flahax 0.1.0__tar.gz

flahax-0.1.0/INTEGRATION.md

@@ -0,0 +1,39 @@
+# Connecting FlahaX to FlahaFAST
+
+This repository is the Python package. FlahaFAST does not contain a copy. The application calls FlahaX only when `FLAHAX_RECOMMENDATIONS=true`. With the variable unset, Water → Crop → Salts → Recipe → Results is unchanged.
+
+The server runs `python -m flahax` with `PYTHONPATH` set to the package `src` directory.
+
+1. `FLAHAX_SRC`, when it is set.
+2. A sibling checkout, `../Flahax/src`, when this app is started from `FlahaFast/server`.
+3. The older in-app folder `flahax/src`, if a copy is still on disk.
+
+On the production host the installed tree is `/var/www/flahafast.flaha.org/flahax/src`. Set `FLAHAX_SRC` to that path in `server/.env`. Updating the package is a copy from this repository. It is not part of the FlahaFAST deploy archive.
+
+## What must already be true
+
+FlahaX needs the crop targets after the user confirms Crop, and the water ions after the user confirms Water. Both exist only when the user reaches Salts. The salts pre-checked today come from the formula record. That is not a FlahaX result.
+
+Recipe weighs whatever salts were confirmed. If an accepted FlahaX mix is thrown away there and solved again, the recommendation is lost. The grams travel with the salts only when the user accepted them.
+
+A saved run is never rewritten.
+
+## Start without a gap
+
+One switch, default off: `FLAHAX_RECOMMENDATIONS`.
+
+While it is off, every screen is the current flow. No new request, no new button, no change to Open results.
+
+While it is on:
+
+1. Salts asks for a recommendation only after water and the formula are both saved. The call is allowed to fail. On failure or timeout the salt page shows exactly what it shows today, including the formula’s own salt ids when those exist.
+2. The recommendation is a panel, not a new stage. **Use this combination** replaces the selection and stores the grams on the draft. **Keep my salts** leaves the selection untouched and stores nothing from FlahaX.
+3. Recipe, if and only if the draft says the user accepted, uses those grams as the salt amounts and does not solve them again. A/B and pH stay optional and unchanged. If the user did not accept, Recipe solves as it does now.
+4. Open results saves the balance that Recipe actually produced. The snapshot may record `flahaxAccepted: true` or `false`. It does not replace the result with a new solve at save time.
+5. History analysis, for a saved run with `flahaxAccepted` not true, may show the recommendation beside the saved balance. If that call fails, the history page omits the panel. The saved numbers stay.
+
+## What not to do in the first connection
+
+Do not block Salts while the recommendation loads. Do not change Crop, Water, or the formula row in the database. Do not auto-accept. Do not run FlahaX inside Open results. Do not deploy the Python package inside the Node process until the salt panel has been tried with the switch on and with the switch off.
+
+The first technical join is a single command, `python -m flahax`, reading JSON on stdin and writing the `recommend` result on stdout. The Node server starts it only when the switch is on. A non-zero exit becomes “no recommendation,” and the user continues.

flahax-0.1.0/LICENSE

@@ -0,0 +1,65 @@
+SPDX-License-Identifier: LicenseRef-Flaha-Free-Use
+
+Flaha Free Use License
+Version 1.0
+
+Copyright (c) 2026 Flaha
+
+This license covers the FlahaX software and its accompanying files (the
+"Software"), including source code, the salt library data shipped with the
+package, and documentation in this repository.
+
+1. Free use
+
+You may install and run the Software, at no charge, for any purpose,
+including commercial work, research, and personal use. You may make the
+copies that installation and execution require on computers you control,
+and you may keep reasonable backup copies for that same use. Obtaining
+the Software from the copyright holder's official repository or official
+package release, for your own use, is allowed.
+
+2. No redistribution
+
+You may not distribute, publish, sublicense, sell, rent, lend, or otherwise
+give the Software to anyone else, in source form or in built form. That
+includes republishing this repository, uploading the package to a package
+index, mirroring the files, or shipping the Software inside a product or
+archive that you give to a third party.
+
+3. No modification
+
+You may not modify, translate, adapt, or create derivative works of the
+Software. You may not remove or change copyright notices, license text, or
+author attributions.
+
+4. Reservation of rights
+
+The copyright holder reserves all rights that this license does not
+expressly grant. No patent rights and no trademark rights are granted.
+"Flaha" and "FlahaX" remain marks of their owner.
+
+5. Termination
+
+If you break section 2 or section 3, this license ends automatically for
+you. Sections 6 and 7 continue to apply.
+
+6. No warranty
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE, AND NON-INFRINGEMENT. THE ENTIRE RISK AS TO THE QUALITY AND USE
+OF THE SOFTWARE IS WITH YOU.
+
+7. Limitation of liability
+
+IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY, WHETHER IN CONTRACT, TORT, OR OTHERWISE, ARISING FROM OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OF THE SOFTWARE.
+
+8. How this license relates to open source
+
+This license makes use of the Software free. It does not permit copying
+the Software onward or modifying it. Because those permissions are
+withheld, this license is a proprietary free-use license. It is not an
+open-source license under the Open Source Definition, and it is not free
+software under the Free Software Definition.

flahax-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include README.md
+include LICENSE
+include INTEGRATION.md
+include pyproject.toml
+recursive-include docs *.md
+recursive-include src/flahax *.py
+recursive-include src/flahax/data *.json
+recursive-include tests *.py
+global-exclude __pycache__
+global-exclude *.py[cod]

flahax-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: flahax
+Version: 0.1.0
+Summary: Choose fertilizer salts and weights that minimize crop-formula percentage error.
+Author: Flaha
+License-Expression: LicenseRef-Flaha-Free-Use
+Project-URL: Homepage, https://github.com/rafatahmed/Flahax
+Project-URL: Documentation, https://github.com/rafatahmed/Flahax/tree/main/docs
+Project-URL: Source, https://github.com/rafatahmed/Flahax
+Project-URL: Issues, https://github.com/rafatahmed/Flahax/issues
+Keywords: fertilizer,hydroponics,nutrient-solution,formulation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# FlahaX
+
+FlahaX chooses a fertilizer combination and the grams of each salt for a fixed crop formula. Version 0.1.0. It is a separate Python package. The FlahaFAST application does not import it.
+
+The crop formula does not change. This season’s water is subtracted from it. The gap that remains is what the salts must cover. Every real salt in the library is a candidate. Non-negative grams decide which salts stay in the mix.
+
+## License
+
+Use of FlahaX is free of charge, including commercial use. The [Flaha Free Use License](LICENSE) allows you to install and run the package. It does not allow you to modify the software, and it does not allow you to give copies of it to anyone else. Downloading an official release for your own use is covered. Republishing, forking, or shipping your own copy is not.
+
+Because modification and redistribution are withheld, this is a proprietary free-use license. It is outside the Open Source Definition, which requires those permissions.
+
+## Install
+
+Python 3.11 or newer. No third-party dependencies.
+
+From this repository, in a virtual environment:
+
+```powershell
+python -m pip install -e .
+python -c "import flahax; print(flahax.__version__)"
+```
+
+The package is not on a public index yet. Building a release is described in [docs/publishing.md](docs/publishing.md).
+
+## Quick start
+
+```python
+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},
+)
+```
+
+The same call from the command line, reading JSON on standard input:
+
+```powershell
+@'
+{"targets": {"N_NO3": 128, "P": 58, "K": 211, "Ca": 104, "Mg": 40, "S": 54}, "water": {"Ca": 20}}
+'@ | python -m flahax
+```
+
+`result["salts"]` lists each chosen salt with `gramsPerLitre`. `result["rows"]` lists each element with its target, the final ppm, and `deltaPct`.
+
+## Proof
+
+Edited pepper targets, with 20 ppm calcium already in the water, fit inside 1% on every targeted element using six salts:
+
+| Salt | g/L |
+|---|---:|
+| Potassium nitrate | 0.546 |
+| Magnesium nitrate | 0.415 |
+| Calcium sulfate | 0.290 |
+| Phosphoric acid (75%) | 0.146 |
+| Calcium nitrate (ag grade) | 0.046 |
+| Calcium monobasic phosphate | 0.048 |
+
+The mathematics, the library counts, and the regression case are in [docs/method.md](docs/method.md).
+
+## Documentation
+
+- [docs/usage.md](docs/usage.md) — install, library call, command line, inputs, and result fields
+- [docs/method.md](docs/method.md) — ppm equation, solver, library file, and the pepper proof
+- [docs/publishing.md](docs/publishing.md) — build the sdist and wheel
+- [INTEGRATION.md](INTEGRATION.md) — how FlahaFAST can call the package without changing the current flow
+
+## Tests
+
+After `pip install -e .`, from the repository root:
+
+```powershell
+python -m unittest discover -s tests -t .
+```
+
+## Scope of this version
+
+Grams are for one litre of the solution the plant sees. This version does not split tanks, adjust pH, price the mix, or apply a concentration factor. It does not write to the FlahaFAST database.

