@classytic/stage 0.2.0 → 0.4.0

package/dist/chem/relations.mjs

@@ -0,0 +1,299 @@
+import { AVOGADRO, GAS_CONSTANT, ZERO_CELSIUS_K } from "../core/constants.mjs";
+import { relation } from "../relation/index.mjs";
+
+//#region src/chem/relations.ts
+/**
+* The quantitative relations of chemistry, declared once and solvable in any direction.
+*
+* ## Why declared and not written as functions
+*
+* A textbook ends its quantitative chapter with a page of formulae to memorise, each one written
+* the way it is most often used and rearranged by hand whenever it is not. That page is the part
+* learners photograph and the part they get wrong, because a formula written one way round has to
+* be turned round under exam pressure.
+*
+* A relation has no preferred direction. `n = c * V` answers for the moles, the concentration or
+* the volume, and it shows the rearrangement and the substitution while it does it. So instead of
+* three functions per formula, and a fourth when someone needs the working, there is one
+* declaration:
+*
+* ```ts
+* MOLES_FROM_SOLUTION.solve({ c: 0.100, V: qty(24.50, 'cm3') });  // n, straight off the burette
+* MOLES_FROM_SOLUTION.solve({ n: 2.45e-3, V: 0.0245 });           // c, the titration answer
+* MOLES_FROM_SOLUTION.steps({ c: 0.100, V: 0.0245 });             // the working, line by line
+* ```
+*
+* ## Units are checked when the relation is declared
+*
+* A relation whose units do not balance is refused at declaration, before anything can be written
+* against it. That matters more than it sounds: a wrong formula that lessons, labs and the marker
+* all share is worse than no formula, because everything then agrees and everything is wrong.
+*
+* It also means a volume can be given in cubic centimetres against a concentration in mol per cubic
+* decimetre, and the factor of a thousand sorts itself out. That single conversion is the most
+* common arithmetic slip in volumetric analysis, and here it is not a step anyone performs.
+*
+* ## Declared lazily, so importing one does not build them all
+*
+* Each is behind a getter that builds it on first use and remembers it. Building nineteen relations
+* at import time would parse nineteen expressions and run nineteen dimensional checks for a caller
+* that wanted one, and would pin all of them into any bundle that touched this file.
+*
+* Pure: no React, no pixels.
+*/
+/** Build once, on first use. */
+function lazy(build) {
+	let made;
+	return () => made ??= build();
+}
+/** `n = m / M`, moles from a mass weighed out. */
+const molesFromMass = lazy(() => relation("n = m / M", {
+	n: "mol",
+	m: "g",
+	M: "g/mol"
+}, "moles from mass"));
+/** `n = c * V`, moles in a volume of solution. Give V in cm3 and the conversion looks after itself. */
+const molesFromSolution = lazy(() => relation("n = c * V", {
+	n: "mol",
+	c: "mol/dm3",
+	V: "dm3"
+}, "moles in a solution"));
+/** `n = N / L`, moles from a number of particles. */
+const molesFromParticles = lazy(() => relation("n = N / L", {
+	n: "mol",
+	N: "1",
+	L: "1/mol"
+}, "moles from a particle count"));
+/**
+* `n = V / Vm`, moles of a gas from its volume at a stated molar volume.
+*
+* The molar volume is a variable rather than a constant baked in, because it is not one: it depends
+* on temperature and pressure, and quoting 22.4 dm3/mol without saying "at standard temperature and
+* pressure" is where a great many wrong answers begin.
+*/
+const molesFromGasVolume = lazy(() => relation("n = V / Vm", {
+	n: "mol",
+	V: "dm3",
+	Vm: "dm3/mol"
+}, "moles of a gas"));
+/** `P * V = n * R * T`, the ideal gas equation. Temperature in kelvin, as it must be. */
+const idealGas = lazy(() => relation("P * V = n * R * T", {
+	P: "Pa",
+	V: "m3",
+	n: "mol",
+	R: "J/mol/K",
+	T: "K"
+}, "the ideal gas equation"));
+/** `P1 * V1 / T1 = P2 * V2 / T2`, one gas under two sets of conditions. */
+const combinedGasLaw = lazy(() => relation("P1 * V1 / T1 = P2 * V2 / T2", {
+	P1: "Pa",
+	V1: "m3",
+	T1: "K",
+	P2: "Pa",
+	V2: "m3",
+	T2: "K"
+}, "the combined gas law"));
+/** `c = n / V`, concentration from moles and volume. */
+const concentration = lazy(() => relation("c = n / V", {
+	c: "mol/dm3",
+	n: "mol",
+	V: "dm3"
+}, "concentration"));
+/**
+* `c1 * V1 = c2 * V2`, dilution.
+*
+* True because the moles do not change when water is added, which is the whole of the derivation
+* and is worth saying every time it is used.
+*/
+const dilution = lazy(() => relation("c1 * V1 = c2 * V2", {
+	c1: "mol/dm3",
+	V1: "dm3",
+	c2: "mol/dm3",
+	V2: "dm3"
+}, "dilution"));
+/** `m_conc = c * V * M`, the mass to weigh out to make up a standard solution. */
+const massForSolution = lazy(() => relation("m = c * V * M", {
+	m: "g",
+	c: "mol/dm3",
+	V: "dm3",
+	M: "g/mol"
+}, "mass for a standard solution"));
+/**
+* `b = n / m_solvent`, molality: moles of solute per kilogram of SOLVENT.
+*
+* Not per kilogram of solution, and not per litre of anything. The distinction from molarity is the
+* point of having both: molality uses a mass, so it does not change when the temperature does,
+* which is why it is the one that appears in freezing point and boiling point work.
+*/
+const molality = lazy(() => relation("b = n / ms", {
+	b: "mol/kg",
+	n: "mol",
+	ms: "kg"
+}, "molality"));
+/** `rho = m / V`, density, which is what converts between a volume and a mass of solution. */
+const density = lazy(() => relation("rho = m / V", {
+	rho: "g/cm3",
+	m: "g",
+	V: "cm3"
+}, "density"));
+/**
+* `A = eps * c * l`, the Beer-Lambert law.
+*
+* Absorbance is dimensionless: it is a logarithm of a ratio of intensities, so it has no unit, and
+* the molar absorptivity carries whatever is needed to cancel the concentration and the path
+* length. Declaring it that way is what lets the units check pass, and it is also the honest
+* description of what absorbance is.
+*
+* Solving it for the concentration is the entire quantitative use of a colorimeter: measure the
+* absorbance of a coloured solution, and read its concentration off.
+*/
+const beerLambert = lazy(() => relation("A = eps * c * l", {
+	A: "1",
+	eps: "dm3/mol/cm",
+	c: "mol/dm3",
+	l: "cm"
+}, "the Beer-Lambert law"));
+/**
+* `A = log10(I0 / I)`, absorbance from the light that went in and the light that came out.
+*
+* The definition the law above is built on, and the reason absorbance has no unit.
+*/
+const absorbanceFromIntensity = lazy(() => relation("A = log10(I0 / I)", {
+	A: "1",
+	I0: "1",
+	I: "1"
+}, "absorbance from transmitted light"));
+/** `q = m * c * dT`, the heat a measured temperature change accounts for. */
+const heatEnergy = lazy(() => relation("q = m * cs * dT", {
+	q: "J",
+	m: "g",
+	cs: "J/g/K",
+	dT: "K"
+}, "heat from a temperature change"));
+/**
+* The values these relations are usually fed, kept as data with their units attached.
+*
+* Passed in rather than compiled into the relations. A molar volume of 24 dm3/mol is only right at
+* room temperature and 22.4 only at standard temperature and pressure, and a relation that hid
+* either inside itself would give a confidently wrong answer under the other conditions.
+*/
+const CONSTANTS = {
+	/** Avogadro constant, per mole. */
+	avogadro: AVOGADRO,
+	/** Molar gas constant, J per mole per kelvin. */
+	gasConstant: GAS_CONSTANT,
+	/** Molar volume of an ideal gas at 273.15 K and 100 kPa, dm3 per mole. */
+	molarVolumeStp: 22.7,
+	/** Molar volume at 298 K and 100 kPa, dm3 per mole: the figure room-temperature questions use. */
+	molarVolumeRoom: 24,
+	/** Specific heat capacity of water, J per gram per kelvin. */
+	waterHeatCapacity: 4.18
+};
+/** Kelvin from degrees Celsius. One line, and the source of a great many wrong gas answers. */
+const kelvinFrom = (celsius) => celsius + ZERO_CELSIUS_K;
+/**
+* The derivations, so a lesson can say why a formula is true and not only how to use it.
+*
+* Three kinds, and the difference between them is worth as much as the formulae. A definition has
+* nothing underneath it. A derived relation follows from others plus something held fixed, and the
+* chain is executable, so the claim is checked rather than asserted. A measured one was observed by
+* somebody, and saying so is the difference between teaching chemistry and teaching a formula
+* sheet.
+*/
+const DERIVATIONS = {
+	/**
+	* Dilution, the one everyone memorises and nobody can justify.
+	*
+	* The argument is three sentences long. Adding water changes the volume and changes the
+	* concentration, and does not change the number of moles. So `n = cV` holds at both ends with the
+	* same n, and that is the rule.
+	*/
+	dilution: {
+		kind: "derived",
+		summary: "Adding water changes how much there is of the solution and how concentrated it is, and changes nothing about how much solute is in it.",
+		invariant: "the number of moles of solute, which water does not create or destroy",
+		arrivesAt: "c2",
+		steps: [{
+			relation: molesFromSolution,
+			solveFor: "n",
+			using: {
+				c: "c1",
+				V: "V1"
+			},
+			gives: "n",
+			because: "first find how many moles the stock solution you measured out actually contains"
+		}, {
+			relation: concentration,
+			solveFor: "c",
+			using: {
+				n: "n",
+				V: "V2"
+			},
+			gives: "c2",
+			because: "those same moles are now spread through the larger volume, so the concentration is what they make up in it"
+		}]
+	},
+	/**
+	* The mass to weigh out for a standard solution.
+	*
+	* Two definitions laid end to end, which is worth showing because learners meet it as a third
+	* formula rather than as the two they already have.
+	*/
+	massForSolution: {
+		kind: "derived",
+		summary: "You cannot weigh out moles, so work out how many moles the solution needs and then what that many moles weigh.",
+		invariant: "nothing is held fixed here: this is two definitions used one after the other",
+		arrivesAt: "m",
+		steps: [{
+			relation: molesFromSolution,
+			solveFor: "n",
+			using: {
+				c: "c",
+				V: "V"
+			},
+			gives: "n",
+			because: "the volume you are making up, at the concentration you want, needs this many moles"
+		}, {
+			relation: molesFromMass,
+			solveFor: "m",
+			using: {
+				n: "n",
+				M: "M"
+			},
+			gives: "m",
+			because: "and that many moles of this substance weigh this much, which is what goes on the balance"
+		}]
+	},
+	concentration: {
+		kind: "definition",
+		summary: "Concentration is how many moles are dissolved in each unit of volume. That is what the word means."
+	},
+	molesFromMass: {
+		kind: "definition",
+		summary: "Molar mass is defined as the mass of one mole, so dividing a mass by it counts how many moles that mass is."
+	},
+	/**
+	* The Beer-Lambert law, which is measured and is usually taught as though it were not.
+	*
+	* It is stated as a formula with no hint that anyone ever checked it, and it does in fact fail:
+	* at high concentrations absorbance stops rising in step, which is why a calibration curve is
+	* drawn and a sample too dark to read is diluted before it is measured.
+	*/
+	beerLambert: {
+		kind: "measured",
+		summary: "Each layer of a solution takes the same FRACTION of the light reaching it, so the light left falls away multiplicatively and its logarithm falls in step with both the concentration and the distance travelled.",
+		evidence: "Measured: double the concentration of a coloured solution, or double the length of the cell, and the absorbance doubles. It stops holding at high concentrations, which is why a calibration curve is plotted rather than assumed and why a dark sample is diluted before it is read."
+	},
+	idealGas: {
+		kind: "measured",
+		summary: "Pressure times volume divided by temperature comes to the same thing for any gas, once there is enough of it to average over and the particles are far enough apart to ignore each other.",
+		evidence: "Measured, and by three separate people on three separate pairs of variables before anyone combined them. It is a limit rather than a law: every real gas departs from it as it is compressed or cooled toward its boiling point, which is exactly when its particles stop being far apart."
+	},
+	heatEnergy: {
+		kind: "definition",
+		summary: "Specific heat capacity is defined as the energy one gram needs to warm by one kelvin, so the total is that energy times the grams times the kelvin."
+	}
+};
+
+//#endregion
+export { CONSTANTS, DERIVATIONS, absorbanceFromIntensity, beerLambert, combinedGasLaw, concentration, density, dilution, heatEnergy, idealGas, kelvinFrom, massForSolution, molality, molesFromGasVolume, molesFromMass, molesFromParticles, molesFromSolution };

