FlahaX

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 mix asks 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.

Installation

Python 3.11 or newer. There are no third-party runtime dependencies.

python -m pip install flahax==0.6.0

Pin 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 --version

One 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"

Quick start

Growers and agronomists: flahax mix

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 questions

In 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.

One command: flahax batch

The same from files, for scripts:

flahax batch --formula "Tomato (Howard Resh)" --water ro --ph 5.8 --acid HNO3:0.60:1.37 --output tomato

It 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.

Python

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.

Commands

flahax --help shows every command with examples. Commands plan; they never operate pumps, valves or other hardware.

What it does

Documentation

The manual can also be read offline from an installed package through importlib.resources (flahax/data/USER_GUIDE.md).

Troubleshooting

More in the manual's troubleshooting section. If something still looks wrong, open an issue with flahax --version and the command you ran.

Verification and limits

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 owner'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.

Contributing

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.

Citation

Al Khashan, R. A. (2026). FlahaX (Version 0.6.0) [Computer software]. https://pypi.org/project/flahax/

@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},
  url     = {https://pypi.org/project/flahax/},
  license = {Apache-2.0}
}

GitHub's "Cite this repository" button reads CITATION.cff.

Author and credits

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 full list, the modifications and the USGS User Rights Notice are in NOTICE; the references are also in CITATION.cff.

License

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.