water-chem-calc

Offline textbook water chemistry calculations with explicit units, visible working, and stated limits. Use the same 20 formulas through the wcc CLI, Python, a local browser page, or MCP. No API key, account, cloud calculation, or internet connection is required after installation.

For learning and estimates only. This tool does not select equipment, recommend chemical dosing, supply operating targets, or control a treatment plant.

Install

Python 3.11 or newer is required. There are no native chemistry engines or external services to install.

git clone https://github.com/GuoHaoyu1688/water-chem-calc.git
cd water-chem-calc
python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'

For an existing environment: pip install -r requirements.txt. On Windows, use .venv\Scripts\activate instead of the POSIX activation command.

Related MCP server: mcp-molecules

Quick start

wcc list --json
wcc calc ion_exchange.cycle_throughput --resin-volume 5m3 --capacity 800mol/m3 --ion-load 0.5mmol/L --json
wcc serve

The calculation produces approximately 8,000 m³ from 5 × 800 ÷ 0.5. The mol notation in this legacy example means moles of charge equivalents; the result includes a warning. Prefer --capacity 800eq/m3 --ion-load 0.5meq/L. For calcium, 1 mmol/L of Ca²⁺ is 2 meq/L, not 1 meq/L.

Open http://127.0.0.1:8769 for the browser calculator. All assets are local. Each formula has its own form and shows assumptions before submission and working, references, and the disclaimer after calculation. The server must remain running; this is an offline local application, not a standalone file:// HTML calculator.

Formula coverage

Every result includes original inputs, normalized values, the expression, substitution steps, values with units, assumptions, application bounds, references, warnings and the educational-use disclaimer. Full input specifications are available from wcc explain FORMULA --json and the formula catalogue.

Units and examples

Quote quantities containing spaces. Compact forms such as 5m3, 800eq/m3, 25degC, and 10uS/cm work; µS/cm, μS/cm, °C, kelvin and Fahrenheit are also accepted where dimensionally appropriate. A dimensional quantity requires units. A bare number is only valid for dimensionless inputs such as pH, charge and cycles. Arithmetic expressions are not accepted as quantity values.

wcc calc conductivity.pure_water --temperature '25 degC' --json
wcc calc ammonia.from_concentration --concentration '1 mg/L' --json
wcc calc conductivity.ions --ions '{"Ca":"0.1 mmol/L","Cl":"0.2 mmol/L"}' --json
wcc calc units.concentration --value '40.078 mg/L' --molar-mass '40.078 g/mol' --charge 2 --target 'meq/L' --json
wcc calc balance.cooling --evaporation '100 m3/h' --cycles 5 --drift '2 m3/h' --json
wcc calc oxygen.saturation --temperature '25 degC' --pressure '1 atm' --json

Examples above use fictional quantities. Ammonia mass is reported as NH3, not as nitrogen. Supported ion keys are H, OH, NH4, Na, K, Ca, Mg, Cl, SO4, HCO3, and NO3. Ionic concentrations accept mol/L or mg/L; they are already speciated inputs, not a general acid-base speciation model. Hardness units dH, fH, mmol/L, meq/L, and mg/L as CaCO3 are reporting conventions.

CLI and data

All commands are noninteractive. --json writes one standard JSON envelope to stdout; errors use {"ok":false,"error":{"code":"...","message":"..."}}. Exit codes: 0 success, 1 runtime/storage failure, 2 invalid inputs or model range, 3 missing file/formula; an interrupted long-running server exits 130.

Global options can appear before or after the command: --json, --quiet, --version, --data-dir PATH, --config config.toml. Configuration supports data_dir and timezone; default timezone is Asia/Shanghai. Explicit --data-dir overrides WCC_DATA_DIR, then config, then ./data.

