8000 docs: organize public guides and preserve validation history by rafatahmed · Pull Request #34 · 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
20 changes: 20 additions & 0 deletions docs/documentation-maintenance.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,26 @@ validate a published artifact.

## Updating a function

### Public site organization

The public navigation has seven reader-facing sections: Get started, Growers
and agronomists, User manual, API reference, Models and chemistry, Evidence
and audits, and Changelog. Detailed workflow guides belong under the manual;
input schemas and quantity types belong under the API reference. Source
reviews, package verification, and dated validation logs belong under Evidence
and audits. Keep development gates and work-package labels out of navigation
and current usage instructions.

Preserve public page URLs when reorganizing navigation. Preserve historical
results, provenance, model identifiers, failure records, and limitations;
relocation must not turn old local checks into current release acceptance.
The planning logs are retained in
[`planning-validation-history`](site/evidence/planning-validation-history.md);
the superseded pH requirements are retained in
[`ph-planning-requirements`](history/ph-planning-requirements.md).

### API changes

1. Describe its purpose, required inputs, units, defaults, return values and
rejection behavior in its source docstring. Explain distinctions between
missing, zero and unsupported values. Avoid promises beyond tested scope.
Expand Down
26 changes: 26 additions & 0 deletions docs/history/ph-planning-requirements.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Historical pH planning requirements

Archived from the measured-curve guide during documentation reorganization.
The following text is a historical design requirement, not the current API
status or evidence that every proposed boundary is implemented. The current
[water-to-delivery guide](../site/guide/water-to-delivery.md) describes the
implemented equilibrium workflow and its limits. Original wording follows.

## Required mathematical model

The final P3 model must solve aqueous equilibrium directly from the complete solution definition; it must not require a new titration experiment to discover the governing chemistry. Its unknowns include aqueous species activities and reagent amount. Its equations are:

```text
mass action: K_r = product_i(a_i ^ nu_i)
activity: a_i = gamma_i * m_i
electroneutrality: sum_i(z_i * m_i) = 0
alkalinity: Alk = sum_i(alpha_i * m_i)
target condition: -log10(a_H+) = pH_target
phase constraint: SI_p = log10(IAP_p / K_p) <= configured limit
```

The model needs the water and fertilizer totals, temperature, allowed reagent stoichiometry, activity model, thermodynamic database, and a gas boundary: either closed total inorganic carbon or a specified CO2 partial pressure. Without the gas boundary, pH/alkalinity data alone do not uniquely define carbonate speciation, so an exact mathematical solution would be falsely precise.

FlahaX will verify its solver against PHREEQC golden fixtures that contain all those inputs and expected activities, species distribution, saturation indices, and reagent amount. The USGS documentation describes PHREEQC's activity-based speciation and saturation-index calculations, including the distinction between total concentrations and aqueous species activities [PHREEQC Version 3](https://doi.org/10.3133/tm6A43). No new physical laboratory experiment is required to define or regression-test this model.

P3 does not establish a universal hydroponic pH target. Crop, root-zone system, substrate, and operating procedure own the selected setpoint.
2 changes: 2 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ Readers: the documentation is at <https://flahax.readthedocs.io/>. This index is
- [Chelate parameter assumptions](site/models/flahax-chelate-thermodynamic-profile.md)
- [Computational assessment](site/evidence/computational-review.md), [release evidence](site/evidence/release-evidence.md) and [roadmap](implementation-roadmap.md)
- [Audits](site/evidence/audit/README.md): dated independent assessments with maintainer reviews, starting with the 2026-10-17 FlahaX vs Horticalc benchmark.
- [Planning validation history](site/evidence/planning-validation-history.md): dated local checks preserved separately from current usage instructions.

## Maintainers and development

Expand All @@ -61,6 +62,7 @@ Readers: the documentation is at <https://flahax.readthedocs.io/>. This index is
- [Reduced-equilibrium model history](history/reduced-equilibrium-model.md)
- [Chemistry development history](history/full-fertilizer-development.md)
- [Original delivery design](delivery-control-design.md)
- [Historical pH requirements](history/ph-planning-requirements.md): original design wording; the implemented workflow is documented separately.
- [Initial reference kernels](site/models/equilibrium-kernel.md)

