@classytic/stage 0.2.0 → 0.4.0

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

package/dist/chem/stereo.d.mts

@@ -0,0 +1,108 @@
+import { Structure } from "./molecule.mjs";
+
+//#region src/chem/stereo.d.ts
+/**
+ * Compare two branches by CIP priority.
+ *
+ * Returns a negative number when the first outranks the second, positive when the second does, and
+ * `undefined` when they cannot be separated within the spheres explored, which for a real molecule
+ * means they are the same branch.
+ *
+ * The comparison walks outward one sphere at a time. At each sphere both branches offer a list of
+ * atoms sorted heaviest first; the lists are compared position by position, and the first
+ * difference decides it. Only if they are identical does the walk go further out.
+ */
+declare function comparePriority(structure: Structure, centre: number, firstAtom: number, secondAtom: number, maxSpheres?: number): number | undefined;
+/**
+ * The same comparison, for two branches hanging off DIFFERENT atoms.
+ *
+ * Needed by the meso check, where the two branches being weighed against each other belong to the
+ * two ends of the molecule rather than to one centre. Passing both to {@link comparePriority} with
+ * a single centre let each walk escape backwards through the other's parent, so two branches that
+ * are plainly the same came out different and no meso form was ever found.
+ */
+declare function compareBranches(structure: Structure, firstAtom: number, firstFrom: number, secondAtom: number, secondFrom: number, maxSpheres?: number): number | undefined;
+interface RankedSubstituent {
+  readonly atom: number;
+  readonly element: string;
+  /** 1 is highest priority. */
+  readonly rank: number;
+}
+/**
+ * The substituents of an atom in priority order, highest first.
+ *
+ * Returns undefined when two of them cannot be separated, which is the honest answer: a carbon with
+ * two identical groups on it has no handedness, and saying so is more useful than an arbitrary
+ * ordering that would then produce a confident R or S for a molecule that is neither.
+ */
+declare function rankSubstituents(structure: Structure, centre: number): RankedSubstituent[] | undefined;
+interface Stereocentre {
+  readonly atom: number;
+  readonly substituents: readonly RankedSubstituent[];
+}
+/**
+ * Every carbon with four different groups on it.
+ *
+ * The definition, applied rather than paraphrased. A carbon qualifies when the four things attached
+ * to it can all be told apart by the priority rules, which is a stronger statement than "four
+ * different atoms" and is why 3-methylhexane has a stereocentre and 3-methylpentane does not: in
+ * the second, two of the branches are both ethyl.
+ */
+declare function stereocentres(structure: Structure): Stereocentre[];
+/**
+ * How many stereoisomers a molecule has, from its stereocentre count.
+ *
+ * Two arrangements at each centre, independently, so 2^n. This is the upper bound: see
+ * {@link stereoisomerCount} for the number a molecule with an internal mirror plane actually has.
+ */
+declare const maximumStereoisomers: (centres: number) => number;
+interface StereoisomerCount {
+  readonly centres: number;
+  /** Two arrangements at each centre, independently. */
+  readonly maximum: number;
+  /** What the molecule actually has. */
+  readonly actual: number;
+  /** True when one arrangement is its own mirror image and so is not a separate substance. */
+  readonly hasMeso: boolean;
+  readonly because: string;
+}
+/**
+ * How many stereoisomers a molecule really has.
+ *
+ * The rule of 2^n over-counts whenever the molecule has an internal mirror plane. Tartaric acid has
+ * two stereocentres and three isomers, not four: the arrangement with one centre left-handed and
+ * the other right-handed is superimposable on its own reflection, so the two that 2^n counts
+ * separately are one substance, and that substance is not optically active at all.
+ *
+ * Detected by asking whether the centres are mirror images of one another, which is checkable with
+ * the machinery already here: the branches leading away from each centre have to be
+ * indistinguishable, and indistinguishable is exactly what {@link comparePriority} reports when it
+ * cannot separate two branches.
+ *
+ * Restricted to the two-centre case, which is the one syllabuses set. A molecule with more centres
+ * and partial symmetry needs a full search over configurations, and this reports the maximum for
+ * those rather than guessing.
+ */
+declare function stereoisomerCount(structure: Structure): StereoisomerCount;
+type DoubleBondShape = 'E' | 'Z';
+interface DoubleBondStereo {
+  readonly a: number;
+  readonly b: number;
+  /** The higher-priority substituent on each carbon. */
+  readonly higherOnA: number;
+  readonly higherOnB: number;
+}
+/**
+ * Double bonds that can show E/Z, with the higher-priority group on each end identified.
+ *
+ * A double bond has a shape worth naming only when BOTH its carbons carry two different groups. If
+ * either end has two of the same thing, swapping them changes nothing and there is only one
+ * compound, which is why 1,1-dichloroethene has no isomers and 1,2-dichloroethene has two.
+ *
+ * Which arrangement is E and which is Z cannot be read off the connection table: it depends on
+ * where the groups actually are in space, which a graph does not record. So this reports WHICH
+ * group wins on each end, and the geometry has to say the rest.
+ */
+declare function stereogenicDoubleBonds(structure: Structure): DoubleBondStereo[];
+//#endregion
+export { DoubleBondShape, DoubleBondStereo, RankedSubstituent, Stereocentre, StereoisomerCount, compareBranches, comparePriority, maximumStereoisomers, rankSubstituents, stereocentres, stereogenicDoubleBonds, stereoisomerCount };