8000 fix: reconcile sequential dosing and zero-ammonium search by rafatahmed · Pull Request #239 · rafatahmed/Flahax · GitHub
[go: up one dir, main page]

Skip to content
< 7FFF link rel="preload" as="image" href="https://github.githubassets.com/assets/changelog-dark-b1c25ae971bd641b.png"/>
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
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,10 @@ each release, with numbers, sources and decisions, are in

### Fixed

- Reconcile sequential pH nutrient reports and limit checks with the actual returned reagent
dose (#237). Respect fixed-zero sources in joint proposals and enable zero-cap refinement
without changing tolerances or iteration limits (#238).

- Fill nutrient stocks independently of the reagent container capacity at the shared injection
ratio; report reagent doses per fill, refill counts and final partial fills without changing
solver methods or nutrient tolerances (#231).
Expand Down
15 changes: 15 additions & 0 deletions docs/releases/unreleased.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,20 @@
# FlahaX unreleased changes: detailed notes

## Sequential accounting and explicit zero maxima (#237, #238)

Sequential pH candidates now reassess nutrient totals, total nitrogen, loss and declared
maximum checks using the actual returned reagent dose and unchanged fertilizer amounts.
The settling tolerance no longer leaves assessments tied to the preceding assumed dose.
Ordinary fits retain their search provenance; only actual blended recipes are labelled as blends.

Joint proposals keep sources at zero when an existing hard constraint proves that no dose is
allowed. The existing active-face refinement also applies to binding zero maxima. This avoids
discarding an entire proposed step because it includes a forbidden product, and permits local
stationarity refinement at a zero cap. Solver tolerances, iteration limits and final verification
are unchanged. A zero ammonium target still means no requirement; an explicit zero ammonium
maximum prohibits ammonium. Convergence does not imply that nutrient targets are met, and
does not prove a global optimum.

## Final recipe report consistency (#231)

Remedy stage messages now match the final recipe shown in the batch summary. Reports explain
Expand Down
17 changes: 15 additions & 2 deletions src/flahax/joint_solver.py
Original file line number Diff line number Diff line change
Expand Up @@ -389,6 +389,16 @@ def solve_joint_problem(
doses = [start.get(k, 0.0) for k in identifiers[:-1]] + [_number(reagent_dose, 'reagent dose')]
point = [_number(x / h, 'scaled initial dose') for x, h in zip(doses, scales)]
constraints = _constraints(problem, scales)
# Nonnegative sources of a nutrient with no remaining allowance are fixed
# at zero. Keep them out of local proposals, not merely the final line search:
# one forbidden positive coordinate would otherwise shorten the whole step to zero.
fixed_zero = {
j
for row, bound in constraints
if bound == 0 and all(a >= 0 for a in row)
for j, a in enumerate(row)
if a > 0
}
exact_model = None
if objective_gap_tolerance is not None or stationarity_tolerance is not None:
exact_model = [
Expand Down Expand Up @@ -929,7 +939,7 @@ def improves_stationarity(u, value):
return trial_check['relativeResidual'] < stationary['relativeResidual']

has_active_cap = any(
item['constraint'] >= n and constraints[item['constraint']][1] > 0
item['constraint'] >= n and constraints[item['constraint']][1] >= 0
for item in stationary['activeMultipliers']
)
refine_cap = has_active_cap and stationary['relativeResidual'] <= 0.05
Expand Down Expand Up @@ -1052,7 +1062,10 @@ def improves_stationarity(u, value):
charge_tolerance / charge_scale,
max_backtracks,
[max(0.0, v - width) for v, width in zip(point, widths)],
[v + width for v, width in zip(point, widths)],
[
0.0 if j in fixed_zero else v + width
for j, (v, width) in enumerate(zip(point, widths))
],
diagnostics=linear,
)
linear['chargeEquality'] = True
Expand Down
39 changes: 26 additions & 13 deletions src/flahax/ph_adjustment.py
Original file line number Diff line number Diff line change
Expand Up @@ -548,17 +548,33 @@ def _blend_recipe(pool, targets, supply, endpoints, weight, maxima):
rebuilt rows (water, products and the reagent's supply).
"""
maxima = assessed_limits(maxima, endpoints[0])
by_id = {p['id']: p for p in pool}
entries = {s['id']: s for r in endpoints for s in r['salts']}
doses = {}
for recipe, factor in zip(endpoints, (1 - weight, weight)):
for salt in recipe['salts']:
doses[salt['id']] = doses.get(salt['id'], 0.0) + factor * salt['gramsPerLitre']
salts = [dict(entries[key], gramsPerLitre=g) for key, g in doses.items() if g > 0]
result = _assess_recipe(pool, targets, supply, endpoints[0], salts, maxima)
if 'substitutionSearch' in result:
result['substitutionSearch'] = dict(
result['substitutionSearch'],
method='convex blend of searched endpoint recipes; no global search certificate',
attemptedProductIds=[
[salt['id'] for salt in endpoint['salts']] for endpoint in endpoints
],
)
return result


def _assess_recipe(pool, targets, supply, recipe, salts, maxima):
"""Reassess fixed product doses and actual supply without rerunning the fit."""
maxima = assessed_limits(maxima, recipe)
by_id = {p['id']: p for p in pool}
doses = {s['id']: s['gramsPerLitre'] for s in salts}
grams = [doses.get(p['id'], 0.0) for p in pool]
loss, rows = score(forward(pool, grams, supply), targets)
result = dict(
endpoints[0],
recipe,
salts=salts,
saltIds=[s['id'] for s in salts],
grams=grams,
Expand Down Expand Up @@ -607,10 +623,6 @@ def _blend_recipe(pool, targets, supply, endpoints, weight, maxima):
result['substitutionSearch'] = dict(
result['substitutionSearch'],
status='candidate_found' if result['feasible'] else 'search_incomplete',
method='convex blend of searched endpoint recipes; no global search certificate',
attemptedProductIds=[
[salt['id'] for salt in endpoint['salts']] for endpoint in endpoints
],
)
return result

Expand Down Expand Up @@ -745,13 +757,14 @@ def charge_gap(weight):
)
if abs(dose - assumed_dose) > DOSE_TOLERANCE * max(dose, 1e-12):
raise DeliveryError('nonconvergent', 'blended recipe and reagent dose disagree')
# Recompute every assessment at the actual dose, including diagnostic rows.
supply = dict(water)
for ion, mg in contribution(dose).items():
supply[ion] = supply.get(ion, 0.0) + mg
recommendation = _blend_recipe(
pool, targets, supply, [recommendation] * 2, 0.0, maximum_concentrations
)
# Settling permits a small dose difference; rows and limits must still describe
# the actual returned dose, for ordinary fits as well as blended recipes.
supply = dict(water)
for ion, mg in contribution(dose).items():
supply[ion] = supply.get(ion, 0.0) + mg
recommendation = _assess_recipe(
pool, targets, supply, recommendation, recommendation['salts'], maximum_concentrations
)
grams = dose * mass * molar_mass / fraction
litres = grams / (1000 * density) if density else None
over_dose = (litres is not None and (litres > cap or litres > volume)) or grams * (
Expand Down
13 changes: 11 additions & 2 deletions tests/test_grower_journey.py
Original file line number Diff line number Diff line change
Expand Up @@ -247,10 +247,19 @@ def test_measured_water_reference_reaches_the_target_in_an_explicit_joint_fit(se
self.assertAlmostEqual(chosen['joint']['finalPh'], 5.8, places=4)
self.assertEqual(summary['status'], 'requires_review')

def test_dry_reagent_uses_mass_on_a_real_batch_when_no_joint_candidate_verifies(self):
summary = tomato(formula='Lettuce 2 (Howard Resh)', ph=6.5)
def test_dry_reagent_uses_mass_without_a_declared_joint_mass_cap(self):
from flahax import catalogue_ph_reagents

solid = next(p for p in catalogue_ph_reagents() if p['chemicalFormula'] == 'KHCO3')
with tempfile.TemporaryDirectory() as folder:
reagents = Path(folder) / 'reagents.json'
reagents.write_text(json.dumps([solid]), encoding='utf-8')
summary = tomato(
formula='Lettuce 2 (Howard Resh)', ph=6.5, reagents=str(reagents), acid=[]
)
chosen = summary['ph']['selected']
self.assertIsNotNone(chosen, summary['ph']['message'])
self.assertEqual(chosen['product_id'], solid['id'])
self.assertEqual(chosen['joint']['status'], 'sequential')
self.assertIsNone(chosen['volume_ml_per_batch'])
self.assertGreater(chosen['mass_g_per_batch'], 0)
Expand Down
131 changes: 131 additions & 0 deletions tests/test_joint_hard_caps.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
# SPDX-FileCopyrightText: 2026 Flaha. Created by Rafat A. Al Khashan.
# SPDX-License-Identifier: Apache-2.0
# Disclaimer: planning software provided without warranty (Apache-2.0, section 7);
# its results are calculations, not dosing instructions.
"""Provably unusable sources must not dominate the public joint search."""

import json
from pathlib import Path
import tempfile
import unittest

from flahax import (
catalogue_ph_reagents,
load_library,
make_joint_problem,
recommend,
solve_joint_problem,
)
from flahax.batch_cli import JOINT_CONTROLS


def capped_problem(include_forbidden):
pool = [
p
for p in load_library()['salts']
if p['formula'] == 'KH2PO4' or include_forbidden and p['formula'] == '(NH4)2SO4'
]
reagent = next(p for p in catalogue_ph_reagents() if p['chemicalFormula'] == 'KOH')
targets = {'K': 100, 'P': 50, 'S': 50}
problem = make_joint_problem(
pool,
reagent,
targets,
{},
reagent_solvent_fraction=0.55,
water_components={},
final_volume_litres=1000,
solvent_mass_kg=1000,
target_ph=6,
10000 reference_charge_mol_per_kg=0,
maximum_reagent_mass_g=7280,
maximum_reagent_volume_litres=5,
maximum_concentrations={'N_NH4': 0},
)
recipe = recommend(pool, targets, {}, maximum_concentrations={'N_NH4': 0})
doses = {s['id']: s['gramsPerLitre'] for s in recipe['salts']}
controls = dict(
JOINT_CONTROLS,
dose_steps={s.product_id: 1e-4 for s in (*problem.fertilizers, problem.reagent)},
)
return problem, doses, controls


class JointHardCapTests(unittest.TestCase):
def test_batch_converges_with_explicit_zero_ammonium_maximum(self):
from flahax.batch_cli import BatchOptions, run_batch

targets = {
'N_NO3': 140,
'N_NH4': 0,
'P': 50,
'K': 340,
'Ca': 200,
'Mg': 50,
'S': 150,
'Fe': 2.8,
'Mn': 0.8,
'B': 0.7,
'Zn': 0.1,
'Cu': 0.07,
'Mo': 0.05,
}
reagents = [p for p in catalogue_ph_reagents() if p['chemicalFormula'] == 'KOH']
with tempfile.TemporaryDirectory() as directory:
target_file = Path(directory) / 'targets.json'
reagent_file = Path(directory) / 'reagents.json'
target_file.write_text(json.dumps(targets))
reagent_file.write_text(json.dumps(reagents))
summary = run_batch(
BatchOptions(
water='ro',
targets=str(target_file),
reagents=str(reagent_file),
ph=6,
ratio=10,
tank_litres={'A': 100, 'B': 100, 'acid': 10},
mode='fill',
limit=[['N_NH4', 0]],
)
)
chosen = summary['ph']['selected']
self.assertIsNotNone(chosen, summary['ph']['message'])
self.assertEqual(chosen['joint']['status'], 'stationary_point')
products = {p['id']: p for p in load_library()['salts']}
self.assertEqual(chosen['formula'], 'KOH')
ammonium = sum(
salt['gramsPerLitre'] * products[salt['id']]['elements'].get('N_NH4', 0) * 10
for salt in summary['formulation']['salts']
)
self.assertEqual(ammonium, 0)
limit = next(item for item in summary['limits'] if item['symbol'] == 'N_NH4')
self.assertEqual(limit['maximumPpm'], 0)
self.assertLessEqual(
abs(chosen['joint']['chargeResidual']), chosen['joint']['chargeTolerance']
)
self.assertAlmostEqual(chosen['joint']['finalPh'], 6, delta=1e-4)

def test_unusable_ammonium_source_does_not_explode_search_work(self):
results = []
for include_forbidden in (False, True):
problem, doses, controls = capped_problem(include_forbidden)
result = solve_joint_problem(problem, doses, 0, **controls)
self.assertEqual(result['status'], 'stationary_point')
self.assertEqual(result['evaluation']['violations'], [])
self.assertLessEqual(abs(result['evaluation']['chargeResidual']), 2e-12)
for source in problem.fertilizers:
if source.nutrients.get('N_NH4', 0) > 0:
self.assertEqual(result['fertilizerDoses'][source.product_id], 0)
results.append(result)
self.assertAlmostEqual(
results[0]['evaluation']['loss'], results[1]['evaluation']['loss'], delta=1e-8
)
# A loose relative work guard, not an iteration or numerical tolerance change.
self.assertLessEqual(
results[1]['diagnostics']['evaluations'],
5 * results[0]['diagnostics']['evaluations'],
)


if __name__ == '__main__':
unittest.main()
102 changes: 102 additions & 0 deletions tests/test_sequential_accounting.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
# SPDX-FileCopyrightText: 2026 Flaha. Created by Rafat A. Al Khashan.
# SPDX-License-Identifier: Apache-2.0
# Disclaimer: planning software provided without warranty (Apache-2.0, section 7);
# its results are calculations, not dosing instructions.
"""Sequential pH plans report the nutrients in their actual returned doses."""

import math
import json
from pathlib import Path
import tempfile
import unittest

from flahax import (
calculate_equilibrium_ph,
catalogue_dose_totals,
catalogue_ph_reagents,
load_library,
plan_coupled_ph,
)


def acid_plan(maxima=None):
pool = [p for p in load_library()['salts'] if p['formula'] in ('KNO3', 'KH2PO4')]
acid = next(p for p in catalogue_ph_reagents() if p['chemicalFormula'] == 'HNO3')

def mix(recipe):
return calculate_equilibrium_ph(
catalogue_dose_totals({s['name']: s['gramsPerLitre'] for s in recipe['salts']}),
carbon_boundary='closed',
phases=[],
)

plan = plan_coupled_ph(
pool,
{'N_NO3': 140, 'K': 100, 'P': 20},
{},
4,
products=[acid],
mix=mix,
water_mass_kg=1000,
final_volume_litres=1000,
maximum_reagent_volume_litres=5,
maximum_concentrations=maxima,
)
return plan.candidates[0], pool


class SequentialAccountingTests(unittest.TestCase):
def test_report_counts_the_actual_nitric_dose(self):
candidate, pool = acid_plan()
by_id = {p['id']: p for p in pool}
# g/batch / 1000 L * 1000 mg/g; nitric acid carries one nitrogen per molecule.
nitrogen = candidate.reagent_mass_g * 0.65 * 14.0067 / 63.01284
nitrogen += math.fsum(
s['gramsPerLitre'] * by_id[s['id']]['elements'].get('N_NO3', 0) * 10
for s in candidate.recommendation['salts']
)
row = next(r for r in candidate.recommendation['rows'] if r['symbol'] == 'N_NO3')
self.assertAlmostEqual(row['final'], nitrogen, delta=1e-10)

def test_tight_maximum_and_total_n_use_the_actual_recipe(self):
candidate, pool = acid_plan({'N_NO3': 2})
by_id = {p['id']: p for p in pool}
nitrogen = candidate.reagent_mass_g * 0.65 * 14.0067 / 63.01284
nitrogen += math.fsum(
s['gramsPerLitre'] * by_id[s['id']]['elements'].get('N_NO3', 0) * 10
for s in candidate.recommendation['salts']
)
self.assertLess(nitrogen, 2)
self.assertLess(2 - nitrogen, 2e-6)
self.assertAlmostEqual(candidate.recommendation['totalN']['final'], nitrogen, delta=1e-10)
row = next(r for r in candidate.recommendation['rows'] if r['symbol'] == 'N_NO3')
self.assertAlmostEqual(2 - row['final'], 2 - nitrogen, delta=1e-10)
self.assertEqual(candidate.recommendation['limitViolations'], [])
self.assertNotIn('convex blend', candidate.recommendation['substitutionSearch']['method'])

def test_batch_reports_the_final_sequential_reagent_contribution(self):
from flahax.batch_cli import BatchOptions, run_batch

acid = next(p for p in catalogue_ph_reagents() if p['chemicalFormula'] == 'HNO3')
with tempfile.TemporaryDirectory() as directory:
path = Path(directory) / 'reagents.json'
path.write_text(json.dumps([acid]))
summary = run_batch(
BatchOptions(
water='ro', formula='Cucumber (Howard Resh)', ph=4, reagents=str(path)
)
)
chosen = summary['ph']['selected']
self.assertEqual(chosen['joint']['status'], 'sequential')
products = {p['id']: p for p in load_library()['salts']}
nitrate = chosen['mass_g_per_batch'] * 0.65 * 14.0067 / 63.01284
nitrate += math.fsum(
salt['gramsPerLitre'] * products[salt['id']]['elements'].get('N_NO3', 0) * 10
for salt in summary['formulation']['salts']
)
row = next(r for r in summary['formulation']['rows'] if r['symbol'] == 'N_NO3')
self.assertAlmostEqual(row['final'], nitrate, delta=1e-10)


if __name__ == '__main__':
unittest.main()
Loading
0