package/dist/chem/skeleton.d.mts

@@ -0,0 +1,51 @@
+import { Structure } from "./molecule.mjs";
+
+//#region src/chem/skeleton.d.ts
+/**
+ * Atoms that lie on a ring, as one list per ring.
+ *
+ * Found by removing terminal atoms repeatedly: whatever survives is the ring system, because only a
+ * ring has no free end to peel. Simple, and right for the one-ring molecules this subset covers.
+ */
+declare function ringSystems(structure: Structure): number[][];
+/**
+ * The longest chain through the structure, as atom ids in order.
+ *
+ * ## Which atoms count as backbone
+ *
+ * Every carbon, plus any heteroatom the chain RUNS THROUGH. The ester oxygen and the amide nitrogen
+ * are in the middle of a chain and are drawn in it; a carbonyl oxygen, a hydroxyl, an amine or a
+ * halogen hangs off the side and is drawn as a substituent.
+ *
+ * The test is how many bonds the atom has out into the skeleton, counting an open valence as one,
+ * because an open valence is where the chain continues into the next repeat unit. Two or more means
+ * the chain passes through.
+ *
+ * Restricting the walk to CARBON was the first version and it broke the thing this exists for: a
+ * nylon repeat unit is a chain of six carbons, an amide nitrogen and six more carbons, and a walk
+ * that could not cross the nitrogen reported half the molecule as one enormous substituent, which
+ * the drawing then collapsed into the label "C6H29N2".
+ *
+ * Ring atoms are excluded, because a ring is reported separately by {@link backboneOf}.
+ */
+declare function longestChain(structure: Structure): number[];
+interface Backbone {
+  /** The atoms drawn across the page, in order. */
+  readonly atoms: readonly number[];
+  /** The backbone is a closed ring rather than an open chain. */
+  readonly ring: boolean;
+  /** True when the ring is aromatic, so it takes a circle rather than alternating bonds. */
+  readonly aromatic: boolean;
+  /** Everything else, grouped by which backbone atom it hangs from. */
+  readonly branches: ReadonlyMap<number, readonly number[]>;
+}
+/**
+ * The backbone and its branches.
+ *
+ * A branch is every atom reachable from a backbone atom without going back through the backbone, so
+ * a carboxyl group on a ring comes back as three atoms attached at one vertex rather than as three
+ * unrelated neighbours.
+ */
+declare function backboneOf(structure: Structure): Backbone;
+//#endregion
+export { Backbone, backboneOf, longestChain, ringSystems };

