@classytic/stage 0.3.0 → 0.4.0

package/dist/chem/lewis.mjs

@@ -0,0 +1,163 @@
+import { periodOf, valenceElectronsOf } from "../atomic/periodic.mjs";
+import { elementBySymbol } from "../atomic/elements.mjs";
+import { electronegativity } from "../atomic/properties.mjs";
+
+//#region src/chem/lewis.ts
+/**
+* The electron budget of a species: how many bonding pairs and how many lone pairs.
+*
+* ## The counting, stated once
+*
+* Every shape question reduces to two numbers, and both come out of one budget:
+*
+*   1. total valence electrons = the valence electrons of every atom, plus one for each unit of
+*      negative charge and minus one for each unit of positive charge;
+*   2. one sigma bond to each ligand uses two of them;
+*   3. each non-hydrogen ligand then takes six more to complete its own octet (hydrogen takes none,
+*      because its bonding pair already fills its shell);
+*   4. whatever is left belongs to the central atom, as lone pairs.
+*
+* That is the whole method, and it gets SF4, XeF2, ClF3, NH4+ and SO4 right with no special cases.
+*
+* ## Multiple bonds, decided by formal charge
+*
+* Where the central atom ends up short of an octet, that gap is what multiple bonding closes. The
+* question is whether it actually does, and the answer is not in the electron count: carbon dioxide
+* closes its gap completely and boron trifluoride cannot close it at all.
+*
+* Formal charge settles it, with electronegativity as the guard. Every pi bond moves the central
+* atom one step toward zero and the donating outer atom one step away, so pi bonds are added while
+* that trade improves the structure and stopped when it does not:
+*
+*   carbon dioxide starts as C(+2) with two O(-1), and two pi bonds take all three to zero;
+*   boron trifluoride starts at B(0) with three F(0), so no pi bond improves anything, and one
+*   would push fluorine, the most electronegative element there is, to +1.
+*
+* That is the whole difference between them, and it needs no special case for either. A second-
+* period centre is additionally capped at an octet, which is why nitrate gets exactly one double
+* bond and leaves its nitrogen at +1 rather than reaching zero.
+*
+* None of it affects the shape. A double bond points the same way as the single bond underneath it
+* and is one region of electron density, which is why carbon dioxide is linear.
+*
+* ## Where the valence electron counts come from
+*
+* From the atomic engine, not from a table typed out here. An element's valence electron count is
+* already a consequence of its configuration, and duplicating it would let the two disagree. So
+* oxygen having six and xenon having eight is derived in one place and used here.
+*
+* ## On the octet rule and its exceptions
+*
+* The octet rule is a useful summary of the second period and is broken routinely below it. This
+* engine does not enforce it: it counts electrons and REPORTS whether the central atom ended up
+* with fewer than eight, exactly eight, or more. Boron trifluoride comes out with six and sulfur
+* hexafluoride with twelve, and both are correct, so a rule that forbade them would be a rule that
+* had to be switched off for the interesting cases.
+*
+* Expansion beyond eight needs d orbitals close enough in energy to be used, which is why it starts
+* in the third period. {@link LewisCount.canExpand} says whether the central atom is in a position
+* to do it, so a count that expands a second-period atom can be flagged as impossible rather than
+* reported as fact.
+*
+* Pure: no React, no pixels.
+*/
+/** Valence electrons of an element, from its configuration. */
+function valenceElectronsFor(symbol) {
+	const element = elementBySymbol(symbol);
+	if (!element) throw new Error(`no element with symbol "${symbol}"`);
+	return valenceElectronsOf(element.Z);
+}
+/** Electrons a ligand needs beyond its bonding pair to fill its own shell. */
+function ligandDemand(symbol) {
+	return symbol === "H" ? 0 : 6;
+}
+/**
+* Work out the electron budget of a species.
+*
+* Returns the count rather than a drawing: where the electrons GO on the page is a layout decision,
+* and how many there are is chemistry.
+*/
+function lewisCount(centre) {
+	const centralValence = valenceElectronsFor(centre.central);
+	const totalValenceElectrons = centralValence + centre.bonded.reduce((total, l) => total + valenceElectronsFor(l.element) * l.count, 0) - centre.charge;
+	const bondingPairs = centre.bondedCount;
+	const usedBySigma = 2 * bondingPairs;
+	const demandedByLigands = centre.bonded.reduce((total, l) => total + ligandDemand(l.element) * l.count, 0);
+	const leftForCentre = totalValenceElectrons - usedBySigma - demandedByLigands;
+	const lonePairs = Math.max(0, Math.floor(leftForCentre / 2));
+	const stericNumber = bondingPairs + lonePairs;
+	const singleBondElectrons = 2 * bondingPairs + 2 * lonePairs;
+	const period = periodOf(elementBySymbol(centre.central).Z);
+	const canExpand = period >= 3;
+	const bondOrders = shareOutPiBonds(centre, {
+		centralValence,
+		lonePairs,
+		bondingPairs,
+		singleBondElectrons,
+		canExpand
+	});
+	const piBonds = bondOrders.reduce((total, b) => total + b.order - 1, 0);
+	const centralElectrons = singleBondElectrons + 2 * piBonds;
+	const octetShortfall = Math.max(0, 8 - centralElectrons);
+	const formalCharge = centralValence - 2 * lonePairs - (bondingPairs + piBonds);
+	let impossible;
+	if (leftForCentre < 0) impossible = `${centre.formula} has ${totalValenceElectrons} valence electrons, which is ${-leftForCentre} short of what its ${bondingPairs} bonds and its outer atoms need: check the formula and the charge`;
+	else if (singleBondElectrons > 8 && !canExpand) impossible = `${centre.central} is in period ${period} and has no d subshell available, so it cannot hold the ${singleBondElectrons} electrons this arrangement needs`;
+	return {
+		totalValenceElectrons,
+		bondingPairs,
+		lonePairs,
+		stericNumber,
+		piBonds,
+		bondOrders,
+		centralElectrons,
+		octetShortfall,
+		formalCharge,
+		canExpand,
+		...impossible ? { impossible } : {}
+	};
+}
+/** Formal charge on an outer atom holding `pi` extra bonds beyond its single one. */
+const outerFormalCharge = (symbol, pi) => valenceElectronsFor(symbol) - 2 * (3 - pi) - (1 + pi);
+/**
+* Decide how many pi bonds form, and to which outer atoms.
+*
+* Greedy and one bond at a time, because that is what the reasoning actually is: would drawing one
+* more double bond here make the structure better? Better means the central atom's formal charge
+* moves toward zero without pushing a more electronegative neighbour above it.
+*
+* Spread across the outer atoms rather than piled onto one, so carbon dioxide comes out as two
+* double bonds and not as a triple and a single. Both satisfy the counting; only one of them is the
+* molecule.
+*/
+function shareOutPiBonds(centre, state) {
+	const orders = centre.bonded.flatMap((b) => Array.from({ length: b.count }, () => ({
+		element: b.element,
+		order: 1
+	})));
+	const centralPull = electronegativity(elementBySymbol(centre.central).Z);
+	for (;;) {
+		const piSoFar = orders.reduce((total, b) => total + b.order - 1, 0);
+		if (state.centralValence - 2 * state.lonePairs - (state.bondingPairs + piSoFar) <= 0) break;
+		if (!state.canExpand && state.singleBondElectrons + 2 * (piSoFar + 1) > 8) break;
+		const donor = orders.filter((bond) => {
+			if (bond.element === "H" || bond.order >= 4) return false;
+			if (outerFormalCharge(bond.element, bond.order) <= 0) return true;
+			const donorPull = electronegativity(elementBySymbol(bond.element).Z);
+			if (donorPull === void 0 || centralPull === void 0) return false;
+			return donorPull <= centralPull;
+		}).sort((a, b) => a.order - b.order)[0];
+		if (!donor) break;
+		donor.order += 1;
+	}
+	return orders;
+}
+/** Whether the central atom has fewer than eight electrons, eight, or more. */
+function octetStatus(count) {
+	if (count.centralElectrons < 8) return "short of an octet";
+	if (count.centralElectrons === 8) return "an octet";
+	return "an expanded octet";
+}
+
+//#endregion
+export { lewisCount, octetStatus, valenceElectronsFor };

