8000 Style the docs site and rewrite the evidence pages by rafatahmed · Pull Request #33 · rafatahmed/Flahax · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/site/_static/flahax-mark.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
89 changes: 89 additions & 0 deletions docs/site/_static/flahax.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
/* FlahaX documentation: light touches on top of Furo. */

/* Sidebar brand: mark beside the project name. */
.sidebar-brand {
flex-direction: row;
align-items: center;
gap: 0.6rem;
padding: 1rem var(--sidebar-item-spacing-horizontal);
}
.sidebar-logo-container { margin: 0; }
.sidebar-logo { width: 2.1rem; }
.sidebar-brand-text { font-size: 1.35rem; font-weight: 700; letter-spacing: -0.01em; }

.sidebar-tree .caption,
.sidebar-tree :not(.caption) > .caption-text {
color: var(--color-brand-primary);
letter-spacing: 0.06em;
}

/* Headings. */
article h1 { font-weight: 750; letter-spacing: -0.02em; }
article h2 {
font-weight: 650;
margin-top: 2.4rem;
padding-bottom: 0.3rem;
border-bottom: 1px solid var(--color-background-border);
}
article h3 { font-weight: 600; }

/* Tables: compact, readable, scroll instead of overflow. */
article table.docutils {
display: block;
max-width: 100%;
overflow-x: auto;
border-radius: 0.4rem;
border: 1px solid var(--color-background-border);
box-shadow: none;
font-size: 0.86rem;
}
article table.docutils th {
background: var(--color-background-secondary);
font-weight: 600;
text-align: left;
}
article table.docutils td,
article table.docutils th {
padding: 0.45rem 0.75rem;
border-left: none;
border-right: none;
vertical-align: top;
}
article table.docutils tbody tr:nth-child(even) td {
background: var(--color-background-hover--transparent, transparent);
}
article table.docutils code.literal { white-space: nowrap; }

/* Code blocks. */
.highlight pre { border-radius: 0.4rem; }

/* Landing page. */
.flahax-hero {
margin: 0.5rem 0 1.5rem;
font-size: 1.15rem;
line-height: 1.55;
color: var(--color-foreground-secondary);
}
.flahax-hero strong { color: var(--color-foreground-primary); }
.flahax-badges { margin: 0 0 1.75rem; display: flex; flex-wrap: wrap; gap: 0.4rem; }
.flahax-badges span {
font-size: 0.78rem;
font-weight: 600;
padding: 0.2rem 0.6rem;
border-radius: 999px;
background: color-mix(in srgb, var(--color-brand-primary) 12%, transparent);
color: var(--color-brand-primary);
}

.sd-card {
border-color: var(--color-background-border) !important;
background: var(--color-background-primary) !important;
transition: border-color 0.15s ease, transform 0.15s ease;
}
.sd-card:hover {
border-color: var(--color-brand-primary) !important;
transform: translateY(-2px);
}
.sd-card-title { color: var(--color-brand-primary); font-weight: 650; }
.sd-card-body p:last-child { margin-bottom: 0; }
.sd-card-text { color: var(--color-foreground-secondary); font-size: 0.92rem; }
36 changes: 35 additions & 1 deletion docs/site/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,45 @@
release = __version__
version = __version__

extensions = ["myst_parser"]
extensions = ["myst_parser", "sphinx_design", "sphinx_copybutton"]
source_suffix = {".md": "markdown"}

html_theme = "furo"
html_title = "FlahaX"
html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
html_static_path = ["_static"]
html_css_files = ["flahax.css"]
html_favicon = "_static/flahax-mark.svg"
html_theme_options = {
"light_logo": "flahax-mark.svg",
"dark_logo": "flahax-mark.svg",
"source_repository": "https://github.com/rafatahmed/Flahax/",
"source_branch": "main",
"source_directory": "docs/site/",
"light_css_variables": {
"color-brand-primary": "#1f6b45",
"color-brand-content": "#1f6b45",
"color-brand-visited": "#4a5d8f",
"font-stack": "Inter, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif",
"font-stack--monospace": "'JetBrains Mono', 'SFMono-Regular', Consolas, monospace",
},
"dark_css_variables": {
"color-brand-primary": "#6cc995",
"color-brand-content": "#6cc995",
"color-brand-visited": "#a3b2dc",
},
"footer_icons": [
{
"name": "GitHub",
"url": "https://github.com/rafatahmed/Flahax",
"html": '<svg viewBox="0 0 16 16" aria-hidden="true"><path fill="currentColor" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"></path></svg>',
"class": "",
},
],
}

copybutton_prompt_text = r">>> |\.\.\. |\$ |PS> "
copybutton_prompt_is_regexp = True