CLI calculations save to data/calculations.sqlite. Identical formula/input objects share an ID and retain their first timestamp; different unit spellings can have separate records. Python, browser and MCP calculations do not save history. Snapshot JSON is {schema_version:1, records:[...]}; CSV has id and record_json columns and a UTF-8 BOM. Imports recompute every result and reject modified, incompatible or malformed records before writing anything. Backups contain a consistent SQLite snapshot; see AGENTS.md for restoration.

Python and MCP

from water_chem_calc import ion_exchange, conductivity, calculate

result = ion_exchange.cycle_throughput("5m3", "800eq/m3", "0.5meq/L")
print(result["result"]["throughput"])
print(conductivity.pure_water("25degC")["steps"])
result = calculate("balance.ions", {"ions": {"Ca": "1mmol/L", "Cl": "2mmol/L"}})

Every formula is also importable from its category module. MCP uses the official Python SDK and exposes list_formulas(category?), calculate(formula, inputs), and explain_formula(formula), all sharing the core engine. Example client config:

{
  "mcpServers": {
    "water-chem-calc": {
      "command": "/workspace/apps/water-chem-calc/.venv/bin/python",
      "args": ["-m", "water_chem_calc.mcp_server"]
    }
  }
}

Replace the executable with the actual installation path. Tool schemas are in docs/mcp-tools.json; a headless-agent guide is in AGENTS.md.

References, limitations and extension

Sources are public textbook/literature values, including NIST, USGS, DOE, WRC and peer-reviewed pure-water measurements. Methods and reference notes explain the approximations and independent checks. Calculations never fetch sources.

• The pure-water table gives about 0.0551 µS/cm at 25 °C. Rounded tabular constants and interpolation are for estimates, not conductivity-meter calibration.

• Ammonia inversion is unique only on the supported branch above the model's pure-water baseline. A shallow minimum near neutral water makes lower readings ambiguous. Other salts invalidate ammonia-only inversion.

• Oxygen data exclude hot deaerators, salinity and high pressure. Linear conductivity compensation does not replace pure-water or ammonia temperature models.

• LSI/RSI are simplified carbonate indices. Passing the implementation's screening bounds does not validate a real sample or establish steam-cycle applicability.

• Resin working capacities and regeneration levels must be supplied by the user. Geometry, throughput and mass arithmetic do not constitute equipment design.

• No uncertainty propagation, real-water activity correction, dynamic process model, laboratory certification, or operating-control advice is supplied.

Register new formulas under src/water_chem_calc/formulas/*.yaml, implement them in core/calculations.py, add a dispatcher entry and an importable category wrapper, and add at least two independent hand checks plus invalid-input examples. The CLI catalogue, input flags and browser forms read the YAML automatically. Constants are bundled under src/water_chem_calc/data/constants.yaml; runtime data/ remains private and ignored. YAML never executes Python expressions or loads arbitrary plugins.

FAQ

Why does ppm require density? ppm means mg/kg. It equals mg/L only when the solution density is 1 kg/L; the default assumption is visible in the result.

Why is 1 mmol/L calcium different from 1 meq/L? Calcium is divalent; its charge amount is twice its amount of ions. Conductivity tables already contain molar conductivities, so charge is not multiplied a second time there.

Why is a below-baseline ammonia reading rejected? Replacing highly mobile H+ with NH4+ initially lowers conductivity by a small amount, creating two possible ammonia concentrations for a narrow conductivity interval.

Can I enter boiler oxygen at 150 °C? No. That is outside this freshwater model. The tool rejects extrapolation rather than inventing high-temperature validity.

Verification and roadmap

ruff check .
ruff format --check .
pytest -q --cov=water_chem_calc
python scripts/rebuild_oxygen_table.py

Tests include two hand-checked examples per formula, unit errors, model boundaries, water autoionization, ambiguous inversion, ionic charge closure, infeasible balances, transactional import/export, backups, CLI, MCP and HTTP. CI targets Python 3.11/3.12 on Ubuntu. Verification record separates local checks from CI.

Future work: validated uncertainty reporting, additional ionic species with primary references, and carefully bounded activity models. MIT license; see LICENSE.