Scientific captures and failure reproducers remain in `tests/fixtures/phreeqc/`. Their provenance is retained rather than removed as unused documentation.
12 changes: 12 additions & 0 deletions docs/site/api/reference.md
Original file line number Diff line number Diff line change
@@ -1,2 +1,14 @@
```{include} ../../../src/flahax/data/API_REFERENCE.md
```

## Input schemas and quantities

These references describe the records and units used by the public planning
functions. Validation of a record does not establish physical performance.

```{toctree}
:maxdepth: 1

Input schemas and validation <../guide/delivery-contracts>
Units and batch quantities <../guide/delivery-quantities>
```
3 changes: 2 additions & 1 deletion docs/site/evidence/computational-review.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# Computational assessment (G6)
(computational-assessment-g6)=
# Computational assessment

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**,
Expand Down
69 changes: 69 additions & 0 deletions docs/site/evidence/planning-validation-history.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# Planning validation history

These records were moved from the workflow guides without changing their
reported results. They describe dated local development runs, including failed
attempts, reruns, and checks performed before later edits. They are not current
test counts, hosted release acceptance, independent review, or physical
validation. For version-specific evidence, see [release evidence](release-evidence.md).

## Water-to-delivery validation

Original guide: [water-to-delivery](../guide/water-to-delivery.md).

### Local validation, 2026-09-28

During water-to-delivery development, Windows / Python 3.14.0:

| Command / check | Observed result |
|---|---|
| `PYTHONPATH=src FLAHAX_REQUIRE_PHREEQC=1 python -m unittest discover -s tests -t .` | 121 tests passed in 261.424 seconds; no skips |
| Two subsequently added tests: changed catalogue assay and non-mapping maxima (`tests.test_water_workflow.WaterWorkflowTests`) | Both passed; 123 distinct tests exercised across these runs, not a claimed 123-test single run |
| `python -m unittest tests.test_acid_reference -v` with required PHREEQC | Both golden comparison and live replay passed |
| `.venv-verification/Scripts/python.exe tools/verify_distribution.py --report build/water-workflow-distribution-verification.json` | Clean wheel and sdist installs passed, including four existing manual examples, exports and CLI checks |
| `python -m compileall -q src tools`; `git diff --check` | Passed |

Historical record from the 0.3.1 development increment. The distribution check preceded final documentation-only edits. Its report is
local build evidence, not a release artifact manifest. No new version was
published, no hosted acceptance was claimed and the published 0.3.0 files were
not replaced. Run the current complete suite again before release; these local
results do not waive the normal supported-version/hosted verification gates.


## Site planning validation

Original guide: [site-planning](../guide/site-planning.md).

### Local verification, 2026-09-30

- `PYTHONPATH=src FLAHAX_REQUIRE_PHREEQ 10000 C=1 python -m unittest discover -s tests -t .`:
**149 tests passed, 207.550 s, zero skips** (environment variables set with
`$env:...` in PowerShell). PHREEQC live replay used the existing external
installation; its executable and base database were not modified.
- Initial sandboxed full run: 149 tests, two temporary-directory permission
errors in live PHREEQC replay. The successful full rerun used approved
temporary-directory access; no test or tolerance was removed to pass.
- Focused workflow/examples/source-input tests: 31 passed in 73.327 s.
Final site-input/release-hygiene check: 13 passed in 1.175 s.
- `python -m compileall -q src examples`: passed.
- `git diff --check`: passed (line-ending normalization warnings only).
- `python -m examples.run_all --output build/site-planning-reviewed`: generated
HTML, Markdown and JSON; browser inspection confirmed the calculated EC chart,
unavailable-stock rows and per-channel flow table render correctly.

These checks verify arithmetic, data transcription and rejection boundaries;
they do not establish experimental accuracy of the screening approximation,
validate a concentrated-stock conductivity model, or approve equipment.


## Conductivity validation

Original guide: [conductivity](../guide/conductivity.md).

Local verification on Windows/Python 3.14.0, 2026-09-28: the full suite with
`PYTHONPATH=src` and `FLAHAX_REQUIRE_PHREEQC=1` passed 137 tests in 167.484 s,
with no skips. After the final overflow-safe TDS arithmetic adjustment,
`python -m unittest tests.test_conductivity tests.test_examples tests.test_release_hygiene -q`
passed all 17 tests. Compilation and `git diff --check` passed. Clean wheel
and sdist installation checks passed before that final arithmetic adjustment
(`build/ec-distribution-verification.json`); these are local development checks,
not hosted release approval or a physical EC accuracy certification.
26 changes: 16 additions & 10 deletions docs/site/guide/conductivity.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,14 @@
# Stock and irrigation EC planning
(stock-and-irrigation-ec-planning)=
# EC methods and limitations