flahax-0.1.0/README.md

@@ -0,0 +1,80 @@
+# FlahaX
+
+FlahaX chooses a fertilizer combination and the grams of each salt for a fixed crop formula. Version 0.1.0. It is a separate Python package. The FlahaFAST application does not import it.
+
+The crop formula does not change. This season’s water is subtracted from it. The gap that remains is what the salts must cover. Every real salt in the library is a candidate. Non-negative grams decide which salts stay in the mix.
+
+## License
+
+Use of FlahaX is free of charge, including commercial use. The [Flaha Free Use License](LICENSE) allows you to install and run the package. It does not allow you to modify the software, and it does not allow you to give copies of it to anyone else. Downloading an official release for your own use is covered. Republishing, forking, or shipping your own copy is not.
+
+Because modification and redistribution are withheld, this is a proprietary free-use license. It is outside the Open Source Definition, which requires those permissions.
+
+## Install
+
+Python 3.11 or newer. No third-party dependencies.
+
+From this repository, in a virtual environment:
+
+```powershell
+python -m pip install -e .
+python -c "import flahax; print(flahax.__version__)"
+```
+
+The package is not on a public index yet. Building a release is described in [docs/publishing.md](docs/publishing.md).
+
+## Quick start
+
+```python
+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},
+)
+```
+
+The same call from the command line, reading JSON on standard input:
+
+```powershell
+@'
+{"targets": {"N_NO3": 128, "P": 58, "K": 211, "Ca": 104, "Mg": 40, "S": 54}, "water": {"Ca": 20}}
+'@ | python -m flahax
+```
+
+`result["salts"]` lists each chosen salt with `gramsPerLitre`. `result["rows"]` lists each element with its target, the final ppm, and `deltaPct`.
+
+## Proof
+
+Edited pepper targets, with 20 ppm calcium already in the water, fit inside 1% on every targeted element using six salts:
+
+| Salt | g/L |
+|---|---:|
+| Potassium nitrate | 0.546 |
+| Magnesium nitrate | 0.415 |
+| Calcium sulfate | 0.290 |
+| Phosphoric acid (75%) | 0.146 |
+| Calcium nitrate (ag grade) | 0.046 |
+| Calcium monobasic phosphate | 0.048 |
+
+The mathematics, the library counts, and the regression case are in [docs/method.md](docs/method.md).
+
+## Documentation
+
+- [docs/usage.md](docs/usage.md) — install, library call, command line, inputs, and result fields
+- [docs/method.md](docs/method.md) — ppm equation, solver, library file, and the pepper proof
+- [docs/publishing.md](docs/publishing.md) — build the sdist and wheel
+- [INTEGRATION.md](INTEGRATION.md) — how FlahaFAST can call the package without changing the current flow
+
+## Tests
+
+After `pip install -e .`, from the repository root:
+
+```powershell
+python -m unittest discover -s tests -t .
+```
+
+## Scope of this version
+
+Grams are for one litre of the solution the plant sees. This version does not split tanks, adjust pH, price the mix, or apply a concentration factor. It does not write to the FlahaFAST database.

flahax-0.1.0/docs/method.md

@@ -0,0 +1,71 @@
+# Method
+
+A salt is not a knob for one element. Potassium nitrate carries potassium and nitrate-nitrogen. Monopotassium phosphate carries phosphorus and potassium. Monoammonium phosphate carries phosphorus and ammonium. Stacking those salts by hand can leave phosphorus and potassium hundreds of percent away from the formula while the micronutrients, which each have their own salt, look perfect.
+
+FlahaX answers a different question: given this formula and this water, which subset of the library, at which grams per litre, makes the percentage error as small as those compositions allow?
+
+Every real salt in the library is a candidate. Non-negative grams decide which salts stay in the mix. No salt is given a role by name.
+
+## Equation
+
+For one litre of working solution:
+
+```text
+final[element] = water[element] + Σ grams[salt] × percent[salt, element] × 10
+```
+
+`percent` is the element percentage stored on the salt (0–100). Multiplying by 10 converts one gram per litre at 1% into 10 ppm.
+
+The gap for an element that has a target is:
+
+```text
+gap = target − water
+```
+
+Grams are constrained to be greater than or equal to zero. The solver is Lawson–Hanson non-negative least squares. Each element row is scaled so the residual is a fraction of the target:
+
+```text
+Δ% = (final − target) / target × 100
+loss = Σ (Δ% / 100)²
+```
+
+An element that the formula does not ask for, such as ammonium or chloride, still has a light penalty: its ppm is divided by 100 and squared. That stops a salt from looking free when it dumps an element nobody requested. A sparsity term of `0.02` on each gram pushes salts that do not improve the fit back to zero, so the result is a short combination rather than a dusting of every salt.
+
+`recommend` runs that solve on every usable salt at once. Salts with grams above 0.000001 g/L are the combination, so zinc, copper, and molybdenum stay in the result when the formula asks for them.
+
+## Library file
+
+`load_library()` reads `flahax/data/library.json`, which is installed with the package. It is an export of the production database.
+
+| Key | Count | Contents |
+|---|---:|---|
+| `salts` | 37 | Name, formula, element percentages |
+| `waters` | 3 | `Default Water Profile` (no ions), `WC1` (Ca 20), `WC2` (N, Mg, Ca, Fe) |
+| `formulas` | 26 | Name, targets, linked water, salt names stored on the formula |
+
+Two rows are placeholders, not fertilizers: `Si_test` and `test_all`, both with formula text `Input Formula Here`. Unusable rows are those placeholders, salts whose name starts with `test_`, and salts with no elements. The other salts all enter the solve. Nothing in the solver prefers a salt because its name is MAP, MKP, or SOP.
+
+The formulas stored in that file are the library rows. Pepper (Howard Resh) there is nitrate-N 190, P 40, K 340, Ca 170, S 360, ammonium 18. The edited pepper targets in the proof below are a separate case.
+
+## Proof: edited pepper, water calcium 20
+
+Targets: nitrate-N 128, P 58, K 211, Ca 104, Mg 40, S 54. Water: Ca 20, so the calcium gap is 84.
+
+The fit from the full library keeps six salts and holds every targeted element inside 1%:
+
+| Salt | g/L |
+|---|---:|
+| Potassium nitrate | 0.546 |
+| Magnesium nitrate | 0.415 |
+| Calcium sulfate | 0.290 |
+| Phosphoric acid (75%) | 0.146 |
+| Calcium nitrate (ag grade) | 0.046 |
+| Calcium monobasic phosphate | 0.048 |
+
+A hand mix that forces large weights of both ammonium phosphate and potassium phosphate still produces about +216% phosphorus. That mix is the regression case in `tests/test_pepper.py`. The solver is not told to avoid it. The loss is simply higher, so those weights are not chosen.
+
+## Outside this version
+
+This version does not split tanks, adjust pH, price the mix, or apply a concentration factor. Grams are for one litre of the solution the plant sees. Stock-tank grams are those grams multiplied by the concentration factor, and that step belongs to the recipe screen.
+
+The package does not write to the FlahaFAST database and it does not change a saved run. How the application can call it is described in [INTEGRATION.md](../INTEGRATION.md).