myst_enable_extensions = ["colon_fence", "deflist"]
myst_heading_anchors = 3
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -201,8 +201,8 @@ either package, and its own documentation says so.

### Reproducibility

Every number above comes from code run in this session against `flahax` 0.4.0 at
`C:\Users\rafat\repo\Flaha\Flahax` and Horticalc at branch `main` (fetched 17 Oct 2026),
Every number above comes from code run in this session against `flahax` 0.4.0 from
a local checkout of this repository and Horticalc at branch `main` (fetched 17 Oct 2026),
with PHREEQC 3.8.6 via phreeqpython and `minteq.v4.dat` downloaded from the USGS subtree.

**Not assessed:** laboratory or field validation of either package; concentrated stock-tank
Expand Down
81 changes: 63 additions & 18 deletions docs/site/evidence/computational-review.md
Original file line number Diff line number Diff line change
@@ -1,30 +1,75 @@
# G6 computational assessment — 2026-09-27
# Computational assessment (G6)

## Explicit scope amendment
G6 is the release gate for scientific review of the chemistry. This page
records how that gate was met for the planning package, on **2026-09-27**,
before the 0.3.0 release.

The project owner requested mathematical evidence with no laboratory work for this release and designated **Rafat Al Khashan** as assessor. This supersedes the earlier G6 requirement for independent scientific and bench/site sign-off **for the planning-package release only**. The record distinguishes the named assessor from the automated verification evidence: it is not independent review, experimental validation, a formal proof over all possible inputs, or operational dosing certification. Naming the assessor does not fabricate a reviewer signature or laboratory results.
:::{note}
**In short.** The chemistry was accepted on computational evidence alone:
conservation, convergence and agreement with PHREEQC, checked by automated
tests. It was not reviewed by an independent scientist, not tested in a
laboratory or on a site, and is not a proof over all possible inputs or a
dosing certification.

The accepted object is a bounded numerical implementation of the selected source-versioned model, not a claim that every selected equilibrium constant accurately represents every commercial lot. The disclosed Dtp/Edd activity/concentration and stereoisomer assumptions remain in [the source profile](../models/flahax-chelate-thermodynamic-profile.md).
The thermodynamic data assessed here have not changed since (see
[release evidence](release-evidence.md)). Capabilities added later, such as
measured-pH speciation in 0.4.0 and the EC estimate, are covered by their own
release records, not by this assessment.
:::

## Computational acceptance criteria
## Scope

The project owner asked for mathematical evidence with no laboratory work for
this release and named **Rafat Al Khashan** as assessor. This replaces the
earlier G6 requirement for independent scientific and bench or site sign-off,
**for the planning package only**.

The record keeps the named assessor apart from the automated evidence. It is
not independent review, experimental validation, a formal proof over all
possible inputs or operational dosing certification. Naming the assessor does
not stand in for a reviewer's signature or for laboratory results.

What was accepted is a bounded numerical implementation of the selected,
source-versioned model. It is not a claim that every selected equilibrium
constant represents every commercial lot accurately. The assumptions for the
DTPA and EDDHA chelates (`Dtp`, `Edd`) about activity versus concentration and
about stereoisomers are disclosed in the
[chelate extension](../models/flahax-chelate-thermodynamic-profile.md).

## Acceptance criteria

