v0.3.0 — stoichiometry (limiting reagent & yield)

v0.3.0 — stoichiometry (limiting reagent, yield, leftovers)

New tool: stoichiometry. Give the equation and how much of each reactant you actually have
(mol or g) and get the extent of reaction, which reactant runs out first, how much of every product
forms, and what is left over. Add product + actualYieldG for theoretical and percent yield.

{ "equation": "C3H8 + O2 -> CO2 + H2O",
  "reactants": [{ "formula": "C3H8", "moles": 0.5 }, { "formula": "O2", "moles": 2 }],
  "product": "CO2", "actualYieldG": 44 }

→ limiting: ["O2"], extent: 0.4, CO2 1.2 mol / 52.8108 g, propane leftover 0.1 mol / 4.4097 g,
percentYield: 83.3162913646.

Deterministic rules:

• Every reactant needs an amount — an unstated one would make the limiting reagent undefined, so it is
  an error naming the missing species (never an assumption about “excess”).
• Exactly stoichiometric amounts report both reactants as limiting and no leftovers.
• Coefficients come from the exact rational balancer (the equation may be written unbalanced); grams are
  converted with the same IUPAC molar masses formula_mass reports.
• Errors instead of guesses: not-a-reactant, both/neither of moles/grams, duplicates, non-positive
  amounts, product not in the equation, actualYieldG without product.

Also in this release

• Oracle self-check (--check): the value oracle now verifies itself against outside rulers —
  8 published molar masses, 2 textbook coefficient sets, R and the molar volume, the pH definition, and
  mass-conservation / leftover bounds over every stoichiometry case. It caught a wrong product row while
  being written.
• Shared lossless-JSON helper: tests now use assertLossless from the canonical template, so -0,
  NaN/±Infinity and undefined live keys are all rejected.
• Numbers: 136 → 149 tests, coverage 88.89% → 90.35%.

---

v0.3.0 — 限量试剂计算（stoichiometry）

新工具 stoichiometry：给出方程式与每种反应物的实际量（mol 或 g），得到反应进度、哪种反应物先
耗尽、各产物生成量与剩余量；再给 product + actualYieldG 还能算理论产量与产率。

{ "equation": "C3H8 + O2 -> CO2 + H2O",
  "reactants": [{ "formula": "C3H8", "moles": 0.5 }, { "formula": "O2", "moles": 2 }],
  "product": "CO2", "actualYieldG": 44 }

→ 限量试剂 O2、进度 0.4、CO2 1.2 mol / 52.8108 g、丙烷剩 0.1 mol / 4.4097 g、产率
83.3162913646 %。

确定性规则：

• 每个反应物都必须给量——漏给会让「限量试剂」无定义，所以直接报错并点名缺哪个，不假设“过量”；
• 恰好按配比投料时，两种反应物都算限量，且没有任何剩余；
• 系数由精确有理数配平器给出（方程式可以不平衡着写），克的换算与 formula_mass 用同一套 IUPAC 摩尔质量；
• 一律报错而不猜：不是该方程的反应物、同时/都没给 mol 与 g、重复条目、非正数、产物不存在、只给产率不给产物。

同版本附带

• oracle 自检（--check）：期望值脚本现在拿外部尺子自检——8 个公开摩尔质量、2 组教科书系数、
  气体常数与摩尔体积、pH 定义，以及每个限量试剂用例的质量守恒与剩余边界。写自检时它当场抓出一处产物行取错。
• 共享无损 JSON 助手：测试改用标准模板的 assertLossless，-0、NaN/±Infinity、undefined 活键一并拦截。
• 数字：测试 136 → 149，覆盖率 88.89% → 90.35%。

v0.2.0 — balance_equation + gas_law

v0.2.0 — two new tools (6 total)

balance_equation — balances any equation with exact integer coefficients (BigInt-backed rationals, no floating-point artefacts):

• smallest integer solution, GCD-reduced and sign-normalized; per-element atom counts on both sides returned for verification
• ionic charges add a charge-conservation constraint (MnO4- + Fe2+ + H+ -> Mn2+ + Fe3+ + H2O → 1/5/8/1/5/4)
• hydrate water participates (CuSO4·5H2O -> CuSO4 + H2O → 1/1/5)
• unique: false when several independent balances exist (Fe + O2 -> Fe2O3 + Fe3O4 → 7/5/2/1, the smallest sum)
• honest failures: H2 + O2 -> H2O + N2 reports “a species would need coefficient 0” instead of silently dropping N2

gas_law — ideal-gas arithmetic with fixed units (atm/L/mol/K, plus kPa, mmHg, mL, °C):

• ideal solves PV = nRT for the one quantity you omit (exactly three of P/V/n/T required)
• molar_volume → 22.413969545014133 L/mol at STP (textbook 22.414)
• density ρ = P·M/(R·T) from a formula or a given molar mass; molar_mass back-calculates M = ρ·R·T/P
• R = 8.31446261815324 / 101.325; missing operands and non-positive values are errors, never guesses

Tests: 102 → 136, coverage 86.34% → 88.89% (baseline ratcheted). Numeric anchors come from the independent Python oracle test/anchors-chem.py (own periodic table, own tokenizer, own Fraction-based balancer) and are cross-checked against published textbook values (propane 1/5/3/4, permanganate/HCl 2/16/2/2/5/8, 22.414 L/mol).

中文：新增两个零依赖工具。balance_equation 用 BigInt 有理数精确配平（最小整数系数、电荷守恒、结晶水、多解时给最小解、配不平就明说）；gas_law 做理想气体四大运算（PV=nRT 解缺项、摩尔体积、气体密度、由密度反推摩尔质量），单位固定为 atm/L/mol/K 并附带 kPa、mmHg、mL、°C。测试 102 → 136，覆盖率 86.34% → 88.89%（基线棘轮上调），全部数值锚点由独立 Python oracle 生成并与教科书值交叉验证。

Install

dsh plugin --profile <profile> add github:TYEclipse/dsh-chem#v0.2.0

v0.1.0 — first release

dsh-chem v0.1.0

English: First release of the deterministic chemistry math toolbox — 4 zero-dependency tools:

• formula_mass — chemical formula parsing (nested parens, hydrates, ionic charges, coefficients) + IUPAC molar mass with per-element breakdown
• mass_moles — mass/mole/particle conversions (Avogadro 6.02214076e23), 6 modes
• solution — molarity, preparation mass, C1V1=C2V2 dilution, percent solutions (w/v, v/v, mass)
• ph — pH/pOH/[H+]/[OH-] conversions + Henderson-Hasselbalch buffers

102 tests, all anchors from an independent Python oracle cross-validated against published textbook molar masses.

中文：化学计量数学工具箱首发——化学式解析与摩尔质量、质量/摩尔/粒子换算、溶液浓度（摩尔浓度/稀释/百分比）、pH 与缓冲溶液，四工具零依赖，102 测试全绿（锚点独立 Python oracle + 教科书值交叉验证）。