package/dist/chem/molecular-orbital.d.mts

@@ -0,0 +1,114 @@
+//#region src/chem/molecular-orbital.d.ts
+/**
+ * Molecular orbitals for a diatomic: bond order, and whether the molecule is magnetic.
+ *
+ * ## What this explains that dot-and-cross cannot
+ *
+ * Oxygen is paramagnetic. Liquid oxygen sticks to a magnet, which is a thing anyone can watch, and
+ * the Lewis structure O=O has every electron neatly paired and predicts the opposite. That failure
+ * is the reason molecular orbital theory is taught at all: put the electrons into orbitals that
+ * belong to the whole molecule rather than to one atom or one bond, and two of them end up alone in
+ * a pair of degenerate antibonding orbitals.
+ *
+ * So this engine answers two questions a Lewis structure cannot: how strongly the atoms are held
+ * together when the answer is not a whole number, and whether the molecule has unpaired electrons.
+ *
+ *     bond order = (bonding electrons - antibonding electrons) / 2
+ *
+ * A bond order of zero means the molecule does not exist, which is why there is no He2 and no Ne2.
+ *
+ * ## The crossover, which is the part usually left out
+ *
+ * The order of the 2p-derived orbitals is not fixed. For the earlier second-period elements the two
+ * pi orbitals lie BELOW the sigma; from oxygen onward the sigma drops below the pi. The cause is
+ * mixing between the 2s and 2p sigma orbitals, which pushes the sigma up, and it matters most where
+ * the 2s and 2p levels are closest together, which is at the left of the period.
+ *
+ * This is not a detail. Boron's B2 has exactly two electrons to place in that region: with pi
+ * lowest they go one into each pi orbital and B2 is paramagnetic, which it is; with sigma lowest
+ * they pair up in it and B2 would be diamagnetic, which it is not. So an engine that ignored the
+ * crossover would get the right bond order and the wrong magnetism, and the magnetism is the
+ * evidence.
+ *
+ * ## What is covered
+ *
+ * Diatomics of the first two periods, neutral or charged: H2, He2, Li2 through Ne2, and the
+ * heteronuclear and ionic ones built from the same orbitals, so NO, CO, CN- and the oxygen family
+ * O2+, O2-, O2 2-. Core electrons are left out: they sit in bonding and antibonding pairs that
+ * cancel exactly, so they change no answer and only lengthen the diagram.
+ *
+ * Pure: no React, no pixels.
+ */
+interface MolecularOrbital {
+  readonly label: string;
+  readonly bonding: boolean;
+  /** How many orbitals are at this energy: two for a pi level, one for a sigma. */
+  readonly orbitals: number;
+}
+/**
+ * Where the sigma made from 2p sits relative to the pair of pi orbitals.
+ *
+ * Mixing with the 2s sigma pushes the 2p sigma up, and the effect is strongest where 2s and 2p are
+ * closest in energy, which is toward the left of the period. So the pi orbitals are lower for the
+ * earlier elements and the sigma is lower from oxygen onward.
+ */
+declare const S_P_MIXING_NOTE = "The sigma orbital built from 2p is pushed up by mixing with the sigma built from 2s, and that mixing is strongest where the 2s and 2p levels lie closest together, toward the left of the period. So for boron, carbon and nitrogen the two pi orbitals lie below the sigma, and from oxygen onward the sigma drops below them.";
+/** The orbitals in energy order, for a diatomic with this many valence electrons. */
+declare function orbitalSequence(valenceElectrons: number, firstPeriod: boolean): readonly MolecularOrbital[];
+interface Level {
+  readonly orbital: MolecularOrbital;
+  readonly electrons: number;
+  /** Electrons in this level with no partner, by Hund's rule. */
+  readonly unpaired: number;
+}
+/**
+ * Fill the orbitals from the bottom, singly across a degenerate level before pairing.
+ *
+ * Hund's rule again, and for the same reason it applies inside an atom: two electrons in one
+ * orbital repel, so they spread out while there is anywhere to spread to. It is what leaves oxygen
+ * with two unpaired electrons instead of one filled antibonding orbital.
+ */
+declare function fillOrbitals(sequence: readonly MolecularOrbital[], electrons: number): {
+  levels: Level[];
+  unpaired: number;
+  unplaced: number;
+};
+type Magnetism = 'paramagnetic' | 'diamagnetic';
+interface DiatomicResult {
+  readonly formula: string;
+  readonly atoms: readonly string[];
+  readonly charge: number;
+  /** Valence electrons only: core pairs cancel and change no answer. */
+  readonly valenceElectrons: number;
+  readonly levels: readonly Level[];
+  readonly bondingElectrons: number;
+  readonly antibondingElectrons: number;
+  /**
+   * (bonding - antibonding) / 2, so it can be a half.
+   *
+   * A half-integer bond order is not a rounding error: it is what an odd number of electrons gives,
+   * and it is why nitrogen monoxide exists as a stable radical with a bond between a double and a
+   * triple.
+   */
+  readonly bondOrder: number;
+  readonly unpairedElectrons: number;
+  readonly magnetism: Magnetism;
+  /** A bond order of zero means there is nothing holding the atoms together. */
+  readonly exists: boolean;
+  /** True when the pi orbitals lie below the sigma, which is the crossover. */
+  readonly piBelowSigma: boolean;
+}
+/**
+ * Work out the molecular orbitals of a diatomic written as a formula.
+ *
+ * `diatomic('O2')`, `diatomic('N2')`, `diatomic('NO')`, `diatomic('CN-')`, `diatomic('O2+')`.
+ */
+declare function diatomic(formula: string): DiatomicResult;
+/**
+ * The configuration written out, for a diagram caption.
+ *
+ * Empty levels are dropped, since writing them adds nothing a reader needs.
+ */
+declare const formatOccupancy: (result: DiatomicResult) => string;
+//#endregion
+export { DiatomicResult, Level, Magnetism, MolecularOrbital, S_P_MIXING_NOTE, diatomic, fillOrbitals, formatOccupancy, orbitalSequence };

