Plant-nutrient chemistry engine in Python: fertilizer formulation, aqueous equilibrium chemistry and auditable delivery planning.
FlahaX turns a crop's nutrient formula and the grower's actual water into a fertilizer recipe, then checks what that recipe does in solution: which ions pair up, whether anything precipitates, what the pH will be, how much acid reaches a target pH, and how the recipe splits into stock tanks and injector flows. Every plan carries its units, model identifiers and source hashes, so a result can be reviewed and reproduced.
To our knowledge, FlahaX is the first Python package to unite fertilizer formulation, fertilizer-specific aqueous equilibrium chemistry and auditable delivery planning in one dependency-free library, verified against PHREEQC.
Who it is for
- Growers and agronomists:
flahax mixasks five questions and gives tank A, tank B and the acid, with no code. - Consultants and researchers: reproducible nutrient-solution chemistry with stated validity limits, against real water analyses and real commercial products.
- Developers: a tested, dependency-free engine for nutrition and fertigation software.
For changes from published recipes to this development checkout, see the migration guide. Recalculate and review saved results; acceptance does not transfer to changed inputs or sources.
Python 3.11 or newer. There are no third-party runtime dependencies.
python -m pip install flahax==0.6.0Pin the version for reproducible work; python -m pip install flahax installs the latest
release. To upgrade, and to check what is installed:
python -m pip install --upgrade flahax
flahax --versionOne version lives in each Python environment; to keep an older one for comparison, install it in its own virtual environment.
To try unreleased changes from GitHub, reinstall rather than upgrade: between releases every
commit on main has the same development version, so --upgrade can keep the files you already
have (#134):
python -m pip install --force-reinstall --no-deps "git+https://github.com/rafatahmed/Flahax.git@main"flahax mix asks five things in order: tank sizes and injection ratio, the water analysis as
printed by the lab, the crop formula, the fertilizers you have, and the target pH. It shows what
to weigh into tank A and tank B and how much acid goes in the acid container, writes a batch
sheet, and saves the answers so the next batch is one command:
flahax mix # first time: answer the five steps
flahax mix sessions/my-tomato # next time: no questionsIn a terminal it opens full screen: arrow keys and Enter choose, typing filters a long list,
Space ticks your fertilizers, and the result has three views (Tanks, Nutrients, Notes) switched
with Tab. flahax mix --plain asks line by line instead, and scripts and pipes get the
line-by-line mode automatically. See
For growers and agronomists.
The same from files, for scripts:
flahax batch --formula "Tomato (Howard Resh)" --water ro --ph 5.8 --acid HNO3:0.60:1.37 --output tomatoIt writes batch-sheet.html, report.html and summary.json. flahax batch --help lists every
option, including a measured water analysis and --water-share for blending it with RO water.
Select salts for a crop formula, with 20 mg/L of calcium already in the water:
from flahax import load_library, recommend
result = recommend(
load_library()["salts"],
targets={"N_NO3": 128, "P": 58, "K": 211, "Ca": 104, "Mg": 40, "S": 54},
water={"Ca": 20},
)
for salt in result["salts"]:
print(f"{salt['name']}: {salt['gramsPerLitre']} g/L")result["salts"] lists each chosen salt with grams per litre of the solution the plant receives.
result["rows"] gives each element's target, final concentration (mg/L) and percentage
difference. Element keys are N_NO3, N_NH4, P, K, Ca, Mg, S, Fe, Mn, Zn, B,
Cu and Mo.
| Command | What it does |
|---|---|
flahax mix |
Five questions to tank A, tank B and the acid, with a batch sheet (growers, agronomists) |
flahax batch |
The same from files in one command, for scripts |
flahax (or flahax recommend) |
Reads a JSON request (salts, targets, water) on stdin and writes a recipe |
flahax workflow |
Plans a full workflow from a JSON request, or with --interactive |
flahax ec |
Screens the EC of supported products before acid |
flahax size |
Sizes injector channel volumes and flows |
flahax --help shows every command with examples. Commands plan; they never operate pumps,
valves or other hardware.
recommend accepts the Python API's explicit maximum_concentrations and other
fit options; unknown JSON fields are rejected. Exit 0 means a calculation was
returned, not that it is feasible or physically validated. batch and mix use
exit 3 for a blocked result. Always inspect the returned qualifications and limits.
| 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 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 |
| Audit trail | Explicit units (g/L of final solution versus g/kg water), model identifiers, source hashes, needs_input instead of guessed values |
Plans are reviewable records, not operating authorizations |
| Document | For |
|---|---|
| Documentation site | Guides for growers, agronomists and developers |
| User manual | Installation, tested examples, units, chemistry, pH, delivery planning and troubleshooting |
| API reference | Every public function and result record, with signatures |
| Chemistry model | Equilibrium model, PHREEQC evidence and boundaries |
| Formulation method | The ppm equation, solver and worked pepper example |
| Changelog | Changes by release |
The manual can also be read offline from an installed package through importlib.resources
(flahax/data/USER_GUIDE.md).
| Problem | Fix |
|---|---|
| A feature is missing after installing from GitHub | Reinstall with --force-reinstall --no-deps (see Installation above) and check flahax --version. |
flahax is not recognised as a command |
Run python -m flahax, or add the folder pip names in its "user installation" warning to your PATH. |
flahax mix asks line by line instead of full screen |
Run it in Windows Terminal, PowerShell, cmd or a Linux or macOS terminal; an editor's output panel or Git Bash is not a full-screen console. |
An error code such as invalid_json or charge_imbalance_exceeded |
Every code is explained in the manual's error reference. |
More in the manual's
troubleshooting section.
If something still looks wrong, open an issue with
flahax --version and the command you ran.
The Benchmark v1 protocol separates formulation fit, numerical chemistry, runtime and memory, and physical validation; the measured results come with tables, charts, provenance and their limitations.
- The automated test suite includes live replay of every catalogue product, phase and acid case against pinned PHREEQC 3.8.6 (USGS).
- Hosted checks run on Python 3.11, 3.12, 3.13 and 3.14 on Linux, and on Windows and macOS, with clean wheel and source installations.
- Evidence is recorded per release in the release evidence.
This is computational evidence. FlahaX has not been validated in the laboratory or in the field (a validation protocol is in draft), and its author's computational assessment is not an independent review. Results are calculations for planning, not dosing instructions: measure pH and EC after mixing. No recipe, pH or EC value is an authorization to operate equipment.
Roadmap. Broader numerical and input-boundary testing, stable consumer contracts, physical validation, and a validated conductivity model for irrigation-strength solutions first and concentrated stock tanks second. See the development roadmap. FlahaX is developed as the chemistry engine for the FlahaFAST application; that integration is not yet in place, and FlahaX stays a standalone package with its own releases.
Contributions are welcome. Read CONTRIBUTING for branch names, code style, the changelog format and the validation each change needs, and the code of conduct. Report security problems privately, as SECURITY.md explains.
From a source checkout:
python -m pip install -e .
python -m unittest discover -s tests -t .Live PHREEQC replay and distribution verification are described in package verification.
Al Khashan, R. A. (2026). FlahaX (Version 0.6.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.23605679
@software{alkhashan2026flahax,
author = {Al Khashan, Rafat A.},
title = {FlahaX: plant-nutrient chemistry engine for fertilizer formulation and delivery planning},
year = {2026},
version = {0.6.0},
doi = {10.5281/zenodo.23605679},
url = {https://pypi.org/project/flahax/},
license = {Apache-2.0}
}To cite whichever version you used, the concept DOI 10.5281/zenodo.23605678 always
resolves to the latest release. GitHub's "Cite this repository" button reads
CITATION.cff.
FlahaX is written and maintained by Rafat A. Al Khashan (ORCID 0009-0009-4692-4552, rafat.khashan82@gmail.com) at Flaha Agri Tech.
It builds on published data, each value cited where it is used:
thermodynamic constants from USGS PHREEQC 3.8.6 (Parkhurst and Appelo 2013,
doi:10.3133/tm6A43), converted and extended
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 packaged catalogue is Flaha
Agri Tech Analysis Ver 0.0 (supplied by Flaha Agri Tech, 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; the
references are also in CITATION.cff.
FlahaX is open source under the
Apache License 2.0.
You may use, modify and redistribute it for any purpose, including commercial
products and research. Redistributions must keep the copyright notice and the
NOTICE file. If you
use FlahaX in published work, please cite it as shown above.
Releases up to and including 0.3.1 were published under the Flaha Free Use License 1.0; later releases use Apache-2.0.