dsh-chem

Deterministic chemistry math for DeepSeek Harness (dsh) — zero runtime dependencies, pure arithmetic over IUPAC data.

中文简介：化学计量数学工具箱。四个零依赖确定性工具——化学式解析与摩尔质量（支持嵌套括号、结晶水、离子电荷）、质量/摩尔/粒子数换算、溶液浓度（摩尔浓度、稀释 C1V1=C2V2、百分比浓度）、pH/pOH 与缓冲溶液。专门替代 LLM 高频出错的化学心算。

Why this plugin

Agents get chemistry arithmetic wrong in predictable ways:

• Molar-mass sums — miscounted subscripts, dropped hydrates (CuSO4·5H2O is 249.68 g/mol, not 159.61).
• Element case sensitivity — "Co" is cobalt (58.93), "CO" is carbon monoxide (28.01).
• Dilution math — C1V1 = C2V2 with a wrong or missing factor.
• pH log/antilog arithmetic — pH of 0.01 M HCl is 2, not 12.

These tools replace all of it with deterministic tables and formulas. No network, no state, no dependencies — install and call.

Tools

formula_mass — parse a formula and compute molar mass

Accepts nested parentheses, hydrate dots (CuSO4·5H2O, * also works), leading coefficients (2H2O) and ionic charges. Uses IUPAC standard atomic weights; elements without stable isotopes use the most-stable-isotope mass number (flagged with usedMassNumber).

{ "formula": "H2SO4" }

{
  "valid": true,
  "formula": "H2SO4",
  "molarMass": 98.072,
  "elements": [
    { "symbol": "H", "name": "Hydrogen", "count": 2, "atomicMass": 1.008, "massContribution": 2.016, "massFraction": 0.02056 },
    { "symbol": "O", "name": "Oxygen", "count": 4, "atomicMass": 15.999, "massContribution": 63.996, "massFraction": 0.65254 },
    { "symbol": "S", "name": "Sulfur", "count": 1, "atomicMass": 32.06, "massContribution": 32.06, "massFraction": 0.32690 }
  ],
  "usedMassNumber": false
}

Charge disambiguation rule (documented, deterministic): digits immediately before a trailing +/- belong to the ionic charge only when every element parsed so far is the same single element — Fe3+ is Fe with 3+, S2- is S with 2-, Ca2+ is Ca with 2+. Otherwise they are a subscript and the bare sign is a 1-unit charge — NH4+ is N + H4 with +, NO3- is N + O3 with -. The explicit form SO4^2- is always the charge, and O2^+ escapes the rule for subscript-before-charge. Single lowercase symbols are auto-corrected (h2o → H2O); multi-letter lowercase runs are rejected with a case-sensitivity hint.

mass_moles — mass / amount / particle conversions

Six modes (mass_to_moles, moles_to_mass, mass_to_particles, particles_to_mass, moles_to_particles, particles_to_moles), molar mass from a formula or given directly, Avogadro constant 6.02214076e23.

{ "mode": "mass_to_moles", "value": 98, "formula": "H2SO4" }

{ "valid": true, "mode": "mass_to_moles", "molarMass": 98.072, "avogadro": 6.02214076e+23, "formula": "H2SO4", "moles": 0.9992658455012644 }

solution — concentration math

Four operations:

• molarity — mass of solute + volume → mol/L: { "operation": "molarity", "massG": 58.44, "volumeMl": 250, "formula": "NaCl" } → molarity: 4
• prepare — target molarity + volume → solute mass: { "operation": "prepare", "molarity": 0.1, "volumeMl": 500, "formula": "NaOH" } → massG: 1.99985
• dilute — C1V1 = C2V2, give any three of c1/v1/c2/v2 (M, mL) and the missing one is computed: { "operation": "dilute", "c1": 2, "c2": 0.5, "v2": 250 } → v1: 62.5, solved: "v1"
• percent — wv (g per 100 mL), vv (mL per 100 mL) or mass percent: { "operation": "percent", "percentType": "wv", "soluteG": 5, "solutionMl": 200 } → percent: 2.5

ph — pH chemistry at 25 °C (Kw = 1e-14)

Five operations:

• from_h — { "operation": "from_h", "hConc": 0.001 } → pH: 3, pOH: 11, ohConc: 1e-11
• from_oh — [OH-] → pH/pOH
• from_ph — pH → [H+]
• from_poh — pOH → [OH-]
• buffer — Henderson–Hasselbalch: { "operation": "buffer", "pKa": 4.76, "acidConc": 0.2, "baseConc": 0.1 } → pH: 4.4589700043360185, bufferRatio: 0.5

Negative pH for >1 M acids is supported ([H+] = 2 → pH −0.301).

Install

dsh plugin --profile <profile> add github:TYEclipse/dsh-chem

(Requires pnpm on PATH — dsh plugin forwards installs to it.)

Verify

dsh plugin --profile <profile> list      # dsh-chem present
dsh --dump-config --profile <profile>    # == dsh-chem layer present

Development

pnpm install
pnpm build     # tsc -> dist/ (committed; git installs do not build)
pnpm test      # vitest, 102 tests
pnpm lint      # oxlint src test

All numeric anchors are generated by the independent Python oracle test/anchors-chem.py (own periodic table + own tokenizer) and cross-validated against published textbook molar masses (H2O 18.015, H2SO4 98.08, NaCl 58.44, Ca(OH)2 74.09, CuSO4·5H2O 249.68, C6H12O6 180.16, KMnO4 158.03, NH3 17.03).

License

MIT