package/dist/chem/molecular-orbital.mjs

@@ -0,0 +1,201 @@
+import { readFormula } from "./species.mjs";
+import { valenceElectronsFor } from "./lewis.mjs";
+
+//#region src/chem/molecular-orbital.ts
+/**
+* Molecular orbitals for a diatomic: bond order, and whether the molecule is magnetic.
+*
+* ## What this explains that dot-and-cross cannot
+*
+* Oxygen is paramagnetic. Liquid oxygen sticks to a magnet, which is a thing anyone can watch, and
+* the Lewis structure O=O has every electron neatly paired and predicts the opposite. That failure
+* is the reason molecular orbital theory is taught at all: put the electrons into orbitals that
+* belong to the whole molecule rather than to one atom or one bond, and two of them end up alone in
+* a pair of degenerate antibonding orbitals.
+*
+* So this engine answers two questions a Lewis structure cannot: how strongly the atoms are held
+* together when the answer is not a whole number, and whether the molecule has unpaired electrons.
+*
+*     bond order = (bonding electrons - antibonding electrons) / 2
+*
+* A bond order of zero means the molecule does not exist, which is why there is no He2 and no Ne2.
+*
+* ## The crossover, which is the part usually left out
+*
+* The order of the 2p-derived orbitals is not fixed. For the earlier second-period elements the two
+* pi orbitals lie BELOW the sigma; from oxygen onward the sigma drops below the pi. The cause is
+* mixing between the 2s and 2p sigma orbitals, which pushes the sigma up, and it matters most where
+* the 2s and 2p levels are closest together, which is at the left of the period.
+*
+* This is not a detail. Boron's B2 has exactly two electrons to place in that region: with pi
+* lowest they go one into each pi orbital and B2 is paramagnetic, which it is; with sigma lowest
+* they pair up in it and B2 would be diamagnetic, which it is not. So an engine that ignored the
+* crossover would get the right bond order and the wrong magnetism, and the magnetism is the
+* evidence.
+*
+* ## What is covered
+*
+* Diatomics of the first two periods, neutral or charged: H2, He2, Li2 through Ne2, and the
+* heteronuclear and ionic ones built from the same orbitals, so NO, CO, CN- and the oxygen family
+* O2+, O2-, O2 2-. Core electrons are left out: they sit in bonding and antibonding pairs that
+* cancel exactly, so they change no answer and only lengthen the diagram.
+*
+* Pure: no React, no pixels.
+*/
+/**
+* Where the sigma made from 2p sits relative to the pair of pi orbitals.
+*
+* Mixing with the 2s sigma pushes the 2p sigma up, and the effect is strongest where 2s and 2p are
+* closest in energy, which is toward the left of the period. So the pi orbitals are lower for the
+* earlier elements and the sigma is lower from oxygen onward.
+*/
+const S_P_MIXING_NOTE = "The sigma orbital built from 2p is pushed up by mixing with the sigma built from 2s, and that mixing is strongest where the 2s and 2p levels lie closest together, toward the left of the period. So for boron, carbon and nitrogen the two pi orbitals lie below the sigma, and from oxygen onward the sigma drops below them.";
+/** Valence electron count at or below which the pi orbitals lie below the sigma. */
+const MIXING_LIMIT = 10;
+const PERIOD_1 = [{
+	label: "σ1s",
+	bonding: true,
+	orbitals: 1
+}, {
+	label: "σ*1s",
+	bonding: false,
+	orbitals: 1
+}];
+const PI_BELOW_SIGMA = [
+	{
+		label: "σ2s",
+		bonding: true,
+		orbitals: 1
+	},
+	{
+		label: "σ*2s",
+		bonding: false,
+		orbitals: 1
+	},
+	{
+		label: "π2p",
+		bonding: true,
+		orbitals: 2
+	},
+	{
+		label: "σ2p",
+		bonding: true,
+		orbitals: 1
+	},
+	{
+		label: "π*2p",
+		bonding: false,
+		orbitals: 2
+	},
+	{
+		label: "σ*2p",
+		bonding: false,
+		orbitals: 1
+	}
+];
+const SIGMA_BELOW_PI = [
+	{
+		label: "σ2s",
+		bonding: true,
+		orbitals: 1
+	},
+	{
+		label: "σ*2s",
+		bonding: false,
+		orbitals: 1
+	},
+	{
+		label: "σ2p",
+		bonding: true,
+		orbitals: 1
+	},
+	{
+		label: "π2p",
+		bonding: true,
+		orbitals: 2
+	},
+	{
+		label: "π*2p",
+		bonding: false,
+		orbitals: 2
+	},
+	{
+		label: "σ*2p",
+		bonding: false,
+		orbitals: 1
+	}
+];
+/** The orbitals in energy order, for a diatomic with this many valence electrons. */
+function orbitalSequence(valenceElectrons, firstPeriod) {
+	if (firstPeriod) return PERIOD_1;
+	return valenceElectrons <= MIXING_LIMIT ? PI_BELOW_SIGMA : SIGMA_BELOW_PI;
+}
+/**
+* Fill the orbitals from the bottom, singly across a degenerate level before pairing.
+*
+* Hund's rule again, and for the same reason it applies inside an atom: two electrons in one
+* orbital repel, so they spread out while there is anywhere to spread to. It is what leaves oxygen
+* with two unpaired electrons instead of one filled antibonding orbital.
+*/
+function fillOrbitals(sequence, electrons) {
+	let left = electrons;
+	const levels = sequence.map((orbital) => {
+		const capacity = 2 * orbital.orbitals;
+		const placed = Math.min(left, capacity);
+		left -= placed;
+		return {
+			orbital,
+			electrons: placed,
+			unpaired: placed <= orbital.orbitals ? placed : 2 * orbital.orbitals - placed
+		};
+	});
+	return {
+		levels,
+		unpaired: levels.reduce((total, l) => total + l.unpaired, 0),
+		unplaced: left
+	};
+}
+/**
+* Work out the molecular orbitals of a diatomic written as a formula.
+*
+* `diatomic('O2')`, `diatomic('N2')`, `diatomic('NO')`, `diatomic('CN-')`, `diatomic('O2+')`.
+*/
+function diatomic(formula) {
+	const { counts, charge } = readFormula(formula);
+	const atoms = counts.flatMap((c) => Array(c.count).fill(c.element));
+	if (atoms.length !== 2) throw new Error(`${formula} has ${atoms.length} atoms: this engine describes diatomic molecules, which have two`);
+	const firstPeriod = atoms.every((a) => a === "H" || a === "He");
+	const valenceElectrons = atoms.reduce((total, a) => total + valenceElectronsFor(a), 0) - charge;
+	if (valenceElectrons < 0) throw new Error(`${formula} works out to a negative electron count`);
+	const piBelowSigma = !firstPeriod && valenceElectrons <= MIXING_LIMIT;
+	const { levels, unpaired, unplaced } = fillOrbitals(orbitalSequence(valenceElectrons, firstPeriod), valenceElectrons);
+	if (unplaced > 0) throw new Error(`${formula} has ${valenceElectrons} valence electrons, more than the orbitals of the first two periods can hold`);
+	const bondingElectrons = levels.filter((l) => l.orbital.bonding).reduce((total, l) => total + l.electrons, 0);
+	const antibondingElectrons = levels.filter((l) => !l.orbital.bonding).reduce((total, l) => total + l.electrons, 0);
+	const bondOrder = (bondingElectrons - antibondingElectrons) / 2;
+	return {
+		formula,
+		atoms,
+		charge,
+		valenceElectrons,
+		levels,
+		bondingElectrons,
+		antibondingElectrons,
+		bondOrder,
+		unpairedElectrons: unpaired,
+		magnetism: unpaired > 0 ? "paramagnetic" : "diamagnetic",
+		exists: bondOrder > 0,
+		piBelowSigma
+	};
+}
+/**
+* The configuration written out, for a diagram caption.
+*
+* Empty levels are dropped, since writing them adds nothing a reader needs.
+*/
+const formatOccupancy = (result) => result.levels.filter((l) => l.electrons > 0).map((l) => `${l.orbital.label}${l.electrons === 1 ? "" : superscript(l.electrons)}`).join(" ");
+const SUPERSCRIPT = "⁰¹²³⁴⁵⁶⁷⁸⁹";
+const superscript = (value) => String(value).split("").map((d) => SUPERSCRIPT[Number(d)] ?? d).join("");
+
+//#endregion
+export { S_P_MIXING_NOTE, diatomic, fillOrbitals, formatOccupancy, orbitalSequence };