package/dist/chem/skeleton.mjs

@@ -0,0 +1,186 @@
+import { bondsAt, otherEnd } from "./molecule.mjs";
+
+//#region src/chem/skeleton.ts
+/**
+* skeleton, the backbone of a structure and what hangs off it.
+*
+* WHAT THIS IS FOR. Two jobs need the same answer. Drawing a molecule needs to know which atoms form
+* the chain that runs across the page and which are substituents hanging off it. Naming a molecule
+* needs exactly the same thing, because an IUPAC name is the longest chain plus its branches. So the
+* perception is done once, here, and returns atom ids rather than coordinates or syllables.
+*
+* ## Why the longest chain, and what "longest" means
+*
+* The backbone is the longest path through the skeleton, which is every carbon plus the heteroatoms
+* the chain runs THROUGH: the oxygen in an ester link, the nitrogen in an amide. A carbonyl oxygen
+* or a hydroxyl hangs off the side and is a substituent. Found by the standard trick for a tree:
+* walk from any atom to the furthest one, then walk again from there, and the second walk traces the
+* diameter.
+*
+* ## Rings come first
+*
+* A ring is not a chain and cannot be drawn as one, so a structure containing a ring reports the
+* ring as its backbone and everything else as substituents. That is also how a chemist draws it:
+* benzene-1,4-dicarboxylic acid is a hexagon with two groups on it, not a chain with a hexagon in
+* the middle.
+*
+* ## The subset this handles, stated rather than implied
+*
+* One ring, and substituents that are single atoms or small terminal groups. That covers every
+* molecule in AS and A2 organic chemistry. A fused polycyclic, or a long branch off a long branch,
+* returns a backbone that is correct and a drawing that would be cramped, and the honest answer
+* there is a hand-placed structure rather than a computed one.
+*
+* Pure: no React, no pixels.
+*/
+/** Heavy atoms bonded to this one. */
+const linked = (structure, id) => bondsAt(structure, id).map((b) => otherEnd(b, id));
+/**
+* Atoms that lie on a ring, as one list per ring.
+*
+* Found by removing terminal atoms repeatedly: whatever survives is the ring system, because only a
+* ring has no free end to peel. Simple, and right for the one-ring molecules this subset covers.
+*/
+function ringSystems(structure) {
+	const alive = new Set(structure.atoms.map((a) => a.id));
+	let peeled = true;
+	while (peeled) {
+		peeled = false;
+		for (const id of [...alive]) if (linked(structure, id).filter((n) => alive.has(n)).length <= 1) {
+			alive.delete(id);
+			peeled = true;
+		}
+	}
+	if (alive.size === 0) return [];
+	const systems = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const id of alive) {
+		if (seen.has(id)) continue;
+		const piece = [];
+		const stack = [id];
+		seen.add(id);
+		while (stack.length) {
+			const at = stack.pop();
+			piece.push(at);
+			for (const n of linked(structure, at)) if (alive.has(n) && !seen.has(n)) {
+				seen.add(n);
+				stack.push(n);
+			}
+		}
+		systems.push(piece);
+	}
+	return systems;
+}
+/** Walk outward from an atom, returning the furthest one and the path to it. */
+function furthest(structure, from, only) {
+	const previous = /* @__PURE__ */ new Map();
+	const seen = new Set([from]);
+	let frontier = [from];
+	let last = from;
+	while (frontier.length) {
+		const next = [];
+		for (const at of frontier) {
+			last = at;
+			for (const n of linked(structure, at)) {
+				if (!only.has(n) || seen.has(n)) continue;
+				seen.add(n);
+				previous.set(n, at);
+				next.push(n);
+			}
+		}
+		if (next.length) frontier = next;
+		else break;
+	}
+	const path = [last];
+	let cursor = last;
+	while (previous.has(cursor)) {
+		cursor = previous.get(cursor);
+		path.unshift(cursor);
+	}
+	return path;
+}
+/**
+* The longest chain through the structure, as atom ids in order.
+*
+* ## Which atoms count as backbone
+*
+* Every carbon, plus any heteroatom the chain RUNS THROUGH. The ester oxygen and the amide nitrogen
+* are in the middle of a chain and are drawn in it; a carbonyl oxygen, a hydroxyl, an amine or a
+* halogen hangs off the side and is drawn as a substituent.
+*
+* The test is how many bonds the atom has out into the skeleton, counting an open valence as one,
+* because an open valence is where the chain continues into the next repeat unit. Two or more means
+* the chain passes through.
+*
+* Restricting the walk to CARBON was the first version and it broke the thing this exists for: a
+* nylon repeat unit is a chain of six carbons, an amide nitrogen and six more carbons, and a walk
+* that could not cross the nitrogen reported half the molecule as one enormous substituent, which
+* the drawing then collapsed into the label "C6H29N2".
+*
+* Ring atoms are excluded, because a ring is reported separately by {@link backboneOf}.
+*/
+function longestChain(structure) {
+	const inRing = new Set(ringSystems(structure).flat());
+	const eligible = new Set(structure.atoms.filter((a) => {
+		if (inRing.has(a.id)) return false;
+		if (a.element === "C") return true;
+		return linked(structure, a.id).length + (a.openValence ?? 0) >= 2;
+	}).map((a) => a.id));
+	if (eligible.size === 0) return [];
+	const start = [...eligible][0];
+	const firstPath = furthest(structure, start, eligible);
+	const end = firstPath[firstPath.length - 1];
+	return furthest(structure, end, eligible);
+}
+/**
+* The backbone and its branches.
+*
+* A branch is every atom reachable from a backbone atom without going back through the backbone, so
+* a carboxyl group on a ring comes back as three atoms attached at one vertex rather than as three
+* unrelated neighbours.
+*/
+function backboneOf(structure) {
+	const ring = ringSystems(structure)[0];
+	const atoms = ring && ring.length >= 3 ? orderRing(structure, ring) : longestChain(structure);
+	const onBackbone = new Set(atoms);
+	const branches = /* @__PURE__ */ new Map();
+	for (const id of atoms) for (const start of linked(structure, id)) {
+		if (onBackbone.has(start)) continue;
+		const group = [];
+		const seen = new Set([start, ...onBackbone]);
+		const stack = [start];
+		while (stack.length) {
+			const at = stack.pop();
+			group.push(at);
+			for (const n of linked(structure, at)) {
+				if (seen.has(n)) continue;
+				seen.add(n);
+				stack.push(n);
+			}
+		}
+		branches.set(id, [...branches.get(id) ?? [], ...group]);
+	}
+	return {
+		atoms,
+		ring: Boolean(ring && ring.length >= 3),
+		aromatic: Boolean(ring?.every((id) => structure.atoms[id].aromatic)),
+		branches
+	};
+}
+/** Put a ring's atoms in the order they are bonded, so a polygon can be walked round. */
+function orderRing(structure, ring) {
+	const inRing = new Set(ring);
+	const ordered = [ring[0]];
+	const seen = new Set(ordered);
+	while (ordered.length < ring.length) {
+		const at = ordered[ordered.length - 1];
+		const next = linked(structure, at).find((n) => inRing.has(n) && !seen.has(n));
+		if (next === void 0) break;
+		seen.add(next);
+		ordered.push(next);
+	}
+	return ordered;
+}
+
+//#endregion
+export { backboneOf, longestChain, ringSystems };