FlahaX offers three separate EC methods. Select a method by its input
requirements and scope; a result from one method does not validate another.

| Method | Inputs and scope | Evidence limit |
|---|---|---|
| Manufacturer screening (`flahax ec`) | Exact supported commercial products and water EC, pre-acid at 25 C; see [site inputs](site-planning.md) | Single-product brochure anchors with unvalidated mixture assumptions; no concentrated-stock prediction |
| Measured calibration (`plan_ec_delivery`) | Separate measured profiles for each stock tank and irrigation mixture, matched to recipe and source | Interpolation inside the supplied calibration domain; no extrapolation |
| Calculated irrigation EC (`calculate_irrigation_ec`, `calculate_ec_from_totals`) | Chemical composition and the declared equilibrium boundary; experimental Python API | Computational estimate with stated coverage limits; numerical agreement does not establish field accuracy |

For the new **no-new-measurements** manufacturer-anchor screening path and
interactive CLI, see [site planning](site-planning.md) and the
Expand Down Expand Up @@ -125,7 +135,8 @@ still be reported when EC evidence is missing; that does not approve the recipe
or authorize EC-driven correction. Verify EC after preparation/dilution using
meters rated for the relevant stock and irrigation ranges.

## Calculated irrigation EC (experimental, M2b)
(calculated-irrigation-ec-experimental-m2b)=
## Calculated irrigation EC (experimental)

Purpose: estimate the EC of an irrigation solution before mixing, and compare
it with a meter reading after mixing. This is **experimental (M2b)** and Python
Expand Down Expand Up @@ -240,11 +251,6 @@ exercise the algorithm. Passing these tests proves software behavior, **not**
physical EC accuracy for a commercial formulation. A site or manufacturer
calibration pack with hold-out validation is still required for that claim.