package/dist/chem/molecule.d.mts

@@ -0,0 +1,154 @@
+//#region src/chem/molecule.d.ts
+/**
+ * molecule, a structure as a graph, so the rest can be worked out rather than declared.
+ *
+ * WHAT THIS IS FOR. Every chemistry lab and lesson we have declares its molecules as DRAWINGS: a
+ * chain of vertices with positions, a formula typed in as a string, a functional group named as a
+ * list of vertex indices. Nothing about that can be checked. A formula string can disagree with the
+ * structure beside it, a group can be named that the structure does not contain, and an isomer list
+ * is only as complete as whoever typed it.
+ *
+ * A graph fixes all of it at once. Declare the heavy atoms and the bonds, and the molecular formula,
+ * the relative molecular mass, the degrees of unsaturation, the functional groups and the polymer
+ * repeat unit all follow by computation.
+ *
+ * ## Hydrogens are implicit, and that is the point
+ *
+ * An author declares carbon, oxygen and nitrogen and never hydrogen, exactly as a skeletal formula
+ * is drawn. The hydrogen count comes from valence: four bonds to a carbon, three to a nitrogen, two
+ * to an oxygen, one to a halogen. So a structure cannot be declared with a hydrogen count that
+ * contradicts its own bonds, because the count is not declared at all.
+ *
+ * ## Why SMILES
+ *
+ * Because it is the notation the whole of chemistry already uses, so `CCO` is ethanol here and in
+ * every database a learner will ever meet, and because a molecule written as one short string is a
+ * molecule an author will actually declare correctly. The subset parsed here is the one A level
+ * needs: the organic elements, single, double, triple and aromatic bonds, branches, and ring
+ * closures.
+ *
+ * What is deliberately NOT here: stereochemistry, charges, isotopes and explicit bracket atoms.
+ * Those belong in the topics that use them, and a parser that accepted them without the rest of the
+ * kernel understanding them would be a promise it could not keep.
+ *
+ * Pure: no React, no pixels.
+ */
+/** The elements A level organic chemistry uses. */
+type Element = 'C' | 'N' | 'O' | 'S' | 'P' | 'F' | 'Cl' | 'Br' | 'I' | 'H';
+/** Relative atomic masses, to the precision a data booklet prints. */
+declare const ATOMIC_MASS: Readonly<Record<Element, number>>;
+interface Atom {
+  readonly id: number;
+  readonly element: Element;
+  /** Part of an aromatic ring, written lowercase in SMILES. */
+  readonly aromatic: boolean;
+  /**
+   * Bonds this atom makes to something OUTSIDE the structure, so they take no hydrogen.
+   *
+   * An attachment point. A polymer repeat unit has two, one to the unit on each side, and without
+   * them the repeat unit of poly(ethene) comes out as C2H6: opening the double bond frees a bond on
+   * each carbon, and if nothing claims it a hydrogen does. The unit is CH2-CH2, not ethane.
+   */
+  readonly openValence?: number;
+  /**
+   * Formal charge on this atom: +1 on the nitrogen of an ammonium ion, -1 on a carboxylate oxygen.
+   *
+   * It changes how many bonds the atom makes, which is the reason it has to live on the graph
+   * rather than being noted alongside it. A nitrogen makes three bonds and an ammonium nitrogen
+   * makes four, and a kernel that did not know the charge would report ammonium as NH3 with a
+   * spare bond it could not explain.
+   */
+  readonly charge?: number;
+  /**
+   * Hydrogens stated outright rather than worked out from the valence.
+   *
+   * Set only by a bracket atom, where SMILES requires the count to be written. Everywhere else the
+   * count is computed, which is what stops a structure disagreeing with its own bonds.
+   */
+  readonly explicitHydrogens?: number;
+}
+interface Bond {
+  readonly a: number;
+  readonly b: number;
+  readonly order: 1 | 2 | 3;
+  /** An aromatic bond counts as one and a half when valence is totted up. */
+  readonly aromatic: boolean;
+}
+interface Structure {
+  readonly atoms: readonly Atom[];
+  readonly bonds: readonly Bond[];
+}
+/**
+ * Parse the SMILES subset A level needs.
+ *
+ * `CCO` ethanol, `CC(=O)C` propanone, `c1ccccc1` benzene, `CC(=O)OCC` ethyl ethanoate.
+ *
+ * Refuses anything it does not fully understand rather than guessing, because a parser that
+ * silently drops a feature produces a molecule that is not the one the author wrote, and every
+ * number computed from it afterwards is then confidently wrong.
+ */
+declare function parseSmiles(smiles: string): Structure;
+/** Bonds touching an atom. */
+declare const bondsAt: (structure: Structure, id: number) => Bond[];
+/** The atom on the other end of a bond. */
+declare const otherEnd: (bond: Bond, id: number) => number;
+/** Atoms directly bonded to this one, excluding any explicit hydrogens. */
+declare const neighbours: (structure: Structure, id: number) => Atom[];
+/** How many bonds an atom has used, counting an aromatic bond as one and a half. */
+declare const bondOrderSum: (structure: Structure, id: number) => number;
+/**
+ * Hydrogens on an atom, from what its valence has left over.
+ *
+ * Never declared, which is what stops a structure disagreeing with its own formula. An aromatic
+ * carbon in benzene has two aromatic bonds worth 1.5 each, leaving one hydrogen, which is right.
+ */
+/**
+ * Bonds an atom can make, once its charge is taken into account.
+ *
+ * The two directions are not symmetrical, and the reason is what the charge did to the electrons.
+ *
+ * An atom with a lone pair to spare, nitrogen or oxygen or sulfur, makes an EXTRA bond when it
+ * loses an electron, because the lone pair becomes a bonding pair: ammonium's nitrogen makes four
+ * bonds, not three. Gaining one costs it a bond instead, which is why a carboxylate oxygen makes
+ * only one.
+ *
+ * Carbon has no lone pair to donate, so it loses a bond whichever way it is charged. A carbocation
+ * and a carbanion both make three.
+ */
+declare function chargedValence(element: Element, charge?: number): number;
+declare function implicitHydrogens(structure: Structure, id: number): number;
+/** Total formal charge on a structure: the charge of the ion it represents. */
+declare const totalCharge: (structure: Structure) => number;
+/** Every element in the structure, counted, hydrogens included. */
+declare function atomCounts(structure: Structure): Record<string, number>;
+/**
+ * The molecular formula, in Hill order: carbon, then hydrogen, then everything else alphabetically.
+ *
+ * Hill order is what a database and a mark scheme both use, so C2H6O and never H6C2O or OC2H6.
+ */
+declare function formatCounts(counts: Readonly<Record<string, number>>): string;
+declare function molecularFormula(structure: Structure): string;
+/** Relative molecular mass, from the same counts. */
+declare const relativeMass: (structure: Structure) => number;
+/**
+ * Degrees of unsaturation: how many rings plus double-bond equivalents the formula demands.
+ *
+ * Worth computing because it is the first thing to do with a molecular formula in a structure
+ * determination, and because it is the check that catches a proposed structure that cannot exist:
+ * a formula with zero degrees cannot contain a C=O however well the rest of the evidence fits.
+ *
+ * Oxygen does not enter the count, which surprises people every time, and the reason is that adding
+ * an oxygen into a chain uses two bonds and supplies two.
+ */
+declare function degreesOfUnsaturation(structure: Structure): number;
+/** Atoms in the structure that are carbon. */
+declare const carbonCount: (structure: Structure) => number;
+/**
+ * Rings, by the cycle rank of the graph: bonds minus atoms plus connected pieces.
+ *
+ * Counts independent rings rather than every closed loop, which is the number a chemist means by
+ * "how many rings", and naphthalene comes out as two rather than three.
+ */
+declare function ringCount(structure: Structure): number;
+//#endregion
+export { ATOMIC_MASS, Atom, Bond, Element, Structure, atomCounts, bondOrderSum, bondsAt, carbonCount, chargedValence, degreesOfUnsaturation, formatCounts, implicitHydrogens, molecularFormula, neighbours, otherEnd, parseSmiles, relativeMass, ringCount, totalCharge };