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

• Researchers who need reproducible nutrient-solution chemistry with stated validity limits.
• Agronomists and consultants who design recipes against real water analyses and real commercial products.
• Growers with technical support, through the interactive command line.
• Developers building nutrition and fertigation software on a tested, dependency-free engine.

FlahaX and FlahaFAST. FlahaX is developed as the chemistry engine for the FlahaFAST application, where it is planned to provide formulation, pH and conductivity planning. That integration is not yet in place: FlahaFAST does not currently import FlahaX, and FlahaX stays a standalone package with its own releases.

Install

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

python -m pip install flahax==0.5.0

Pin the version for reproducible work. python -m pip install flahax installs the latest release.

Quick start

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 line

flahax --help
flahax workflow --interactive   # water + crop targets -> recipe, pH and acid plan
flahax ec --interactive         # approximate EC screening for supported products
flahax size --interactive       # stock-channel volume and injector flow sizing

With no subcommand, flahax reads one JSON object (salts, targets, water) on standard input and writes the recommendation as JSON. Commands plan; they never operate pumps, valves or other hardware.

What it does

Verification

The Benchmark v1 protocol separates formulation fit, numerical chemistry, runtime/memory measurements, and physical validation. Its reproducible reports include input hashes and failed cases; timings are informational, and physical validation remains separate. See the measured results and downloadable evidence for tables, charts, provenance, and retained limitations.

• 153 automated tests, including live replay of every catalogue product, phase and acid case against pinned PHREEQC 3.8.6 (USGS).
• Hosted checks on Python 3.11, 3.12 and 3.13, plus clean wheel and source installation checks.
• Evidence is versioned per release in the release evidence.

This is computational evidence. FlahaX has not been validated in the laboratory or in the field, and its owner's computational assessment is not an independent review. No recipe, pH or EC value is an authorization to operate equipment.

Roadmap

Next work, in order: broader numerical and input-boundary testing, stable consumer contracts, and a validated conductivity model covering irrigation-strength solutions first and concentrated stock tanks second. See the development roadmap and current status.

Documentation

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

Development

From a source checkout:

python -m pip install -e .
PYTHONPATH=src python -m unittest discover -s tests -t .

Live PHREEQC replay, distribution verification and branch conventions are in package verification and CONTRIBUTING.

Citation

Al Khashan, R. A. (2026). FlahaX (Version 0.5.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.5.0},
  url     = {https://pypi.org/project/flahax/},
  license = {Apache-2.0}
}

GitHub's "Cite this repository" button reads 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.