@classytic/stage 0.3.0 → 0.4.0

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 };

package/dist/chem/solution.mjs

@@ -0,0 +1,186 @@
+//#region src/chem/solution.ts
+/**
+* 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.
+*/
+const SOLUBILITY_PRODUCTS = [
+	{
+		formula: "AgCl",
+		cations: 1,
+		anions: 1,
+		ksp: 18e-11
+	},
+	{
+		formula: "AgBr",
+		cations: 1,
+		anions: 1,
+		ksp: 54e-14
+	},
+	{
+		formula: "AgI",
+		cations: 1,
+		anions: 1,
+		ksp: 85e-18
+	},
+	{
+		formula: "BaSO4",
+		cations: 1,
+		anions: 1,
+		ksp: 11e-11
+	},
+	{
+		formula: "CaSO4",
+		cations: 1,
+		anions: 1,
+		ksp: 49e-6
+	},
+	{
+		formula: "CaCO3",
+		cations: 1,
+		anions: 1,
+		ksp: 3.3e-9
+	},
+	{
+		formula: "PbSO4",
+		cations: 1,
+		anions: 1,
+		ksp: 25e-9
+	},
+	{
+		formula: "Ag2CrO4",
+		cations: 2,
+		anions: 1,
+		ksp: 11e-13
+	},
+	{
+		formula: "PbCl2",
+		cations: 1,
+		anions: 2,
+		ksp: 17e-6
+	},
+	{
+		formula: "PbI2",
+		cations: 1,
+		anions: 2,
+		ksp: 9.8e-9
+	},
+	{
+		formula: "Mg(OH)2",
+		cations: 1,
+		anions: 2,
+		ksp: 56e-13
+	},
+	{
+		formula: "Ca(OH)2",
+		cations: 1,
+		anions: 2,
+		ksp: 55e-7
+	},
+	{
+		formula: "Fe(OH)3",
+		cations: 1,
+		anions: 3,
+		ksp: 26e-40
+	}
+];
+const saltByFormula = (formula) => SOLUBILITY_PRODUCTS.find((s) => s.formula === formula);
+/**
+* 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).
+*/
+function kspFromSolubility(salt, solubility) {
+	if (solubility < 0) throw new Error("a solubility cannot be negative");
+	const { cations: p, anions: q } = salt;
+	return (p * solubility) ** p * (q * solubility) ** q;
+}
+/**
+* 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))
+*/
+function solubilityFromKsp(salt) {
+	const { cations: p, anions: q, ksp } = salt;
+	return (ksp / (p ** p * q ** q)) ** (1 / (p + q));
+}
+/**
+* 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.
+*/
+function ionicProduct(salt, cation, anion) {
+	if (cation < 0 || anion < 0) throw new Error("a concentration cannot be negative");
+	return cation ** salt.cations * anion ** salt.anions;
+}
+/**
+* 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.
+*/
+function willPrecipitate(salt, cation, anion) {
+	const product = ionicProduct(salt, cation, anion);
+	const ratio = product / salt.ksp;
+	const verdict = ratio > 1.0001 ? "precipitate" : ratio < .9999 ? "stays dissolved" : "saturated";
+	const because = verdict === "precipitate" ? `the ions present give an ionic product of ${product.toExponential(2)}, above the ${salt.ksp.toExponential(2)} the solution can hold, so solid ${salt.formula} appears until the product falls back to it` : verdict === "stays dissolved" ? `the ions present give an ionic product of ${product.toExponential(2)}, below the ${salt.ksp.toExponential(2)} the solution can hold, so nothing comes out however insoluble ${salt.formula} is said to be` : `the ionic product has reached ${salt.ksp.toExponential(2)} exactly, so the solution is saturated and on the point of depositing solid`;
+	return {
+		ionicProduct: product,
+		ksp: salt.ksp,
+		verdict,
+		because
+	};
+}
+/**
+* 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.
+*/
+function solubilityWithCommonIon(salt, existing, ion = "anion") {
+	if (existing < 0) throw new Error("an existing concentration cannot be negative");
+	if (existing === 0) return solubilityFromKsp(salt);
+	const { cations: p, anions: q, ksp } = salt;
+	const productAt = (s) => {
+		const cation = p * s + (ion === "cation" ? existing : 0);
+		const anion = q * s + (ion === "anion" ? existing : 0);
+		return cation ** p * anion ** q;
+	};
+	let low = 0;
+	let high = solubilityFromKsp(salt);
+	for (let i = 0; i < 200; i += 1) {
+		const mid = (low + high) / 2;
+		if (productAt(mid) > ksp) high = mid;
+		else low = mid;
+	}
+	return (low + high) / 2;
+}
+/**
+* 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.
+*/
+function moreSoluble(a, b) {
+	return solubilityFromKsp(a) >= solubilityFromKsp(b) ? a : b;
+}
+/** Whether comparing two salts by Ksp alone would give the wrong answer. */
+const kspComparisonMisleads = (a, b) => a.cations + a.anions !== b.cations + b.anions && a.ksp < b.ksp !== solubilityFromKsp(a) < solubilityFromKsp(b);
+
+//#endregion
+export { SOLUBILITY_PRODUCTS, ionicProduct, kspComparisonMisleads, kspFromSolubility, moreSoluble, saltByFormula, solubilityFromKsp, solubilityWithCommonIon, willPrecipitate };