| Criterion | Evidence and assessment |
|---|---|
| Product identity and units | All 28 catalogue products retain declared components. P5.5 matches both ID and name, converts batch salt grams using explicit kg water, and checks mass = g/L × L. No assumed unit-density conversion. |
| Equilibrium conservation | `test_chemistry_acceptance.py` and product/phase regressions enforce per-component 1e-9 relative + 1e-15 mol/kg-water residuals, including ligand and phase inventories. |
| Mass action and convergence | Simultaneous ligand order-invariance/mass-action tests; phase complementarity and finite iteration limits; explicit invalid-domain/nonconvergence errors. Agreement is established for the tested cases, not promised for arbitrary inputs. |
| Independent numerical reference | 21 PHREEQC golden families, raw captures and hashes, charge error <= 0.1%, declared Davies/reference tolerances, both nitrate titration and corrected Fix_H+ target proofs. This is an independently implemented reference calculation, not an independent human review. |
| Reagent/recipe feedback | `test_equilibrium_delivery.py`: HNO3 moles → assayed mass → density-qualified volume → added nitrate-N ppm; target rescoring, zero dose, maximum volume and nutrient tolerances; preservation of measured-curve API. |
| Delivery guards | Missing/contradictory input rejection; source hashes in audit; matching recipe and dedicated acid command/channel; target supersaturation/solid formation prevents validation; post-mix measurement remains required. |
| Distributed package | Wheel and sdist installed separately outside checkout with isolated imports; runtime data/export checks, zero runtime dependencies, numerical APIs and both CLI entry points. `tools/verify_distribution.py` emits observed values and artifact hashes. |
| Reference reproducibility | Fresh administrative extraction of the official pinned MSI into TEMP succeeded; installer, executable and database hashes verified; required-live replay succeeds without skips. Missing required PHREEQC is tested as a hard failure. |
| Product identity and units | All 28 catalogue products keep their declared components. Equilibrium delivery (P5.5) matches products by ID and name, converts batch salt grams using explicit kg of water, and checks mass = g/L × L. No unit density is assumed. |
| Equilibrium conservation | `test_chemistry_acceptance.py` and the product and phase regressions hold each component to a 1e-9 relative plus 1e-15 mol/kg-water residual, including ligand and phase inventories. |
| Mass action and convergence | Tests show simultaneous ligand solutions are independent of order and satisfy mass action; phases meet complementarity within finite iteration limits; invalid domains and non-convergence raise explicit errors. Agreement is shown for the tested cases, not promised for arbitrary inputs. |
| Independent numerical reference | 21 PHREEQC golden families with raw captures and hashes, charge error ≤ 0.1 %, declared Davies and reference tolerances, and both the nitrate titration and the corrected PHREEQC `Fix_H+` target-pH proofs. This is an independently implemented calculation, not independent human review. See [PHREEQC reference fixtures](../models/reference-fixtures.md). |
| Reagent and recipe feedback | `test_equilibrium_delivery.py`: HNO₃ moles → assayed mass → density-qualified volume → added nitrate-N ppm; target rescoring, zero dose, maximum volume and nutrient tolerances; the measured-curve API is preserved. |
| Delivery guards | Missing or contradictory inputs are rejected; source hashes go into the audit; recipe, acid command and channel must match; target supersaturation or solid formation prevents validation; a post-mix measurement is still required. |
| Distributed package | Wheel and sdist installed separately outside the checkout with isolated imports; runtime data and exports, zero runtime dependencies, numerical APIs and both CLI entry points checked. `tools/verify_distribution.py` records observed values and artifact hashes. See [package verification](../api/package-verification.md). |
| Reference reproducibility | A fresh administrative extraction of the official pinned PHREEQC installer succeeded; installer, executable and database hashes verified; the required live replay runs without skips. A missing PHREEQC is tested as a hard failure when the replay is required. |

## Assessment

## Assessment and release boundary
**Assessor:** Rafat Al Khashan, designated by the project owner.

**Assessor:** Rafat Al Khashan (designated by the project owner).
**Result:** the automated evidence passes for the tested, bounded planning
capabilities above, subject to the regression and distribution checks in the
[release evidence](release-evidence.md). The assessment does not certify any
chemistry parameter beyond its documented convention. This record does not
replace a personal signature by the assessor.

**Computational assessment:** the automated evidence passes for the above tested, bounded planning capabilities, subject to the exact regression and distribution checks documented in [release evidence](release-evidence.md). Personal sign-off by the named assessor is not inferred from this designation. The assessment does not certify chemistry parameters beyond their selected documented convention.
**Hosted CI.** When this assessment was written, GitHub Actions could not run
because the repository account was billing-locked, so the Python 3.11 and 3.12
checks had not been observed, and local results were not counted as passes.
That gate has since been met: the 0.4.0 release ran the tests on Python 3.11,
3.12 and 3.13 and the live PHREEQC replay on hosted CI before publication (see
[0.4.0 publication](release-evidence.md#040-publication-2026-10-17)).

**Remote release/merge gate remains separate:** GitHub Actions previously could not start because the repository account was billing-locked. Local results do not turn those failed remote checks into passes. Supported Python 3.11/3.12 remote validation and the new hosted jobs must be observed before claiming the entire CI gate complete. Python 3.13 local tests and installed-distribution checks provide evidence for that interpreter only; Python 3.14 checks are additional.
## What this does not authorize

No publishing, automatic merging, deployment, external database write, pump action, or laboratory certification follows from this document. Optional P7 implementation belongs to the separate FlahaFAST project; it is not a FlahaX package release gate. This repository documents only its consumer boundary.
No publishing, automatic merging, deployment, external database write, pump
action or laboratory certification follows from this document. Integration
with FlahaFAST (P7) belongs to that separate project and is not a FlahaX
release gate; this repository documents only the
[consumer boundary](https://github.com/rafatahmed/Flahax/blob/main/INTEGRATION.md).
Loading
Loading
0