Local verification on Windows/Python 3.14.0, 2026-09-28: the full suite with
`PYTHONPATH=src` and `FLAHAX_REQUIRE_PHREEQC=1` passed 137 tests in 167.484 s,
with no skips. After the final overflow-safe TDS arithmetic adjustment,
`python -m unittest tests.test_conductivity tests.test_examples tests.test_release_hygiene -q`
passed all 17 tests. Compilation and `git diff --check` passed. Clean wheel
and sdist installation checks passed before that final arithmetic adjustment
(`build/ec-distribution-verification.json`); these are local development checks,
not hosted release approval or a physical EC accuracy certification.
Dated development checks are preserved in the
[planning validation history](../evidence/planning-validation-history.md#conductivity-validation).
They record those runs only and do not establish current release validation.
12 changes: 7 additions & 5 deletions docs/site/guide/delivery-contracts.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
# Delivery Planning Contracts (P0)
(delivery-planning-contracts-p0)=
# Input schemas and validation

`flahax.delivery_contracts` provides input validation and provenance for stock-tank, pH, and dosing planning. It validates data and records provenance. It does **not** calculate a stock recipe, pH dose, or pump command, and it does not connect to hardware.

## Current supported mode

Schema version `0.1` supports **batch** planning records only. `proportional` injection is intentionally rejected with error code `unsupported_mode` until decision gate G0 is opened and its calibration/flow model is implemented.
Schema version `0.1` supports **batch** planning records only. `proportional` injection is rejected with error code `unsupported_mode`; this schema does not implement a proportional-injection calibration or flow model.

## Public API

Expand Down Expand Up @@ -49,11 +50,11 @@ The records deliberately preserve their own source/revision metadata. A plan can
## Contract rules

- Water analysis requires ion values and temperature. pH and alkalinity may be recorded when available; the measured-curve pH planner requires alkalinity; the separate equilibrium adapter requires complete analytical totals and measured initial pH.
- Product assays are elemental percentages, not ppm. They reject total `N`, unknown ions, values outside 0–100%, and sums above 100.5%. Acid/base records may also carry sourced `densityKgPerL` and `normalityMeqPerL`; P3 requires both.
- Product assays are elemental percentages, not ppm. They reject total `N`, unknown ions, values outside 0-100%, and sums above 100.5%. Acid/base records may also carry sourced `densityKgPerL` and `normalityMeqPerL`; the measured-curve pH planner requires both.
- Compatibility rules currently represent sourced hard `separate` constraints across two or more product IDs.
- Solubility limits require a product ID, maximum g/L, and minimum/maximum temperature range.
- Titration curves require at least two strictly increasing acid/base demand points in meq/L. They are measurements for one water/reagent pair, not a generic pH formula.
- Pump calibration records require non-zero flow, flow variation, and a valid volume range. They are evidence only; P0 cannot command a pump.
- Pump calibration records require non-zero flow, flow variation, and a valid volume range. They are evidence only; input validation cannot command a pump.

## Errors

Expand All @@ -70,6 +71,7 @@ Invalid records raise `DeliveryError`, a subclass of `InputError`, with a stable
| `unknown_ion` | Assay uses an ion outside the FlahaX ion schema |
| `ambiguous_unit` | Input uses total nitrogen rather than nitrate/ammonium form |

## P0 acceptance evidence
(p0-acceptance-evidence)=
## Validation coverage

The test suite includes a valid batch fixture, deterministic audit replay, rejected unsupported mode, rejected total nitrogen assay, rejected incomplete calibration data, and rejected non-monotonic titration data. The contracts are intentionally strict: a later calculation must receive explicit data or fail with an actionable error.
7 changes: 4 additions & 3 deletions docs/site/guide/delivery-quantities.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# Delivery Quantities and Final-Solution Recipes (P1)
(delivery-quantities-and-final-solution-recipes-p1)=
# Units and batch quantities

P1 adds a small, dependency-free quantity layer for delivery planning. It uses immutable dataclasses with explicit base units and rejects non-finite, negative, ambiguous, or dimensionally wrong values before later stock, pH, or pump logic receives them.
The quantity layer uses immutable dataclasses with explicit base units and rejects non-finite, negative, ambiguous, or dimensionally wrong values before stock, pH, or pump logic receives them.

## Quantities

Expand Down Expand Up @@ -57,4 +58,4 @@ The mass fractions must be elemental fractions from 0 to 1 and cannot total more

## Boundary

P1 does not calculate stock concentration, tank compatibility, reagent normality, pH dose, pump runtime, or hardware commands. Those remain P2–P4 work packages. Its role is to make their inputs dimensionally clear and preserve the original solver balance.
The quantity layer does not calculate stock concentration, tank compatibility, reagent normality, pH dose, pump runtime, or hardware commands. Those calculations belong to their respective planning APIs. Its role is to make their inputs dimensionally clear and preserve the original solver balance.
16 changes: 16 additions & 0 deletions docs/site/guide/manual.md
Original file line number Diff line number Diff line change
@@ -1,2 +1,18 @@
```{include} ../../../src/flahax/data/USER_GUIDE.md
```

## Detailed workflow guides

These guides expand the manual's inputs, result interpretation, and limits.
Each method states which records it requires and what its evidence supports.

```{toctree}
:maxdepth: 1

Water, targets and acid <water-to-delivery>
Site inputs and injector sizing <site-planning>
Stock tank planning <stock-planning>
pH planning with measured titration curves <ph-planning>
EC methods and limitations <conductivity>
Material identity, grade and lot <materials>
```
5 changes: 3 additions & 2 deletions docs/site/guide/materials.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Every number FlahaX calculates with can be traced to a **chemical identity**
and a **source document**. Evidence:
[materials identity audit](../evidence/audit/2026-10-18-materials-identity/review.md).

**Position (owner's wording):** Catalogue size does not measure chemical
Catalogue size does not measure chemical
coverage or model accuracy. FlahaX's chemistry approach uses explicit
chemical identities and composition assumptions. Its raw-material catalogue
should distinguish chemical identity from supplier grade and batch assay,
Expand Down Expand Up @@ -131,7 +131,8 @@ ingredients and counterions.
- An undisclosed blend is accepted by `recommend` (its record) and by
`nutrient_band`.

## Decisions
(decisions)=
## Catalogue composition assumptions

- **D1:** Mg Nitrate is Mg(NO3)2.6H2O theoretical (N 10.93 %, Mg 9.48 %).
- **D2:** Chelates are their defined sodium salts (Fe-EDTA 1, Mn/Zn/Cu-EDTA 2,
Expand Down
Loading
Loading
0