package/dist/chem/species.d.mts

@@ -0,0 +1,47 @@
+import { parseFormula } from "./formula.mjs";
+
+//#region src/chem/species.d.ts
+interface Bonded {
+  readonly element: string;
+  readonly count: number;
+}
+/** A central atom and everything bonded to it: the unit a shape question is asked about. */
+interface Centre {
+  /** As written, without the charge. */
+  readonly formula: string;
+  readonly central: string;
+  readonly bonded: readonly Bonded[];
+  /** Overall charge: +1 for an ammonium ion, -2 for a sulfate ion. */
+  readonly charge: number;
+  /** Total number of atoms bonded to the central atom. */
+  readonly bondedCount: number;
+}
+/**
+ * A formula split into its atom counts and its charge.
+ *
+ * The step before deciding anything about structure, shared by the shape engine, which wants a
+ * central atom, and the molecular orbital engine, which wants two atoms and no centre at all.
+ */
+declare const readFormula: (input: string) => {
+  counts: {
+    element: string;
+    count: number;
+  }[];
+  charge: number;
+};
+interface CentreOptions {
+  /** Name the central atom instead of letting it be inferred. */
+  readonly central?: string;
+  /** Overall charge, if it is not written into the formula. */
+  readonly charge?: number;
+}
+/**
+ * Read a formula into a central atom and its ligands.
+ *
+ * Accepts the charge written in ("NH4+", "SO4^2-", "SO4 2-") or passed separately.
+ */
+declare function parseCentre(input: string, options?: CentreOptions): Centre;
+/** The species written out again, charge included: useful for a label. */
+declare function formatCentre(centre: Centre): string;
+//#endregion
+export { Bonded, Centre, CentreOptions, formatCentre, parseCentre, readFormula };

package/dist/chem/species.mjs

