8000 data: adopt the owner catalogue (Flaha Agri Tech Analysis Ver 0.0) by rafatahmed · Pull Request #207 · 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
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,10 @@ each release, with numbers, sources and decisions, are in
equipment alternatives under unchanged targets and limits. Retain candidate
evidence, remaining requirements and honest conditional/budget outcomes (#178).

### Changed

- The packaged catalogue is the owner's Flaha Agri Tech Analysis Ver 0.0: 24 fertilizers, 5 pH products and 13 crop formulas.

### Fixed

- Normalize POSIX mode-inspection/setup/restoration failures and attempt rollback
Expand Down
3 changes: 3 additions & 0 deletions NOTICE
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,9 @@ underlying measurements.
- Product assays from supplier documents named in each record: Haifa
Group (Haifa Cal NG technical data sheet), Sigma-Aldrich (ACS reagent
specifications), ChemicalBook technical data sheets.
- Owner-supplied product analyses and properties: Flaha Agri Tech,
Flaha Agri Tech Analysis Ver 0.0 (2026-10-29), an owner-declared
catalogue review, not independent laboratory or lot verification.
- Chemical identities and theoretical analyses: FlahaX materials audit,
docs/audit/2026-10-18-materials-identity.

Expand Down
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,7 @@ exit 3 for a blocked result. Always inspect the returned qualifications and limi
| Layer | Capability | Boundary |
|---|---|---|
| Formulation | Chooses salts and grams from the full shipped library to meet a fixed crop formula after subtracting the source water | Non-negative least squares; the formula is not altered |
| Equilibrium chemistry | One mixed aqueous model for all 32 catalogue products: 197 aqueous species, 28 solid phases, ion pairs, chelates and saturation indices | 25 °C, Davies activities up to ionic strength 0.1 mol/kg, fixed oxidation states, closed inorganic carbon |
| Equilibrium chemistry | One mixed aqueous model for all 29 catalogue products: 197 aqueous species, 28 solid phases, ion pairs, chelates and saturation indices | 25 °C, Davies activities up to ionic strength 0.1 mol/kg, fixed oxidation states, closed inorganic carbon |
| pH and acid | Calculated initial pH; nitric-acid dose to a target pH; standard workflow with nitric and phosphoric acid, using supplied assay and density | An initial dose estimate; measure after mixing |
| Delivery planning | Stock-tank grouping with compatibility and solubility checks, reagent volumes, pump and injector flow sizing, composed delivery plans | Uses caller-supplied product, compatibility and equipment records; no equipment model selection |
| Conductivity | Approximate EC screening for supported products; EC from a measured calibration profile | Dilute, pre-acid screening with unknown accuracy; no validated concentrated-stock model yet |
Expand Down Expand Up @@ -258,7 +258,9 @@ for FlahaX; conductivity from McCleskey et al. (2012) and Pethybridge et al.
(2006); stock solubility from the CRC Handbook of Chemistry and Physics, Yara
and the U.S. Coast Guard CHRIS database; supplier assays from Haifa,
Sigma-Aldrich and ChemicalBook; concentrate-tank rules from Yara; and crop
formulas from the authors named in the library. The full list, the
formulas from the authors named in the library. The packaged catalogue is Flaha
Agri Tech Analysis Ver 0.0 (owner-supplied, not independent laboratory
verification): 24 fertilizers, 5 pH products and 13 crop formulas. The full list, the
modifications and the USGS User Rights Notice are in
[`NOTICE`](https://github.com/rafatahmed/Flahax/blob/main/NOTICE); the
references are also in `CITATION.cff`.
Expand Down
9 changes: 9 additions & 0 deletions docs/releases/0.7.0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# FlahaX 0.7.0: detailed notes

The full text of every change in 0.7.0, as recorded when each was merged, newest first. The [changelog](../../CHANGELOG.md) groups them into a short summary. 0.7.0 is not yet released.

- The packaged catalogue is the owner's Flaha Agri Tech Analysis Ver 0.0 (Flaha Agri Tech, 2026-10-29; owner-supplied, not independent laboratory verification) (#206). `library.json` holds 29 products, 24 fertilizers and 5 pH products, 13 crop formulas and the 3 waters it held before. Every product carries the analysis review record (`analysisReview`), and the library records the analysis as a whole in `fertilizerAnalysis`. The pH products, all `role: ph_reagent` and never selected as nutrient salts, are Potassium Hydroxide (45% solution), Phosphoric Acid (75%), Nitric Acid (65% solution), Potassium Bicarbonate and Potassium Carbonate; `catalogue_ph_reagents()` returns all five, so `flahax batch` and `flahax mix` now evaluate the two packaged acids beside any acid given with `--acid`. New products: Nitric Acid (65% solution), Micro Combi Mix 1 and Micro Combi Mix 2. Removed products: Ammonium Dibasic Phosphate, Calcium Chloride (Dihydrate), CH - micro (kept as a retired reference in `retiredProductReferences`), Potassium Chloride, Potassium Citrate and Potassium Dibasic Phosphate; the packaged catalogue has no chloride product. Removed formulas: Chilli (maximumyield), Generic Bloom (maximumyield), Generic Dry Season (Howard Resh), Generic Grow (maximumyield), Generic Wet Season (Howard Resh), Generic for Berries (Growing Edge), Rice (Douglas Peckenpaugh) and Tropical Lettuce (Douglas Peckenpaugh). The owner's Potassium Nitrate analysis is 2.57 % out of charge balance against KNO3, above the 1 % label limit, so chemistry stages that include it stop with `identity_inconsistent`; that limit is under review. NOTICE and the attribution test credit Flaha Agri Tech for the analysis.
- Micro Combi Mix 1 and 2 have the owner's declared composition (owner decision 2026-10-30). Fe is Fe(III)-EDTA, Mn, Zn and Cu are EDTA chelates, Mo is sodium molybdate and, in Mix 2, B is boric acid. The sodium counter-ions follow the catalogue's own chelate identities (NaFeEDTA; Na2 Mn, Zn and Cu EDTA; Na2MoO4), and the ion forms are mol/kg from the owner's element percentages. The new identity status `declared_blend` resolves as a disclosed blend without the `assumed_composition` flag (`assumptionStatus`: `declared_composition_not_independently_verified`), and its chemistry source reads "owner-declared composition of" the product. Mix 2's chemistry profile names boric acid among its components (family `edta_boric_acid_molybdate_blend`), as CH-micro's profile names borax.
- Nitric acid is a strong acid in the engine's ion tables: `HNO3` dissociates fully into H+ and nitrate, the proton implicit, as for phosphoric acid. Nitric Acid (65% solution) converts to nitrate from its assay, with no counter-ions; parsing of the existing nitrate salts is unchanged.
- A `flahax batch` or `flahax mix` run whose formulation stage cannot meet a target, with no other stage blocking it, now ends "requires review" (exit 0) and reports the shortfall, for example K at -100 % when a K maximum of 0 forbids every potassium product (owner decision 2026-10-30). Before the owner catalogue such runs ended blocked (exit 3), because no packaged reagent could lower the pH; the packaged acids now give the pH stage a reagent.
- The engine-mechanics tests run on a frozen copy of the pre-owner catalogue (`tests/fixtures/catalogue-pre-owner-33c5df2.json`, the library at commit 33c5df2), entered through `tests.catalogue_history.historical_catalogue()`, so they keep testing the mechanics they were written for. Tests of the packaged catalogue itself run on the owner data.
18 changes: 11 additions & 7 deletions docs/site/agronomist/batch-command.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,11 +82,13 @@ flahax batch --formula "Tomato (Howard Resh)" --water well.json --water-share 8

- `--acid` takes the formula, mass fraction and density (kg/L) from your
certificate, plus an optional name. Repeat it to offer more than one acid.
- If the feed needs raising instead, FlahaX also tries the packaged bases:
potassium hydroxide 45 %, potassium bicarbonate and potassium carbonate.
- FlahaX also tries the packaged pH products: potassium hydroxide 45 %,
potassium bicarbonate and potassium carbonate to raise the pH, and phosphoric
acid 75 % and nitric acid 65 % to lower it.
- `--limit` sets each maximum in the final solution. A maximum also allows that
ion in the recipe up to the limit. For example, `--limit Cl=...` lets FlahaX
use a chloride fertilizer if it helps, while staying under the limit.
use a chloride fertilizer you supply with `--products` if it helps, while
staying under the limit (the packaged catalogue has no chloride product).
- `--volume` sets the batch size (default 1000 L), `--ph` the target pH
(default 5.8) and `--ratio` the injection ratio (default 1:100).

Expand All @@ -98,7 +100,8 @@ FlahaX writes three files into the new folder:
- `summary.json`: the same numbers, for your records or other software.

The command's exit code is 0 for a ready plan or one that needs review, and 3
for a blocked plan.
for a blocked plan. A run whose formulation cannot meet a target, with no other
stage blocking it, ends **Requires review** (exit 0) and reports each shortfall.

## Step 4. Read the batch sheet

Expand Down Expand Up @@ -156,8 +159,8 @@ value on the sheet rather than relying on this arithmetic alone.
### Historical 0.6.0 figures

The following table and quoted doses are retained publication history, not current mixing instructions.
A current run of step 3 is blocked: no reagent is selected, the phosphate EC fit does not
cover the resulting ionic strength, and stock assignment retains three separated tanks.
A current run of step 3 on the packaged catalogue (Flaha Agri Tech Analysis Ver 0.0) is
blocked; read the reasons on its sheet rather than the figures below.
Product chloride can contribute up to the explicit final chloride limit; the water-only
chloride value below is not necessarily the current final concentration.

Expand Down Expand Up @@ -213,7 +216,8 @@ fertilizers do.

**On RO water only** (`--water ro`), the same formula needs 47 mL of nitric
acid per 1000 L: RO water has no bicarbonate, and the mix sits at pH 6.9.
Without an `--acid` the sheet is blocked: no base can lower the pH. A full,
Historically, without an `--acid` the sheet was blocked: no base can lower the pH;
the packaged catalogue now includes phosphoric and nitric acid. A full,
scripted version of the brackish-well example, with charts, is in the
repository (`python -m examples.tomato_report --output tomato-report`).

Expand Down
11 changes: 7 additions & 4 deletions docs/site/agronomist/formula-and-products.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,9 @@ Selection follows the table, per nutrient. Other flags:
band end is widened to include it (grade N-NO3 13.5–13.9 % with a lot at
14.3 % gives the band 13.5–14.3 %).
- `blend_analysis_unreconciled`: see disclosed blends below.
- `assumed_composition`: the shipped CH - micro project-assumed blend.
- `assumed_composition`: a project-assumed blend, such as the pre-owner catalogue's
CH - micro. The packaged Micro Combi Mix 1 and 2 are owner-declared blends and do
not carry it.

## Using materials in calculations

Expand Down Expand Up @@ -140,7 +142,8 @@ ingredients and counterions.
- **D2:** Chelates are their defined sodium salts (Fe-EDTA 1, Mn/Zn/Cu-EDTA 2,
Fe-DTPA 2, Fe-o,o-EDDHA 1 sodium per formula unit). Sodium enters chemistry
totals only; it is not added to formulation `elements`, because Na is a
restricted ion there. CH - micro's assumed chelates carry the same sodium.
restricted ion there. The owner-declared Micro Combi Mix 1 and 2 chelates carry
the same sodium.
- **D3:** Reference grades may name commercial products with attribution and a
document reference.

Expand Down Expand Up @@ -203,8 +206,8 @@ result also carries `identitiesSha256`, which pins the shipped catalogue.
`solve_weights` and `forward` use the shared nutrient inventory.

**Counterion sodium in formulation rows.** Supported formula counterion sodium
not already assayed as elemental Na (chelate sodium and CH - micro's borax and
molybdate sodium) enters the matrix before fitting. It affects the selected doses
not already assayed as elemental Na (chelate sodium and the molybdate sodium of
the Micro Combi blends) enters the matrix before fitting. It affects the selected doses
and the resulting Na row, including a supplied Na target or maximum. The source
`elements` and existing eligibility/permission policy remain unchanged. A warning
identifies the selected products' counterion sodium contribution.
Expand Down
7 changes: 4 additions & 3 deletions docs/site/agronomist/reading-results.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,9 +42,10 @@ that matches exactly one formula name and lists the matches otherwise. Use
| `--rules` | JSON array of extra `compatibilityRule` records | none |
| `--output` | a new directory; existing paths are never overwritten | required |

The packaged bases (potassium hydroxide 45 %, potassium bicarbonate, potassium
carbonate) are always evaluated, so a feed that mixes below the target pH gets a
base. The exit code is 0 for a ready or review plan, 3 for a blocked plan and 1
The packaged pH products (potassium hydroxide 45 %, potassium bicarbonate and
potassium carbonate to raise the pH; phosphoric acid 75 % and nitric acid 65 % to
lower it) are always evaluated, so a feed that mixes off the target pH gets a
reagent in the needed direction. The exit code is 0 for a ready or review plan, 3 for a blocked plan and 1
for an input error.

### Water analysis file
Expand Down
2 changes: 1 addition & 1 deletion docs/site/developer/python-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -251,7 +251,7 @@ From the repository root, after the package is installed:
python -m unittest discover -s tests -t .
```

`test_pepper.py` checks water subtraction, the edited pepper fit, and the forced double-phosphate miss. `test_library.py` checks that the curated catalogue has 32 salts, 3 waters, and 21 formulas, then calls `recommend` once per formula. `test_measured_water.py` checks measured-pH water balancing on a published Qatar well. Set `FLAHAX_REQUIRE_PHREEQC=1` to make the live PHREEQC replay fail rather than skip when the pinned executable is missing.
`test_pepper.py` checks water subtraction, the edited pepper fit, and the forced double-phosphate miss. `test_library.py` checks that the packaged catalogue (Flaha Agri Tech Analysis Ver 0.0, owner-supplied, not independent laboratory verification) has 29 products (24 fertilizers and 5 pH products), 3 waters, and 13 formulas, then calls `recommend` once per formula. `test_measured_water.py` checks measured-pH water balancing on a published Qatar well. Set `FLAHAX_REQUIRE_PHREEQC=1` to make the live PHREEQC replay fail rather than skip when the pinned executable is missing.

### Chemistry failure and compatibility contract

Expand Down
6 changes: 3 additions & 3 deletions docs/site/developer/verification.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ To retain only artifacts that passed clean-install checks, use `python tools/ver

## Installed distributions

Run `python -m pip install build` in a development virtual environment, then `python tools/verify_distribution.py`. The tool builds wheel and sdist (wheel from sdist), installs each non-editably in a separate temporary virtual environment, runs from outside the checkout with `-I` and without `PYTHONPATH`, and asserts the imported package is inside that environment. It verifies zero runtime dependencies, 32 catalogue products, the exact chemistry resource hash, catalogue solve, nitric target, equilibrium delivery adapter, and both `python -m flahax` and `flahax` CLI entry points. A JSON report containing distribution hashes and observed numerical values is written to `build/distribution-verification.json`. Nothing is published.
Run `python -m pip install build` in a development virtual environment, then `python tools/verify_distribution.py`. The tool builds wheel and sdist (wheel from sdist), installs each non-editably in a separate temporary virtual environment, runs from outside the checkout with `-I` and without `PYTHONPATH`, and asserts the imported package is inside that environment. It verifies zero runtime dependencies, the catalogue product count (29 in the packaged catalogue), the exact chemistry resource hash, catalogue solve, nitric target, equilibrium delivery adapter, and both `python -m flahax` and `flahax` CLI entry points. A JSON report containing distribution hashes and observed numerical values is written to `build/distribution-verification.json`. Nothing is published.

The source distribution now includes offline fixture inputs/outputs, extensions and reproduction tools as well as tests; the wheel includes runtime Python and JSON resources only. Neither contains PHREEQC binaries. Python 3.11–3.13 CI runs source regression and clean distribution smoke checks. Local Python 3.14 testing is additional evidence, not a substitute for that matrix.

Expand Down Expand Up @@ -186,7 +186,7 @@ from flahax import (load_library, final_solution_recipe, VolumeLitres,
plan_equilibrium_delivery)

products = {p['name']: p for p in load_library()['salts']}
doses = {'Potassium Carbonate': 0.01, 'Potassium Nitrate': 0.02} # g/kg water
doses = {'Potassium Carbonate': 0.01, 'Potassium Sulfate': 0.02} # g/kg water
recipe = final_solution_recipe({'feasible': True, 'salts': [
{'id': products[name]['id'], 'name': name, 'gramsPerLitre': dose * 95 / 100}
for name, dose in doses.items()
Expand All @@ -202,7 +202,7 @@ plan = plan_equilibrium_delivery(
'revision': '1', 'recordedAt': '2026-09-27T00:00:00Z',
'name': 'Nitric acid', 'kind': 'acid', 'chemicalFormula': 'HNO3',
'elements': {'N_NO3': 13.8}, 'densityKgPerL': 1.4},
maximum_reagent_volume=VolumeLitres(0.1), targets={'K': 12.72},
maximum_reagent_volume=VolumeLitres(0.1), targets={'K': 13.9},
maximum_nutrient_error_percent=1,
)
print(plan.reagent_volume_litres, plan.nutrient_contribution, plan.warnings)
Expand Down
3 changes: 2 additions & 1 deletion docs/site/evidence/competitor-comparison.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

> Historical benchmark inputs include five presets retired under #202. Their
> inclusion tested numerical behavior; it did not validate crop recommendations.
> Raw captures are preserved. The current catalogue contains 21 formulas.
> Raw captures are preserved. The current catalogue, Flaha Agri Tech Analysis Ver 0.0
> (owner-supplied, not independent laboratory verification), contains 13 formulas.


**Measured snapshot: 2026-10-22-competitors-1ade5b6.** One run on one Windows
Expand Down
2 changes: 1 addition & 1 deletion docs/site/models/fertilizer-equilibrium-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ and chemistry components, with explicit incomplete/composition-disagreement fiel

The generated `data/chemistry_25c.json` stores the exact master-basis expansion of 197 aqueous entries and 28 phases from pinned MINTEQ plus two extensions. [Every reaction](chemistry-coverage-matrix.md) has its original equation, log K and source line. `LIGAND_PROFILES` is derived from that file, not an independently rounded table.

All 28 catalogue products have explicit records. Fe-DTPA and Fe-o,o-EDDHA supply one ligand per Fe(III), with no other Dtp/Edd metal families. Fe/Mn/Zn/Cu-EDTA products and CH-micro supply their declared EDTA equivalents; CH-micro also supplies borax and sodium molybdate. Citrate supplies one ligand per three K. Urea remains neutral (two N per molecule); potassium carbonate supplies one inorganic carbon per two K. Assayed nitrate/sulfate/sodium are never added again as inferred counterions. Ferrous sulfate preserves Fe(II).
All 29 packaged catalogue products (Flaha Agri Tech Analysis Ver 0.0, owner-supplied, not independent laboratory verification) have explicit records. Fe-DTPA and Fe-o,o-EDDHA supply one ligand per Fe(III), with no other Dtp/Edd metal families. Fe/Mn/Zn/Cu-EDTA products and the owner-declared Micro Combi Mix 1 and 2 supply their declared EDTA equivalents; both blends also supply sodium molybdate, and Mix 2 supplies boric acid. Nitric and phosphoric acid supply nitrate and phosphate with an implicit proton. A potassium citrate product you supply carries one ligand per three K. Urea remains neutral (two N per molecule); potassium carbonate supplies one inorganic carbon per two K. Assayed nitrate/sulfate/sodium are never added again as inferred counterions. Ferrous sulfate preserves Fe(II).

Rounded elemental assays do not specify every unlabelled counterion. Fixed-pH results report `charge_balance` and do not claim automatic electroneutrality. References declare NaCl background and charge-adjust Na while retaining all pr 5A59 oduct totals. Site use requires complete water/assay data. The legacy field `inert_mass_fraction` means unassayed elemental remainder, including oxygen/hydration/carrier, **not** measured inert carrier.

Expand Down
Loading
Loading
0