flahax-0.1.0/docs/publishing.md

@@ -0,0 +1,38 @@
+# Publishing
+
+This follows the [Python packaging tutorial](https://packaging.python.org/en/latest/tutorials/packaging-projects/). The project already uses the `src` layout, `pyproject.toml`, `README.md`, `LICENSE`, and `tests/`.
+
+Build from the repository root, in the same directory as `pyproject.toml`:
+
+```powershell
+py -m pip install --upgrade build
+py -m build
+```
+
+That writes two files under `dist/`:
+
+- `flahax-0.1.0.tar.gz`, the source distribution
+- `flahax-0.1.0-py3-none-any.whl`, the built distribution
+
+Check them before uploading:
+
+```powershell
+py -m pip install --upgrade twine
+py -m twine check dist/*
+```
+
+## GitHub release
+
+Pushing a GitHub Release runs `.github/workflows/publish.yml`. That workflow builds `dist/`, checks it with Twine, and publishes to PyPI. The workflow password is the repository secret `PYPI_API_TOKEN`. The username Twine sends is `__token__`. The token value stays in GitHub secret storage, not in this repository.
+
+A new PyPI upload needs a new `version` in `pyproject.toml` before the next release. PyPI keeps a filename that was already published.
+
+## Manual upload
+
+A local upload is the same build, then:
+
+```powershell
+py -m twine upload dist/*
+```
+
+The username is `__token__` and the password is an API token, including the `pypi-` prefix. Keep that token in `%USERPROFILE%\.pypirc`, not in this repository. `.gitignore` ignores a `.pypirc` copied here by mistake. A TestPyPI rehearsal adds `--repository testpypi` and uses an account on [test.pypi.org](https://test.pypi.org).

flahax-0.1.0/docs/usage.md

@@ -0,0 +1,108 @@
+# Using FlahaX
+
+FlahaX chooses fertilizer salts and the grams of each salt for one litre of working solution. The crop formula stays fixed. This season’s water is subtracted from it. The remaining gap is what the salts must cover.
+
+Python 3.11 or newer is required. The package has no third-party dependencies.
+
+## Install
+
+From a checkout of this repository, inside a virtual environment:
+
+```powershell
+python -m pip install -e .
+python -c "import flahax; print(flahax.__version__)"
+```
+
+An editable install registers the `flahax` command and ships `data/library.json` with the package.
+
+## Library call
+
+```python
+from flahax import load_library, recommend
+
+library = load_library()
+salts = library["salts"]
+result = recommend(
+    salts,
+    targets={"N_NO3": 128, "P": 58, "K": 211, "Ca": 104, "Mg": 40, "S": 54},
+    water={"Ca": 20},
+)
+for salt in result["salts"]:
+    print(salt["name"], salt["gramsPerLitre"])
+```
+
+`recommend` drops placeholder rows itself. You can pass the full `salts` list from `load_library()`.
+
+## Command line
+
+The same solve is available as a program. It reads one JSON object from standard input and writes the `recommend` result to standard output.
+
+```powershell
+@'
+{"targets": {"N_NO3": 128, "P": 58, "K": 211, "Ca": 104, "Mg": 40, "S": 54}, "water": {"Ca": 20}}
+'@ | python -m flahax
+```
+
+After installation, `flahax` is the same program. A missing or empty `targets` object exits with status 1 and a message on standard error. `water` is optional and defaults to an empty map. Invalid JSON exits with status 1.
+
+## Public functions
+
+```python
+from flahax import gap_for, load_library, recommend, solve_weights
+
+load_library() -> dict
+gap_for(targets, water) -> dict
+recommend(salts, targets, water=None) -> dict
+solve_weights(salts, targets, water=None, sparsity=0.0) -> dict
+```
+
+`solve_weights` fits a set of salts you already chose. `recommend` calls it with `sparsity=0.02` after dropping unusable rows.
+
+`forward(salts, grams, water=None)` and `score(achieved, targets)` live in `flahax.engine`. `forward` applies the ppm equation. `score` returns the loss and the percentage-error rows.
+
+## Inputs
+
+Targets and water are maps of element symbol to ppm. Use the database symbols:
+
+`N_NO3`, `N_NH4`, `P`, `K`, `Ca`, `Mg`, `S`, `Fe`, `Mn`, `Zn`, `B`, `Cu`, `Mo`.
+
+A missing target means the formula does not ask for that element. That is different from a target of zero. Any ppm the salts still produce for an unrequested element is penalized.
+
+A salt is a dictionary:
+
+```python
+{
+    "id": "…",
+    "name": "Potassium Nitrate",
+    "formula": "KNO3",
+    "elements": {"N_NO3": 13.856, "K": 38.67},
+}
+```
+
+`elements` values are percentages from 0 to 100.
+
+## Result
+
+```python
+{
+    "salts": [{"id": "…", "name": "…", "gramsPerLitre": 0.5458}],
+    "saltIds": ["…"],
+    "grams": [0.0, 0.5458],
+    "loss": 0.0,
+    "rows": [
+        {"symbol": "K", "target": 211, "final": 211.0, "deltaPct": 0.0}
+    ],
+}
+```
+
+`grams` lines up with the salt list that entered the solve, and it includes the zeros. `salts` contains only the salts that received a positive weight. `deltaPct` is `None` when the formula has no target for that symbol.
+
+## Tests
+
+From the repository root, after the package is installed:
+
+```powershell
+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 export still has 37 salts, 3 waters, and 26 formulas, then calls `recommend` once per formula.

flahax-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "flahax"
+version = "0.1.0"
+description = "Choose fertilizer salts and weights that minimize crop-formula percentage error."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "LicenseRef-Flaha-Free-Use"
+license-files = ["LICEN[CS]E*"]
+authors = [{ name = "Flaha" }]
+keywords = ["fertilizer", "hydroponics", "nutrient-solution", "formulation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/rafatahmed/Flahax"
+Documentation = "https://github.com/rafatahmed/Flahax/tree/main/docs"
+Source = "https://github.com/rafatahmed/Flahax"
+Issues = "https://github.com/rafatahmed/Flahax/issues"
+
+[project.scripts]
+flahax = "flahax.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+flahax = ["data/*.json"]

flahax-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

flahax-0.1.0/src/flahax/__init__.py

@@ -0,0 +1,6 @@
+"""FlahaX: choose salt weights that minimize formulation Δ%."""
+
+from .engine import LIBRARY, gap_for, load_library, recommend, solve_weights
+
+__all__ = ["LIBRARY", "gap_for", "load_library", "recommend", "solve_weights"]
+__version__ = "0.1.0"

flahax-0.1.0/src/flahax/__main__.py

@@ -0,0 +1,29 @@
+"""Read targets and water as JSON on stdin. Write a recommendation on stdout."""
+
+import json
+import sys
+
+from flahax import load_library, recommend
+from flahax.engine import _usable
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        print("Expected a JSON object on stdin.", file=sys.stderr)
+        return 1
+    targets = payload.get("targets") if isinstance(payload, dict) else None
+    if not isinstance(targets, dict) or not targets:
+        print("targets are required.", file=sys.stderr)
+        return 1
+    water = payload.get("water") if isinstance(payload.get("water"), dict) else {}
+    salts = [salt for salt in load_library()["salts"] if _usable(salt)]
+    result = recommend(salts, targets, water)
+    json.dump(result, sys.stdout)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

flahax-0.1.0/src/flahax/data/library.json

@@ -0,0 +1 @@
+{"salts":[{"id":"cmbpfudiw00lzq8z936qog27v","name":"Ammonium Chloride","formula":"NH4Cl","elements":{"N_NH4":26.191,"Cl":66.272}},{"id":"cmbpfudkh00n5q8z9rvo5siqe","name":"Ammonium Dibasic Phosphate","formula":"(NH4)2HPO4","elements":{"N_NH4":21.217,"P":23.451}},{"id":"cmbpfudkn00naq8z9kd4qsr60","name":"Ammonium Monobasic Phosphate","formula":"(NH4)H2PO4","elements":{"N_NH4":12.18,"P":26.924}},{"id":"cmbpfudkt00nfq8z9iiidqyz0","name":"Ammonium Sulfate","formula":"(NH4)2SO4","elements":{"N_NH4":21.203,"S":24.267}},{"id":"cmbpfudmb00omq8z9a5nu1i5b","name":"Boric Acid","formula":"H3BO3","elements":{"B":17.482}},{"id":"cmbpfudh500klq8z9c38yocuf","name":"CH - micro","formula":"Ch micro","elements":{"B":1.3,"Fe":7,"Zn":0.4,"Mn":2,"Cu":0.11,"Mo":0.05}},{"id":"cmbpfudk800mzq8z9sfy6dfb4","name":"Calcium Carbonate","formula":"CaCO3","elements":{"Ca":40.078}},{"id":"cmbpfudlm00o2q8z9pq5dsfqe","name":"Calcium Monobasic Phosphate","formula":"Ca(H2PO4)2.H2O","elements":{"P":24.779,"Ca":16.029}},{"id":"cmbpfudif00lkq8z99slfmci3","name":"Calcium Nitrate (ag grade)","formula":"5Ca(NO3)2.NH4NO3.10H2O","elements":{"N_NO3":14.4,"N_NH4":1.1,"Ca":19}},{"id":"cmbpfudmg00opq8z9icoyntnp","name":"Calcium Sulfate (Dihydrate)","formula":"CaSO4.2H2O","elements":{"Ca":23.28,"S":18.62}},{"id":"cmbpfudi100l9q8z9xit3ujoz","name":"Copper EDTA","formula":"CuEDTA","elements":{"Cu":14}},{"id":"cmbpfudjh00meq8z964kelatd","name":"Copper Nitrate (Hexahydrate)","formula":"Cu(NO3)2.6H2O","elements":{"N_NO3":9.48,"Cu":21.49}},{"id":"cmbpfudls00o7q8z929uh7kwl","name":"Copper Sulfate (pentahydrate)","formula":"CuSO4.5H2O","elements":{"S":12.84,"Cu":25.45}},{"id":"cmbpfudjv00mqq8z9m4ndatyl","name":"Iron DTPA","formula":"FeDTPA","elements":{"Fe":11}},{"id":"cmbpfudjz00mtq8z9nrll8fnq","name":"Iron EDDHA","formula":"FeEDDHA","elements":{"Fe":6}},{"id":"cmbpfudl400npq8z9esjvg92l","name":"Iron EDTA","formula":"Fe(EDTA)","elements":{"Fe":13}},{"id":"cmbpfudm400ohq8z9h4pbl5iz","name":"Iron II Sulfate (Hepahydrate)","formula":"FeSO4.7H2O","elements":{"S":11.53,"Fe":20.09}},{"id":"cmbpfudkd00n2q8z9pasbjo1b","name":"Magnesium Carbonate","formula":"MgCO3","elements":{"Mg":28.831}},{"id":"cmbpfudmm00ouq8z91yim9eru","name":"Magnesium Sulfate (Heptahydrate)","formula":"MgSO4.7H2O","elements":{"Mg":9.86,"S":13.01}},{"id":"cmbpfudhl00kyq8z9j8u2rr14","name":"Mg Nitrate","formula":"Mg(NO3)2","elements":{"N_NO3":11,"Mg":9.65}},{"id":"cmbpfudhw00l6q8z9wj92mk5s","name":"Mn EDTA","formula":"MnEDTA","elements":{"Mn":13}},{"id":"cmbpfudim00lrq8z97u3qbfds","name":"Phosphoric Acid (75%)","formula":"H3PO4","elements":{"P":31.61}},{"id":"cmbpfudk400mwq8z9sdy98y00","name":"Potassium Carbonate","formula":"K2CO3","elements":{"K":56.581}},{"id":"cmbpfudj400m4q8z9e2mo7drh","name":"Potassium Chloride","formula":"KCl","elements":{"K":52.448,"Cl":47.552}},{"id":"cmbpfudi500lcq8z93fydsckd","name":"Potassium Citrate","formula":"C6H5K3O7","elements":{"K":38.2808916}},{"id":"cmbpfudky00nkq8z9baprwvj6","name":"Potassium Dibasic Phosphate","formula":"K2HPO4","elements":{"P":17.781,"K":44.897}},{"id":"cmbpfudl900nsq8z98470qom2","name":"Potassium Monobasic Phosphate","formula":"KH2PO4","elements":{"P":22.758,"K":28.732}},{"id":"cmbpfudmt00ozq8z9gsnrs779","name":"Potassium Nitrate","formula":"KNO3","elements":{"N_NO3":13.856,"K":38.67}},{"id":"cmbpfudi900lfq8z9o74v7q4e","name":"Potassium Sulfate","formula":"K2SO4","elements":{"K":44.873,"S":18.402}},{"id":"cmbpfudh100kiq8z95a34gov0","name":"Si_test","formula":"Input Formula Here","elements":{"Si":10}},{"id":"cmbpfudja00m9q8z9so56ge40","name":"Sodium Borate (Decahydrate) (borax)","formula":"Na2B4O7.10H2O","elements":{"B":11.34,"Na":12.06}},{"id":"cmbpfudlf00nxq8z9wx4ryy2b","name":"Sodium Molybdate (Dihydrate)","formula":"Na2MoO4.2H2O","elements":{"Mo":39.65,"Na":19}},{"id":"cmbpfudjn00mjq8z9svikn6gq","name":"Sodium Nitrate","formula":"NaNO3","elements":{"N_NO3":16.482,"Fe":7,"Na":27.047}},{"id":"cmbpfudiq00luq8z9z720v4t7","name":"Zinc Nitrate (Hexahydrate)","formula":"Zn(NO3)2.6H2O","elements":{"N_NO3":9.42,"Zn":21.98}},{"id":"cmbpfudly00ocq8z9zrrcr9zt","name":"Zinc Sulfate (Monohydrate)","formula":"ZnSO4.H2O","elements":{"S":17.86,"Zn":36.44}},{"id":"cmbpfudhr00l3q8z9qrth913z","name":"Zn EDTA","formula":"ZnEDTA","elements":{"Zn":14}},{"id":"cmbpfudfu00jjq8z9z2imd5m5","name":"test_all","formula":"Input Formula Here","elements":{"N_NO3":1,"N_NH4":2,"P":3,"K":4,"Mg":5,"Ca":6,"S":7,"B":10,"Fe":8,"Zn":9,"Mn":14,"Cu":11,"Mo":12,"Na":13,"Si":15,"Cl":16}}],"waters":[{"id":"cmbpfucsa0000q8z9kspb6dkt","name":"Default Water Profile","ph":7,"ec":0,"elements":{}},{"id":"cmbp7428f0000fyp8j73d3g1j","name":"WC1","ph":7,"ec":0,"elements":{"Ca":20}},{"id":"cmbp7428n0003fyp8ohwvs5gb","name":"WC2","ph":7,"ec":0,"elements":{"N":5,"Mg":8,"Ca":20,"Fe":0.1}}],"formulas":[{"id":"cmbpfud0y006wq8z9ghn6t86g","name":"Chilli (maximumyield)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":320,"P":103,"K":364,"Mg":96,"Ca":330,"S":174,"B":0.7,"Fe":4.9,"Zn":0.25,"Cu":0.07,"Mo":0.05,"Mn":1.97},"saltNames":[]},{"id":"cmbpfud9f00eaq8z92ve3zic0","name":"Cucumber (Howard Resh)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":140,"P":50,"K":350,"Mg":50,"Ca":200,"S":150,"B":0.3,"Fe":3,"Zn":0.1,"Cu":0.07,"Mo":0.03,"Mn":0.8},"saltNames":[]},{"id":"cmbpfucsg0002q8z9a5q0u7nu","name":"DEFAULT","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":210,"P":31,"K":235,"Mg":49,"Ca":200,"S":64,"B":0.5,"Fe":2.9,"Zn":0.05,"Cu":0.02,"Mo":0.05,"Mn":0.5},"saltNames":[]},{"id":"cmbpfud6y00c1q8z9emlc27x2","name":"Generic Bloom (maximumyield)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":130,"P":60,"K":300,"Mg":30,"Ca":100,"S":60,"B":0.5,"Fe":2,"Zn":0.1,"Cu":0.05,"Mo":0.05,"Mn":0.5},"saltNames":[]},{"id":"cmbpfudcu00haq8z9xwjoq1zt","name":"Generic Dry Season (Howard Resh)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":177,"P":60,"K":200,"Mg":36,"Ca":250,"S":129,"B":0.5,"Fe":5,"Zn":0.05,"Cu":0.03,"Mo":0.02,"Mn":0.5,"N_NH4":53},"saltNames":[]},{"id":"cmbpfud7r00crq8z9qc0abr6h","name":"Generic Grow (maximumyield)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":160,"P":30,"K":230,"Mg":30,"Ca":100,"S":60,"B":0.5,"Fe":2,"Zn":0.1,"Cu":0.05,"Mo":0.05,"Mn":0.5},"saltNames":[]},{"id":"cmbpfudbu00giq8z9jquzw746","name":"Generic Wet Season (Howard Resh)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":115,"P":50,"K":150,"Mg":50,"Ca":150,"S":50,"B":0.5,"Fe":5,"Zn":0.05,"Cu":0.03,"Mo":0.02,"Mn":0.5,"N_NH4":32},"saltNames":[]},{"id":"cmbpfucvl002kq8z9in7tpn5y","name":"Generic for Berries (Growing Edge)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":207,"P":55,"K":289,"Mg":38,"Ca":155,"S":51,"B":0.7,"Fe":6.8,"Zn":0.25,"Cu":0.07,"Mo":0.05,"Mn":1.97},"saltNames":[]},{"id":"cmbpfucun001uq8z9dgqeihsj","name":"Hoagland solution","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":210,"P":31,"K":235,"Mg":49,"Ca":200,"S":64,"B":0.5,"Fe":2.9,"Zn":0.05,"Cu":0.02,"Mo":0.05,"Mn":0.5},"saltNames":[]},{"id":"cmbpfud8k00dhq8z9yz59ziwb","name":"Lettuce 2 (Howard Resh)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":165,"P":50,"K":210,"Mg":45,"Ca":190,"S":113,"B":0.5,"Fe":4,"Zn":0.1,"Cu":0.1,"Mo":0.05,"Mn":0.5,"N_NH4":15},"saltNames":[]},{"id":"cmbpfuddo00i2q8z9nldrxm9w","name":"Lettuce General (Howard Resh)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":165,"P":50,"K":210,"Mg":45,"Ca":190,"S":65,"B":0.5,"Fe":4,"Zn":0.1,"Cu":0.1,"Mo":0.05,"Mn":0.5,"N_NH4":15},"saltNames":[]},{"id":"cmbpfud2n008cq8z99v63xpo5","name":"Melons (Douglas Peckenpaugh)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":215,"P":86,"K":343,"Mg":85,"Ca":175,"S":113,"B":0.7,"Fe":6.8,"Zn":0.25,"Cu":0.07,"Mo":0.05,"Mn":1.97},"saltNames":[]},{"id":"cmbpfudb100fqq8z9wcljgmyi","name":"Pepper (Howard Resh)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":190,"P":40,"K":340,"Mg":50,"Ca":170,"S":360,"B":0.33,"Fe":5,"Zn":0.33,"Cu":0.05,"Mo":0.05,"Mn":0.55,"N_NH4":18},"saltNames":[]},{"id":"cmbpfud3e0092q8z9vq8gw25x","name":"Rice (Douglas Peckenpaugh)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":249,"P":58,"K":80,"Mg":65,"Ca":317,"S":87,"B":0.7,"Fe":5,"Zn":0.4,"Cu":0.07,"Mo":0.05,"Mn":0.8,"Si":100},"saltNames":[]},{"id":"cmbpfuctq0014q8z9li5oo75d","name":"Strawberry Drip Irrigation (schundler.com)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":80,"P":45,"K":100,"Mg":50,"Ca":200,"S":180,"B":0.5,"Fe":3,"Zn":0.5,"Cu":0.05,"Mo":0.05,"Mn":0.5},"saltNames":[]},{"id":"cmbpfudel00iuq8z9l2wiwsfy","name":"Strawberry Fruiting (growing edge)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":128,"P":58,"K":211,"Mg":40,"Ca":104,"S":54,"B":0.7,"Fe":5,"Zn":0.25,"Cu":0.07,"Mo":0.05,"Mn":2},"saltNames":[]},{"id":"cmbpfuda900f0q8z9hi9hu2gu","name":"Tomato (Howard Resh)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":140,"P":50,"K":352,"Mg":50,"Ca":180,"S":168,"B":0.3,"Fe":5,"Zn":0.1,"Cu":0.07,"Mo":0.03,"Mn":0.8},"saltNames":[]},{"id":"cmbpfud6400bbq8z9gwrj4cw7","name":"Tomato Stage.1 - 10-14 days (Howard Resh)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":100,"P":40,"K":200,"Mg":20,"Ca":100,"S":53,"B":0.3,"Fe":3,"Zn":0.1,"Cu":0.07,"Mo":0.03,"Mn":0.8},"saltNames":[]},{"id":"cmbpfud5900alq8z907fk2r92","name":"Tomato Stage.2 - first cluster (Howard Resh)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":130,"P":55,"K":300,"Mg":33,"Ca":150,"S":109,"B":0.3,"Fe":3,"Zn":0.1,"Cu":0.07,"Mo":0.03,"Mn":0.8},"saltNames":[]},{"id":"cmbpfud4a009vq8z953niqg47","name":"Tomato Stage.3 - to plant maturity (Howard Resh)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":180,"P":65,"K":400,"Mg":45,"Ca":400,"S":144,"B":0.3,"Fe":3,"Zn":0.1,"Cu":0.07,"Mo":0.03,"Mn":0.8},"saltNames":[]},{"id":"cmbpfucxi0040q8z94o3m2bps","name":"Tomatoes - Fourth Cluster (U of Florida)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":120,"P":50,"K":150,"Mg":50,"Ca":150,"S":60,"B":0.7,"Fe":2.8,"Zn":0.3,"Cu":0.2,"Mo":0.05,"Mn":0.8},"saltNames":[]},{"id":"cmbpfucz7005gq8z90ev9h6ao","name":"Tomatoes - Second Cluster (U of Florida)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":80,"P":50,"K":120,"Mg":40,"Ca":150,"S":50,"B":0.7,"Fe":2.8,"Zn":0.3,"Cu":0.2,"Mo":0.05,"Mn":0.8},"saltNames":[]},{"id":"cmbpfucyc004qq8z9mdajrg3w","name":"Tomatoes - Third Cluster (U of Florida)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":100,"P":50,"K":150,"Mg":40,"Ca":150,"S":50,"B":0.7,"Fe":2.8,"Zn":0.3,"Cu":0.2,"Mo":0.05,"Mn":0.8},"saltNames":[]},{"id":"cmbpfud030066q8z9fvdyru1m","name":"Tomatoes - till First Cluster (U of Florida)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":70,"P":50,"K":120,"Mg":40,"Ca":150,"S":50,"B":0.7,"Fe":2.8,"Zn":0.3,"Cu":0.2,"Mo":0.05,"Mn":0.8},"saltNames":[]},{"id":"cmbpfucwh003aq8z9vmh9kner","name":"Tomatoes - to termination (U of Florida)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":150,"P":50,"K":200,"Mg":50,"Ca":150,"S":60,"B":0.7,"Fe":2.8,"Zn":0.3,"Cu":0.2,"Mo":0.05,"Mn":0.8},"saltNames":[]},{"id":"cmbpfud1t007mq8z9w16hx6hw","name":"Tropical Lettuce (Douglas Peckenpaugh)","waterName":"Default Water Profile","water":{},"targets":{"N_NO3":190,"P":25,"K":98,"Mg":25,"Ca":216,"S":33,"B":0.7,"Fe":4.9,"Zn":0.25,"Cu":0.07,"Mo":0.05,"Mn":1.97},"saltNames":[]}]}

flahax-0.1.0/src/flahax/engine.py

@@ -0,0 +1,235 @@
+"""FlahaX salt-combination search.
+
+The crop formula is fixed. This season's water is subtracted from it.
+The gap is what the salts must cover. Grams are per litre of working
+solution and cannot be negative. The objective is the sum of squared
+percentage errors on elements that have a target.
+
+Not imported by the FlahaFAST application.
+"""
+
+from __future__ import annotations
+
+import json
+from importlib.resources import files
+
+EPS = 1e-10
+
+
+def load_library() -> dict:
+    """Salt library, water profiles, and crop formulas shipped with the package."""
+    text = files("flahax").joinpath("data/library.json").read_text(encoding="utf-8")
+    return json.loads(text)
+
+
+def ppm_per_gram(percent: float) -> float:
+    """ppm in 1 litre from 1 gram of salt at an element percentage."""
+    return float(percent) * 10.0
+
+
+def gap_for(targets: dict, water: dict | None = None) -> dict:
+    water = water or {}
+    symbols = set(targets) | set(water)
+    gap = {}
+    for symbol in symbols:
+        target = targets.get(symbol)
+        if target is None:
+            gap[symbol] = None
+            continue
+        gap[symbol] = float(target) - float(water.get(symbol) or 0.0)
+    return gap
+
+
+def _transpose(rows: list[list[float]]) -> list[list[float]]:
+    return [list(col) for col in zip(*rows)]
+
+
+def _matvec(rows: list[list[float]], vec: list[float]) -> list[float]:
+    return [sum(a * b for a, b in zip(row, vec)) for row in rows]
+
+
+def _solve_square(matrix: list[list[float]], rhs: list[float]) -> list[float]:
+    """Gaussian elimination with partial pivoting."""
+    n = len(rhs)
+    a = [row[:] + [rhs[i]] for i, row in enumerate(matrix)]
+    for col in range(n):
+        pivot = max(range(col, n), key=lambda r: abs(a[r][col]))
+        if abs(a[pivot][col]) < EPS:
+            raise ValueError("singular least squares block")
+        a[col], a[pivot] = a[pivot], a[col]
+        div = a[col][col]
+        for j in range(col, n + 1):
+            a[col][j] /= div
+        for r in range(n):
+            if r == col:
+                continue
+            factor = a[r][col]
+            for j in range(col, n + 1):
+                a[r][j] -= factor * a[col][j]
+    return [a[i][n] for i in range(n)]
+
+
+def _lstsq(columns: list[list[float]], b: list[float]) -> list[float]:
+    """Least squares: columns are the active salt vectors."""
+    if not columns:
+        return []
+    ata = []
+    for i, left in enumerate(columns):
+        row = []
+        for right in columns:
+            row.append(sum(x * y for x, y in zip(left, right)))
+        ata.append(row)
+    atb = [sum(x * y for x, y in zip(col, b)) for col in columns]
+    return _solve_square(ata, atb)
+
+
+def nnls(matrix: list[list[float]], rhs: list[float]) -> list[float]:
+    """Lawson-Hanson non-negative least squares. matrix is rows × columns."""
+    if not matrix:
+        return []
+    cols = _transpose(matrix)
+    m = len(matrix)
+    n = len(cols)
+    x = [0.0] * n
+    passive: list[int] = []
+    active = list(range(n))
+
+    def residual() -> list[float]:
+        pred = _matvec(matrix, x)
+        return [rhs[i] - pred[i] for i in range(m)]
+
+    for _ in range(n * 4):
+        resid = residual()
+        w = [sum(col[i] * resid[i] for i in range(m)) for col in cols]
+        if not active:
+            break
+        enter = max(active, key=lambda j: w[j])
+        if w[enter] <= EPS:
+            break
+        passive.append(enter)
+        active.remove(enter)
+        while True:
+            sub = _lstsq([cols[j] for j in passive], rhs)
+            if all(value >= -EPS for value in sub):
+                for j in range(n):
+                    x[j] = 0.0
+                for j, value in zip(passive, sub):
+                    x[j] = max(0.0, value)
+                break
+            alpha = min(
+                x[j] / (x[j] - trial)
+                for j, trial in zip(passive, sub)
+                if trial < 0 and x[j] > trial
+            )
+            for j, trial in zip(passive, sub):
+                x[j] = x[j] + alpha * (trial - x[j])
+            stay = []
+            for j in passive:
+                if x[j] <= EPS:
+                    x[j] = 0.0
+                    active.append(j)
+                else:
+                    stay.append(j)
+            passive = stay
+            if not passive:
+                break
+    return x
+
+
+def score(achieved: dict, targets: dict) -> tuple[float, list[dict]]:
+    loss = 0.0
+    rows = []
+    symbols = list(dict.fromkeys([*targets.keys(), *achieved.keys()]))
+    for symbol in symbols:
+        target = targets.get(symbol)
+        final = float(achieved.get(symbol) or 0.0)
+        delta = None
+        if target is not None and target > 0:
+            delta = ((final - target) / target) * 100.0
+            loss += (delta / 100.0) ** 2
+        elif final > 0:
+            loss += (final / 100.0) ** 2
+        rows.append({"symbol": symbol, "target": target, "final": final, "deltaPct": delta})
+    return loss, rows
+
+
+def forward(salts: list[dict], grams: list[float], water: dict | None = None) -> dict:
+    water = water or {}
+    achieved = {symbol: float(value) for symbol, value in water.items()}
+    for salt, gram in zip(salts, grams):
+        if gram <= 0:
+            continue
+        for symbol, percent in salt["elements"].items():
+            achieved[symbol] = achieved.get(symbol, 0.0) + gram * ppm_per_gram(percent)
+    return achieved
+
+
+def solve_weights(salts: list[dict], targets: dict, water: dict | None = None, sparsity: float = 0.0) -> dict:
+    """Non-negative grams per litre minimizing squared Δ%."""
+    water = water or {}
+    symbols = list(dict.fromkeys([
+        *targets.keys(),
+        *(symbol for salt in salts for symbol in salt["elements"]),
+    ]))
+    matrix = []
+    rhs = []
+    for symbol in symbols:
+        target = targets.get(symbol)
+        rates = [ppm_per_gram(salt["elements"].get(symbol, 0.0)) for salt in salts]
+        background = float(water.get(symbol) or 0.0)
+        if target is not None and target > 0:
+            matrix.append([rate / target for rate in rates])
+            rhs.append((target - background) / target)
+        else:
+            # No target: a light penalty so MAP's ammonium does not outrank a real miss.
+            matrix.append([rate / 100.0 for rate in rates])
+            rhs.append(-background / 100.0)
+    if sparsity > 0 and salts:
+        for index in range(len(salts)):
+            row = [0.0] * len(salts)
+            row[index] = sparsity
+            matrix.append(row)
+            rhs.append(0.0)
+    grams = nnls(matrix, rhs)
+    achieved = forward(salts, grams, water)
+    loss, rows = score(achieved, targets)
+    chosen = []
+    for salt, gram in zip(salts, grams):
+        # Micronutrient salts are often well under 0.0005 g/L. Keep them.
+        if gram > 1e-6:
+            chosen.append({
+                "id": salt["id"],
+                "name": salt["name"],
+                "gramsPerLitre": round(gram, 6),
+            })
+    return {"salts": chosen, "grams": grams, "loss": loss, "rows": rows}
+
+
+LIBRARY = [
+    {"id": "CaNO3", "name": "Calcium nitrate (ag grade)", "elements": {"N_NO3": 14.4, "N_NH4": 1.1, "Ca": 19.0}},
+    {"id": "KNO3", "name": "Potassium nitrate", "elements": {"N_NO3": 13.856, "K": 38.67}},
+    {"id": "MKP", "name": "Monopotassium phosphate", "elements": {"P": 22.758, "K": 28.732}},
+    {"id": "MAP", "name": "Monoammonium phosphate", "elements": {"N_NH4": 12.18, "P": 26.924}},
+    {"id": "SOP", "name": "Potassium sulfate", "elements": {"K": 44.873, "S": 18.402}},
+    {"id": "MgSO4", "name": "Magnesium sulfate", "elements": {"Mg": 9.86, "S": 13.01}},
+]
+
+
+def _usable(salt: dict) -> bool:
+    """Skip empty rows and the two placeholder salts. Every real salt stays eligible."""
+    if not salt.get("elements"):
+        return False
+    if salt.get("formula") == "Input Formula Here":
+        return False
+    if str(salt.get("name", "")).lower().startswith("test_"):
+        return False
+    return True
+
+
+def recommend(library: list[dict], targets: dict, water: dict | None = None) -> dict:
+    """Solve against every usable salt. Positive grams are the chosen combination."""
+    water = water or {}
+    salts = [salt for salt in library if _usable(salt)]
+    solved = solve_weights(salts, targets, water, sparsity=0.02)
+    solved["saltIds"] = [item["id"] for item in solved["salts"]]
+    return solved

flahax-0.1.0/src/flahax.egg-info/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: flahax
+Version: 0.1.0
+Summary: Choose fertilizer salts and weights that minimize crop-formula percentage error.
+Author: Flaha
+License-Expression: LicenseRef-Flaha-Free-Use
+Project-URL: Homepage, https://github.com/rafatahmed/Flahax
+Project-URL: Documentation, https://github.com/rafatahmed/Flahax/tree/main/docs
+Project-URL: Source, https://github.com/rafatahmed/Flahax
+Project-URL: Issues, https://github.com/rafatahmed/Flahax/issues
+Keywords: fertilizer,hydroponics,nutrient-solution,formulation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# FlahaX
+
+FlahaX chooses a fertilizer combination and the grams of each salt for a fixed crop formula. Version 0.1.0. It is a separate Python package. The FlahaFAST application does not import it.
+
+The crop formula does not change. This season’s water is subtracted from it. The gap that remains is what the salts must cover. Every real salt in the library is a candidate. Non-negative grams decide which salts stay in the mix.
+
+## License
+
+Use of FlahaX is free of charge, including commercial use. The [Flaha Free Use License](LICENSE) allows you to install and run the package. It does not allow you to modify the software, and it does not allow you to give copies of it to anyone else. Downloading an official release for your own use is covered. Republishing, forking, or shipping your own copy is not.
+
+Because modification and redistribution are withheld, this is a proprietary free-use license. It is outside the Open Source Definition, which requires those permissions.
+
+## Install
+
+Python 3.11 or newer. No third-party dependencies.
+
+From this repository, in a virtual environment:
+
+```powershell
+python -m pip install -e .
+python -c "import flahax; print(flahax.__version__)"
+```
+
+The package is not on a public index yet. Building a release is described in [docs/publishing.md](docs/publishing.md).
+
+## Quick start
+
+```python
+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},
+)
+```
+
+The same call from the command line, reading JSON on standard input:
+
+```powershell
+@'
+{"targets": {"N_NO3": 128, "P": 58, "K": 211, "Ca": 104, "Mg": 40, "S": 54}, "water": {"Ca": 20}}
+'@ | python -m flahax
+```
+
+`result["salts"]` lists each chosen salt with `gramsPerLitre`. `result["rows"]` lists each element with its target, the final ppm, and `deltaPct`.
+
+## Proof
+
+Edited pepper targets, with 20 ppm calcium already in the water, fit inside 1% on every targeted element using six salts:
+
+| Salt | g/L |
+|---|---:|
+| Potassium nitrate | 0.546 |
+| Magnesium nitrate | 0.415 |
+| Calcium sulfate | 0.290 |
+| Phosphoric acid (75%) | 0.146 |
+| Calcium nitrate (ag grade) | 0.046 |
+| Calcium monobasic phosphate | 0.048 |
+
+The mathematics, the library counts, and the regression case are in [docs/method.md](docs/method.md).
+
+## Documentation
+
+- [docs/usage.md](docs/usage.md) — install, library call, command line, inputs, and result fields
+- [docs/method.md](docs/method.md) — ppm equation, solver, library file, and the pepper proof
+- [docs/publishing.md](docs/publishing.md) — build the sdist and wheel
+- [INTEGRATION.md](INTEGRATION.md) — how FlahaFAST can call the package without changing the current flow
+
+## Tests
+
+After `pip install -e .`, from the repository root:
+
+```powershell
+python -m unittest discover -s tests -t .
+```
+
+## Scope of this version
+
+Grams are for one litre of the solution the plant sees. This version does not split tanks, adjust pH, price the mix, or apply a concentration factor. It does not write to the FlahaFAST database.

flahax-0.1.0/src/flahax.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+INTEGRATION.md
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+docs/method.md
+docs/publishing.md
+docs/usage.md
+src/flahax/__init__.py
+src/flahax/__main__.py
+src/flahax/engine.py
+src/flahax.egg-info/PKG-INFO
+src/flahax.egg-info/SOURCES.txt
+src/flahax.egg-info/dependency_links.txt
+src/flahax.egg-info/entry_points.txt
+src/flahax.egg-info/top_level.txt
+src/flahax/data/library.json
+tests/__init__.py
+tests/test_library.py
+tests/test_pepper.py

flahax-0.1.0/src/flahax.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

flahax-0.1.0/src/flahax.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+flahax = flahax.__main__:main

flahax-0.1.0/src/flahax.egg-info/top_level.txt

@@ -0,0 +1 @@
+flahax

flahax-0.1.0/tests/__init__.py

@@ -0,0 +1 @@
+

flahax-0.1.0/tests/test_library.py

@@ -0,0 +1,33 @@
+import unittest
+
+from flahax import load_library, recommend
+from flahax.engine import _usable
+
+LIBRARY = load_library()
+
+
+class LibrarySuite(unittest.TestCase):
+    def test_tables_match_the_database_export(self):
+        self.assertEqual(len(LIBRARY["salts"]), 37)
+        self.assertEqual(len(LIBRARY["waters"]), 3)
+        self.assertEqual(len(LIBRARY["formulas"]), 26)
+        self.assertIn("WC1", [water["name"] for water in LIBRARY["waters"]])
+
+    def test_each_crop_formula_is_solved_from_the_whole_library(self):
+        salts = [salt for salt in LIBRARY["salts"] if _usable(salt)]
+        known = {salt["id"] for salt in salts}
+        misses = []
+        for formula in LIBRARY["formulas"]:
+            result = recommend(salts, formula["targets"], formula["water"])
+            if not result["salts"]:
+                misses.append(f"{formula['name']}: no salts")
+                continue
+            if any(salt_id not in known for salt_id in result["saltIds"]):
+                misses.append(f"{formula['name']}: unknown salt")
+            if result["loss"] != result["loss"]:
+                misses.append(f"{formula['name']}: loss is not a number")
+        self.assertEqual(misses, [])
+
+
+if __name__ == "__main__":
+    unittest.main()

flahax-0.1.0/tests/test_pepper.py

@@ -0,0 +1,73 @@
+import unittest
+
+from flahax import gap_for, load_library, recommend
+from flahax.engine import _usable, forward, score
+
+SALTS = [salt for salt in load_library()["salts"] if _usable(salt)]
+
+# Project Test01. Pepper (Howard Resh), season 2026. Water calcium 20 ppm.
+TARGETS = {
+    "N_NO3": 128,
+    "P": 58,
+    "K": 211,
+    "Ca": 104,
+    "Mg": 40,
+    "S": 54,
+}
+WATER = {"Ca": 20}
+
+
+def row(result, symbol):
+    return next(item for item in result["rows"] if item["symbol"] == symbol)
+
+
+class PepperProof(unittest.TestCase):
+    def test_gap_removes_season_water(self):
+        gap = gap_for(TARGETS, WATER)
+        self.assertEqual(gap["Ca"], 84)
+        self.assertEqual(gap["P"], 58)
+
+    def test_recommendation_hits_phosphorus_and_potassium(self):
+        result = recommend(SALTS, TARGETS, WATER)
+        for symbol in ("P", "K", "Ca", "Mg", "S", "N_NO3"):
+            self.assertLess(abs(row(result, symbol)["deltaPct"]), 1, symbol)
+
+    def test_zinc_copper_and_molybdenum_stay_in_the_combination(self):
+        targets = {
+            **TARGETS,
+            "Fe": 5, "Mn": 0.8, "Zn": 0.1, "B": 0.3, "Cu": 0.07, "Mo": 0.03,
+        }
+        result = recommend(SALTS, targets, WATER)
+        covered = set()
+        for item in result["salts"]:
+            elements = next(s for s in SALTS if s["id"] == item["id"])["elements"]
+            covered.update(elements)
+        for symbol in ("Zn", "Cu", "Mo"):
+            self.assertIn(symbol, covered, symbol)
+            self.assertLess(abs(row(result, symbol)["deltaPct"]), 1, symbol)
+
+    def test_forced_map_and_mkp_is_the_pepper_miss(self):
+        """The published run stacked both phosphorus salts. That is not the optimum."""
+        def named(fragment):
+            return next(salt for salt in SALTS if fragment.lower() in salt["name"].lower())
+
+        salts = [named(name) for name in (
+            "Calcium Nitrate",
+            "Potassium Nitrate",
+            "Potassium Monobasic",
+            "Ammonium Monobasic",
+            "Magnesium Sulfate",
+        )]
+        # Grams reconstructed from the published balance, not from the solver.
+        grams = [0.605, 0.587, 0.549, 0.213, 0.406]
+        achieved = forward(salts, grams, WATER)
+        _loss, rows = score(achieved, TARGETS)
+        phosphorus = next(item for item in rows if item["symbol"] == "P")
+        self.assertGreater(phosphorus["deltaPct"], 100)
+
+        good = recommend(SALTS, TARGETS, WATER)
+        self.assertLess(abs(row(good, "P")["deltaPct"]), phosphorus["deltaPct"])
+
+
+if __name__ == "__main__":
+    unittest.main()