8000 Hardening 2/4: every error code explained; clear messages for unusable formulas by rafatahmed · Pull Request #119 · 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
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

## Unreleased

- Every error code is explained (hardening 2/4). The shipped user guide gains an error code reference: all 91 `DeliveryError` codes, grouped by what you were doing (input values and files, water analysis, products and materials, recipe and pH, chemistry model, stocks and injection, delivery plans and EC), each with its meaning and what to do; 68 were undocumented. `tests/test_error_catalogue.py` fails if a raised code is missing from the guide. A material whose formula cannot be used now says why: it cannot be read (check the brackets and the element symbols), has fractional atoms, does not split into the fertilizer ions FlahaX knows, or splits in more than one way; it said 'give its formula' even when one was given. The exception audit found no other user-facing exception outside `InputError` and `DeliveryError`: the remaining `TypeError`s are argument-type checks, the `AssertionError`s belong to the reference-fixture comparison helper, and the internal `ValueError`s are caught and re-raised.
- Entry points refuse bad input with a plain message instead of a traceback (#117, from the entry-point audit). `flahax batch --ratio 0` crashed with a ZeroDivisionError; every number option is now checked at the command line with its range (`--ratio`, `--volume` and `--max-reagent-litres` above 0, `--ph` 0-14, `--water-share` above 0 up to 100). Every JSON file (water, targets, products, rules, saved items and sessions) and JSON on stdin is read by one reader that names the file and the line and column (`missing_file`, `invalid_json`); a water value that is not a number, or a non-numeric `--acid` assay or density, is named in the message. The `flahax batch` terminal shows the acid with the same 0.1 mL rounding as the sheet and report.
- Package identity and attribution (owner decisions 2026-10-23). Metadata: author Rafat A. Al Khashan with public contact email, maintainers Rafat A. Al Khashan and Flaha Agri Tech (affiliation), a description that names the grower command and the A/B stock planning, fuller keywords, Development Status 4 - Beta, Console and end-user audiences, Python 3.14 (now also in CI), and Changelog, Citation and Growers-guide links. NOTICE now credits every data source the package ships (USGS PHREEQC 3.8.6 minteq.v4.dat and pitzer.dat, the FlahaX chelate and phase extensions, McCleskey et al. 2012, Pethybridge et al. 2006, the CRC Handbook, Yara, the U.S. Coast Guard CHRIS database, Haifa, Sigma-Aldrich, ChemicalBook, SQM and the crop-formula authors) and reproduces the USGS User Rights Notice, which applies to PHREEQC data: it requires modified data to say what changed, by whom and when, so chemistry_25c.json and NOTICE now carry that statement (the sylvite constant, from pitzer.dat, was not credited before). CITATION.cff gains a current abstract, release date, affiliation, contact and a references list checked against Crossref. The README gains an Author and credits section; `tests/test_attribution.py` fails if a shipped data source is not credited. Zenodo archiving is documented as an owner step in the publishing procedure.
- Fix what the pre-release sweep of `flahax mix` found (19 farmer sessions, each checked across terminal, sheet at every depth and report): an unknown acid formula ('1') was accepted and the acid then silently ignored, so the plan said none was offered (#112); `flahax mix` now asks again and `flahax batch --acid` stops with the list of acids FlahaX plans with (HNO3, H3PO4, H2SO4, C6H8O7; any case). A blocked pH plan repeated its review notes (#113): a chemistry review row or advisory is listed only when not already said. A changed or new formula was titled with its file name (#114): the name typed is kept in the session and used as the title.
Expand Down
89 changes: 89 additions & 0 deletions src/flahax/data/USER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -244,6 +244,95 @@ A plan or state label does not execute hardware or prove physical mixing occurre

Python callers should handle `InputError` for formulation and `DeliveryError` (with its stable `code`) for planning. Retain input provenance and rejection reasons.

### Error code reference

Every `DeliveryError` carries one of these codes; its message names the value or file at fault. Codes above are not repeated. A test keeps this list complete.

**Input values and files**

| Code | Meaning | What to do |
|---|---|---|
| `invalid_value` | A number or text is out of its allowed range or form (for example a negative volume, a pH outside 0-14, a duplicate ID). | Correct the named value. |
| `invalid_type` | A value has the wrong kind (a list where a mapping is needed, text where a number is needed). | Supply the kind the message names. |
| `missing_field` | A required input is absent (targets, reagent records, a document field). | Add the named field. |
| `unknown_field` | A key is not recognised, for example an unsupported water key. | Use the keys the message lists. |
| `out_of_range` | A physical input is outside what the model accepts (pH, ionic strength, concentrations). | Check units and values; FlahaX does not extrapolate. |
| `unknown_ion` | A nutrient or ion symbol is not one FlahaX knows. | Use N_NO3, N_NH4, P, K, Ca, Mg, S, Fe, Mn, Zn, Cu, B, Mo, Na, Cl. |
| `invalid_ions` | A water or nutrient profile for a quantity conversion is not a valid map of ion symbols to mg/L. | Correct the profile the message names. |
| `ambiguous_unit` | A quantity could be read two ways, such as total N. | Split it as the message says (N_NO3 and N_NH4). |
| `unknown_formula` / `ambiguous_formula` | `--formula` names no packaged formula, or `--crop` matches several. | Use `--list-formulas` and give the exact name. |
| `unknown_item` | `flahax mix` cannot find a saved session or item. | Run `flahax mix sessions` to list them. |
| `unknown_command` | Not one of `workflow`, `ec`, `size`. | Use one of those. |

**Water analysis**

| Code | Meaning | What to do |
|---|---|---|
| `incomplete_water_analysis` | The chemistry needs a complete analysis declared as complete. | Supply every measured ion and mark the analysis complete. |
| `inconsistent_water_analysis` | Two water inputs disagree (formulation mg/L against chemistry totals, or titration water against formulation water). | Use one analysis for every stage. |
| `invalid_totals` | Analytical totals are not a mapping of known components to non-negative numbers. | Correct the named component. |
| `alkalinity_exhausted` | The report has no chloride and is so far out of balance that closing on the alkalinity would need negative carbonate. | Check the analysis with the laboratory; ask for chloride and alkalinity. |
| `unsupported_carbon_boundary` | Calculated pH needs inorganic carbon treated as closed. | Use `carbon_boundary='closed'`. |
| `ph_not_bracketed` | No charge-balanced pH exists between 0 and 14 for these totals. | The inputs are inconsistent; check the analysis and doses. |

**Products and materials**

| Code | Meaning | What to do |
|---|---|---|
| `invalid_composition` | A material's ions, chelating agent or blend components are not consistent. | Correct the ions, agent or components named. |
| `unknown_identity` | A grade names a chemical identity FlahaX does not ship. | Use an identity from the catalogue, or define the material by formula or ions. |
| `material_mismatch` | A grade, lot or material record does not match the product it is attached to. | Attach it to the product it describes. |
| `product_chemistry_mismatch` | A product record differs from its catalogue identity without a grade that explains it, or a compound's id is not its grade id. | Give the label as a grade, or use the catalogue record unchanged. |
| `unsupported_product_chemistry` | No chemistry can be built for the product (unknown name, or phosphate without its form). | Define it by formula, ions or a complete data-sheet analysis. |
| `composition_undisclosed` | A blend of undisclosed composition is used for chemistry. | Enter it from its data sheet, or use it for nutrients only. |
| `catalogue_chemistry_mismatch` | The packaged catalogue and its chemistry records disagree (a packaging fault). | Report it as a bug. |
| `missing_document_reference` | A supplier grade lacks its document (supplier, title, date). | Add the data-sheet reference. |
| `inconsistent_assay` | An assay is impossible (mass fraction above one, more nitrate than pure nitric acid). | Check the certificate values. |
| `invalid_identity_record` | A packaged identity record is malformed (a packaging fault). | Report it as a bug. |

**Recipe, limits and pH**

| Code | Meaning | What to do |
|---|---|---|
| `infeasible_recipe` | A stage needs a recipe that meets its targets, and this one misses them or breaks a declared maximum. | Read the formulation reason; adjust targets, products or limits. |
| `nutrient_limit_exceeded` | A plan exceeds a maximum you declared. | Lower the source of that nutrient or the water share; the limit is never relaxed for you. |
| `incidental_review_required` | Nutrients the formula did not ask for have no declared maximum, so the plan cannot be validated. | Declare maxima for them, or accept the review. |
| `unsupported_reagent` | The pH reagent is not one FlahaX models. | Use HNO3, H3PO4, H2SO4 or C6H8O7 (acids) or the packaged bases. |
| `dose_limit_exceeded` | The reagent dose exceeds the volume or the limit you set. | Raise the limit only if the equipment allows, or change the target pH. |
| `missing_measurement` | A measured value is needed (reagent density, water pH and alkalinity). | Measure it and supply it. |
| `outside_titration_range` | The target pH lies outside the measured titration curve. | Extend the titration, or choose a target inside it. |
| `mismatched_record` | A titration curve or pump channel belongs to another water or stock. | Use the records that belong together. |

**Chemistry model**

| Code | Meaning | What to do |
|---|---|---|
| `nonconvergent` | The equilibrium solver did not converge. | Report the inputs as a bug; FlahaX never returns an unconverged answer. |
| `temperature_out_of_range` / `unsupported_temperature` / `temperature_outside_reference` / `temperature_reference_mismatch` | The chemistry and conductivity data are for 25 °C. | Use 25 °C for chemistry; stock solubility uses your temperature separately. |
| `unknown_phase` / `missing_species` | A mineral or species is not in the pinned reaction set. | Use phases from the shipped set. |
| `unsupported_ionic_strength` | Outside the dilute model (ionic strength above 0.1). | Do not apply the dilute model to concentrated stock. |
| `unsupported_legacy_input` | An old input form that a newer function replaces. | Use the function the message names. |

**Stocks, tanks and injection**

| Code | Meaning | What to do |
|---|---|---|
| `capacity_exceeded` | Every tank is smaller than the stock volume needed. | Use larger tanks or a higher injection ratio. |
| `solubility_exceeded` / `missing_solubility_limit` | A stock exceeds its solubility, or has no limit at that temperature (stock planner). | Dilute (lower ratio), warm the stock room, or supply the limit. |
| `no_stock_assignment` | No tank arrangement satisfies the compatibility rules. | Add a tank or change products. |
| `invalid_ratio` / `ambiguous_volume` / `unknown_equipment_type` | Injection sizing inputs are inconsistent. | Correct the ratio, give one volume form, choose dosing_pump, venturi or dosatron. |
| `dry_tank_risk` / `out_of_calibration_range` | The stock cannot supply the planned injection, or the pump is asked outside its calibration. | Prepare more stock or recalibrate. |
| `inconsistent_recipe` | Recipe, stocks and products refer to different items (duplicates, missing products). | Rebuild the plan from one recipe. |

**Delivery plans, EC and reference data**

| Code | Meaning | What to do |
|---|---|---|
| `cross_stage_constraint` / `incomplete_plan` / `invalid_plan_transition` | A delivery plan's stages do not belong together, a stage is missing, or a state change is not allowed. | Build every stage from the same recipe and follow the plan states. |
| `invalid_ec_profile` / `mismatched_ec_profile` / `outside_ec_calibration` / `ambiguous_ec_input` / `unknown_channel` | A measured EC calibration is malformed, belongs elsewhere, or is asked outside its range; or EC and TDS were both given. | Supply one complete calibration for this recipe, channel and water, and one reading. |
| `invalid_ph_input` / `invalid_phase_policy` / `incomplete_prediction` / `invalid_audit_inputs` | Calculated-EC options conflict. | Follow the option rules in the message. |
| `invalid_fixture` | A PHREEQC reference fixture is unreadable or of an unsupported schema (verification tooling). | Recapture the fixture with the pinned PHREEQC. |

## 9. Verification and reproducibility

From an installed development checkout, run `python -m unittest discover -s tests -t .` and `python -m compileall -q src tools`. Use `PYTHONPATH=src` if the checkout is not installed. Reference acceptance also requires the pinned external PHREEQC run with `FLAHAX_REQUIRE_PHREEQC=1`; the executable is never a runtime package dependency.
Expand Down
23 changes: 22 additions & 1 deletion src/flahax/material_chemistry.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@

import json
import math
import re
from collections.abc import Mapping
from functools import lru_cache

Expand Down Expand Up @@ -146,6 +147,26 @@ def ions_from_formula(formula) -> dict | None:
return dict(ions) if ions is not None else None


def formula_problem(formula) -> str:
"""Why a formula cannot define a material, in words a grower can act on."""
text = formula.strip() if isinstance(formula, str) else ''
if not text:
return UNDEFINED
if not re.fullmatch(r'[A-Za-z0-9().·]+', text):
return f'{text!r} is a name, not a chemical formula: {UNDEFINED}'
parsed = parse_formula(text.replace('·', '.'))
if parsed is None:
return (f'the formula {text!r} cannot be read: check the brackets and the element symbols '
'(for example Ca(NO3)2·4H2O)')
if not all(float(n).is_integer() for n in parsed['atoms'].values()):
return f'the formula {text!r} has fractional atoms; give its ions or its analysis instead'
solutions = _decompose({e: int(n) for e, n in parsed['atoms'].items()})
if not solutions:
return (f'the formula {text!r} does not split into the fertilizer ions FlahaX knows; '
'give its ions or its analysis instead')
return f'the formula {text!r} splits into ions in more than one way; give its ions instead'


def _checked_ions(name: str, ions, agent: str | None = None) -> dict:
"""Known ions with positive counts (metals of ``agent`` chelated) that balance."""
if not isinstance(ions, Mapping) or not ions:
Expand Down Expand Up @@ -245,7 +266,7 @@ def _resolve(key: str) -> ProductChemistry:
else:
ions = ions_from_formula(formula)
if ions is None:
raise DeliveryError('material_undefined', f'{name}: {UNDEFINED}')
raise DeliveryError('material_undefined', f'{name}: {formula_problem(formula)}')
ions = _checked_ions(name, ions)
_check_analysis(name, ions, elements)
return _profile(name, ions, status)
Expand Down
45 changes: 45 additions & 0 deletions tests/test_error_catalogue.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
"""Every error code a user can meet is explained in the shipped user guide (hardening 2/4)."""
from importlib.resources import files
from pathlib import Path
import re
import unittest

from flahax.delivery_contracts import DeliveryError
from flahax.material_chemistry import material_chemistry

ROOT = Path(__file__).resolve().parents[1]
RAISED = re.compile(r"DeliveryError\(\s*['\"]([a-z_]+)['\"]")


def raised_codes():
codes = {}
for path in sorted((ROOT / 'src' / 'flahax').glob('*.py')):
for code in RAISED.findall(path.read_text(encoding='utf-8')):
codes.setdefault(code, path.name)
return codes


class ErrorCatalogueTests(unittest.TestCase):
def test_every_raised_code_is_in_the_user_guide(self):
guide = files('flahax').joinpath('data/USER_GUIDE.md').read_text(encoding='utf-8')
documented = set(re.findall(r'`([a-z][a-z_]+)`', guide))
missing = {code: module for code, module in raised_codes().items() if code not in documented}
self.assertEqual(missing, {}, 'explain these codes in USER_GUIDE.md, section 8')

def test_a_mistyped_formula_says_what_is_wrong(self):
cases = (('Ca(NO3', 'cannot be read: check the brackets'),
('KXx3', 'cannot be read'),
('C6H12O6', 'does not split into the fertilizer ions FlahaX knows'))
for formula, said in cases:
with self.subTest(formula=formula), self.assertRaises(DeliveryError) as caught:
material_chemistry({'name': 'My salt', 'formula': formula, 'elements': {}})
self.assertEqual(caught.exception.code, 'material_undefined')
self.assertIn(said, str(caught.exception))
self.assertNotIn('give its formula, its ions', str(caught.exception))
with self.assertRaises(DeliveryError) as caught:
material_chemistry({'name': 'My salt', 'elements': {}})
self.assertIn('give its formula, its ions, or its analysis', str(caught.exception))


if __name__ == '__main__':
unittest.main()
4 changes: 3 additions & 1 deletion tests/test_material_chemistry.py
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,9 @@ def test_a_name_alone_is_not_a_material(self):
with self.assertRaises(DeliveryError) as caught:
material_chemistry(record)
self.assertEqual(caught.exception.code, 'material_undefined')
self.assertIn(f'Mystery: {UNDEFINED}', str(caught.exception))
self.assertIn(UNDEFINED, str(caught.exception))
if 'formula' in record: # a trade name typed where the formula belongs
self.assertIn("'Ch micro' is a name, not a chemical formula", str(caught.exception))

def test_counterions_follow_the_ions_not_the_name(self):
products = {'My potash': {'name': 'My potash', 'formula': 'K2CO3', 'elements': {'K': 56.58}},
Expand Down
Loading
0