package/dist/chem/solution.d.mts

@@ -0,0 +1,116 @@
+//#region src/chem/solution.d.ts
+/**
+ * Sparingly soluble salts: how much dissolves, and when something comes out of solution.
+ *
+ * ## Why a solubility product exists at all
+ *
+ * A salt that barely dissolves sits in equilibrium with its own ions. Once the solid is there, more
+ * solid changes nothing about the solution, so the equilibrium constant contains only the ions:
+ *
+ *     MpAq(s) ⇌ p M^q+(aq) + q A^p-(aq)        Ksp = [M]^p [A]^q
+ *
+ * That is the whole definition, and everything else here follows from it plus counting.
+ *
+ * ## Why Ksp values cannot be compared directly, which is the standard trap
+ *
+ * Silver chloride has a Ksp of 1.8e-10 and silver chromate 1.1e-12, so the chromate looks a hundred
+ * times less soluble. It is roughly seven times MORE soluble. The numbers are not comparable
+ * because they are not the same kind of number: one is a product of two concentrations and the
+ * other of three, so they have different units and different powers.
+ *
+ * The only honest comparison is between SOLUBILITIES, which is what {@link solubilityFromKsp}
+ * computes, and it is computed rather than tabulated so the comparison can be made for any pair.
+ *
+ * ## Precipitation is a comparison, not a rule
+ *
+ * Mixing two solutions does not ask whether a salt is "insoluble". It asks whether the ions that
+ * are now present exceed what the solution can hold: form the same product from the ACTUAL
+ * concentrations and compare it with Ksp. Above it, solid appears until the product falls back;
+ * below it, nothing happens however insoluble the salt is said to be.
+ *
+ * Pure: no React, no pixels.
+ */
+/** A salt as its stoichiometry: p cations of charge q+, q anions of charge p-. */
+interface SaltFormula {
+  readonly formula: string;
+  /** Cations per formula unit. */
+  readonly cations: number;
+  /** Anions per formula unit. */
+  readonly anions: number;
+}
+interface SparinglySoluble extends SaltFormula {
+  /** Solubility product at 298 K. Units depend on the stoichiometry, which is the point. */
+  readonly ksp: number;
+}
+/**
+ * Solubility products at 298 K, from standard tables.
+ *
+ * Deliberately a mixed set of stoichiometries. A table of nothing but 1:1 salts would let the
+ * comparison trap below stay invisible, which is the one thing this data is most useful for.
+ */
+declare const SOLUBILITY_PRODUCTS: readonly SparinglySoluble[];
+declare const saltByFormula: (formula: string) => SparinglySoluble | undefined;
+/**
+ * The solubility product a given solubility implies.
+ *
+ * Dissolving S moles of MpAq gives pS of the cation and qS of the anion, so the product is
+ * (pS)^p (qS)^q. The powers and the multipliers are both there, and dropping either is the usual
+ * way this goes wrong: silver chromate gives (2S)²(S), not S³ and not (2S)(S).
+ */
+declare function kspFromSolubility(salt: SaltFormula, solubility: number): number;
+/**
+ * The solubility a solubility product implies, in mol per cubic decimetre.
+ *
+ * The inverse of the above, solved rather than rearranged by hand, because the rearrangement is a
+ * different expression for every stoichiometry:
+ *
+ *     Ksp = p^p q^q S^(p+q)     so     S = (Ksp / (p^p q^q))^(1/(p+q))
+ */
+declare function solubilityFromKsp(salt: SparinglySoluble): number;
+/**
+ * The ionic product for concentrations that are actually present.
+ *
+ * The same expression as Ksp and a different quantity: Ksp is what a SATURATED solution has, this
+ * is what THIS solution has. Comparing them is the whole of precipitation prediction, and calling
+ * both of them Ksp is why that comparison so often gets skipped.
+ */
+declare function ionicProduct(salt: SaltFormula, cation: number, anion: number): number;
+type PrecipitationVerdict = 'precipitate' | 'saturated' | 'stays dissolved';
+interface PrecipitationCheck {
+  readonly ionicProduct: number;
+  readonly ksp: number;
+  readonly verdict: PrecipitationVerdict;
+  readonly because: string;
+}
+/**
+ * Whether mixing these concentrations produces a solid.
+ *
+ * Returns the reasoning, because "will it precipitate" is answered by a comparison and a learner
+ * who is handed only the verdict never sees which two numbers were compared.
+ */
+declare function willPrecipitate(salt: SparinglySoluble, cation: number, anion: number): PrecipitationCheck;
+/**
+ * Solubility when one of the ions is already in the water: the common ion effect.
+ *
+ * Adding chloride to a saturated silver chloride solution pushes the equilibrium back and less
+ * silver chloride dissolves. The equilibrium itself has not changed; there is simply less room.
+ *
+ * Solved numerically rather than algebraically. With a common ion the equation is
+ * (pS + existing)^p (qS)^q = Ksp for a common cation, which is a polynomial of degree p+q with no
+ * tidy closed form beyond the simplest salts. It is monotonic in S, so bisection finds the root
+ * exactly and works for every stoichiometry rather than for the two that factorise.
+ */
+declare function solubilityWithCommonIon(salt: SparinglySoluble, existing: number, ion?: 'cation' | 'anion'): number;
+/**
+ * Compare two salts by how much of each actually dissolves.
+ *
+ * The reason this exists rather than a sort on Ksp: silver chloride's 1.8e-10 against silver
+ * chromate's 1.1e-12 says the chromate is a hundred times less soluble, and it is about seven times
+ * MORE soluble. The two numbers are products of different numbers of concentrations, so they are
+ * not the same kind of quantity and comparing them is meaningless.
+ */
+declare function moreSoluble(a: SparinglySoluble, b: SparinglySoluble): SparinglySoluble;
+/** Whether comparing two salts by Ksp alone would give the wrong answer. */
+declare const kspComparisonMisleads: (a: SparinglySoluble, b: SparinglySoluble) => boolean;
+//#endregion
+export { PrecipitationCheck, PrecipitationVerdict, SOLUBILITY_PRODUCTS, SaltFormula, SparinglySoluble, ionicProduct, kspComparisonMisleads, kspFromSolubility, moreSoluble, saltByFormula, solubilityFromKsp, solubilityWithCommonIon, willPrecipitate };