@@ -0,0 +1,128 @@
+import { parseFormula } from "./formula.mjs";
+
+//#region src/chem/species.ts
+/**
+* A species written as a formula, parsed into a central atom and what surrounds it.
+*
+* ## Why a formula and not a graph
+*
+* The molecule engine takes SMILES and builds a graph, which is right for organic chemistry where
+* the skeleton is the question. Shape questions are not like that. They are asked about a single
+* central atom with things around it, written as a formula: what shape is XeF4, what is the bond
+* angle in NH3, why is SF4 not tetrahedral. Making an author write a graph for those would be
+* ceremony, and the formula already contains everything the answer needs.
+*
+* So this parses the formula directly, and the two front ends stay separate rather than one being
+* forced through the other.
+*
+* ## Choosing the central atom
+*
+* The rule used here is the one that works in practice: the central atom is the non-hydrogen element
+* that appears fewest times, and where two tie, the one written first. That picks O out of H2O, S
+* out of SO4, Xe out of XeF4 and Cl out of ClF3. A caller who disagrees can name the central atom
+* instead of having it inferred.
+*
+* ## What this refuses, and why refusing is the right answer
+*
+* Hydrogen alongside other ligands. In H2SO4 the hydrogens are bonded to oxygens, not to the
+* sulfur, so treating them as ligands on the central atom would produce a confident answer to a
+* question nobody asked. The formula alone cannot say where a hydrogen sits, so the parse stops and
+* says so rather than guessing. H2O, NH3 and NH4+ are unaffected: there, hydrogen is the only
+* ligand and there is nowhere else for it to be.
+*
+* Pure: no React, no pixels.
+*/
+/**
+* An element bonded to the centre, and how many of it there are.
+*
+* Deliberately not called a ligand: `Ligand` in this kernel already means a named donor in a
+* coordination complex, which carries a charge and a denticity and an IUPAC prefix. This is a
+* plainer thing, one element bonded to a central atom, and giving the two the same name would
+* suggest they were interchangeable.
+*/
+/** An explicit charge: separated from the formula by a caret or a space, so its digits are its own. */
+const EXPLICIT_CHARGE = /(?:\^|\s+)(\d*)\s*([+-])\s*$/;
+/** A bare sign at the end, which is a charge of one. */
+const BARE_CHARGE = /([+-])\s*$/;
+/**
+* Split a trailing charge off a formula.
+*
+* A number before the sign is ambiguous and cannot be resolved by reading alone: the 4 in NH4+ is a
+* subscript on the hydrogen and the 3 in Fe3+ is the charge, and nothing in the text distinguishes
+* them. Guessing produced an ammonium ion with a charge of four.
+*
+* So the contract is explicit rather than clever. A bare sign means one: "NH4+" is the ammonium ion.
+* Any other size is written with a caret or a space: "SO4^2-" or "SO4 2-". A charge can also be
+* passed separately, which is the unambiguous form for anything generated rather than typed.
+*/
+function splitCharge(input) {
+	const text = input.trim();
+	const explicit = EXPLICIT_CHARGE.exec(text);
+	if (explicit) {
+		const size = explicit[1] ? Number(explicit[1]) : 1;
+		return {
+			body: text.slice(0, explicit.index).trim(),
+			charge: explicit[2] === "-" ? -size : size
+		};
+	}
+	const bare = BARE_CHARGE.exec(text);
+	if (bare) return {
+		body: text.slice(0, bare.index).trim(),
+		charge: bare[1] === "-" ? -1 : 1
+	};
+	return {
+		body: text.replace(/\s+/g, ""),
+		charge: 0
+	};
+}
+/**
+* A formula split into its atom counts and its charge.
+*
+* The step before deciding anything about structure, shared by the shape engine, which wants a
+* central atom, and the molecular orbital engine, which wants two atoms and no centre at all.
+*/
+const readFormula = (input) => {
+	const { body, charge } = splitCharge(input);
+	return {
+		counts: parseFormula(body),
+		charge
+	};
+};
+/**
+* Read a formula into a central atom and its ligands.
+*
+* Accepts the charge written in ("NH4+", "SO4^2-", "SO4 2-") or passed separately.
+*/
+function parseCentre(input, options = {}) {
+	const { body, charge: written } = splitCharge(input);
+	const charge = options.charge ?? written;
+	const counts = parseFormula(body);
+	const heavy = counts.filter((c) => c.element !== "H");
+	if (heavy.length === 0) throw new Error(`"${body}" is hydrogen only and has no central atom`);
+	const central = options.central ?? heavy.reduce((best, c) => c.count < best.count ? c : best, heavy[0]).element;
+	if (!counts.some((c) => c.element === central)) throw new Error(`"${central}" does not appear in ${body}`);
+	const centralCount = counts.find((c) => c.element === central).count;
+	if (centralCount !== 1) throw new Error(`${body} has ${centralCount} ${central} atoms, so it has no single central atom: this engine describes one centre at a time`);
+	const bonded = counts.filter((c) => c.element !== central).map((c) => ({
+		element: c.element,
+		count: c.count
+	}));
+	if (bonded.length === 0) throw new Error(`${body} is a single atom and has no shape`);
+	if (bonded.some((l) => l.element === "H") && bonded.length > 1) throw new Error(`${body} has hydrogen alongside other ligands, and a formula cannot say which atom the hydrogen is bonded to. In an oxoacid it is bonded to an oxygen, not to the central atom. Name the central atom and give the ligands directly if you mean something else.`);
+	return {
+		formula: body,
+		central,
+		bonded,
+		charge,
+		bondedCount: bonded.reduce((total, l) => total + l.count, 0)
+	};
+}
+/** The species written out again, charge included: useful for a label. */
+function formatCentre(centre) {
+	if (centre.charge === 0) return centre.formula;
+	const size = Math.abs(centre.charge) === 1 ? "" : String(Math.abs(centre.charge));
+	return `${centre.formula}${size}${centre.charge < 0 ? "-" : "+"}`;
+}
+
+//#endregion
+export { formatCentre, parseCentre, readFormula };