@classytic/stage 0.3.0 → 0.4.0

package/dist/chem/relations.d.mts

@@ -0,0 +1,183 @@
+import { Relation } from "../relation/index.mjs";
+
+//#region src/chem/relations.d.ts
+/** `n = m / M`, moles from a mass weighed out. */
+declare const molesFromMass: () => Relation;
+/** `n = c * V`, moles in a volume of solution. Give V in cm3 and the conversion looks after itself. */
+declare const molesFromSolution: () => Relation;
+/** `n = N / L`, moles from a number of particles. */
+declare const molesFromParticles: () => Relation;
+/**
+ * `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.
+ */
+declare const molesFromGasVolume: () => Relation;
+/** `P * V = n * R * T`, the ideal gas equation. Temperature in kelvin, as it must be. */
+declare const idealGas: () => Relation;
+/** `P1 * V1 / T1 = P2 * V2 / T2`, one gas under two sets of conditions. */
+declare const combinedGasLaw: () => Relation;
+/** `c = n / V`, concentration from moles and volume. */
+declare const concentration: () => Relation;
+/**
+ * `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.
+ */
+declare const dilution: () => Relation;
+/** `m_conc = c * V * M`, the mass to weigh out to make up a standard solution. */
+declare const massForSolution: () => Relation;
+/**
+ * `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.
+ */
+declare const molality: () => Relation;
+/** `rho = m / V`, density, which is what converts between a volume and a mass of solution. */
+declare const density: () => Relation;
+/**
+ * `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.
+ */
+declare const beerLambert: () => Relation;
+/**
+ * `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.
+ */
+declare const absorbanceFromIntensity: () => Relation;
+/** `q = m * c * dT`, the heat a measured temperature change accounts for. */
+declare const heatEnergy: () => Relation;
+/**
+ * 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.
+ */
+declare const CONSTANTS: {
+  /** Avogadro constant, per mole. */readonly avogadro: 6.02214076e+23; /** Molar gas constant, J per mole per kelvin. */
+  readonly gasConstant: number; /** Molar volume of an ideal gas at 273.15 K and 100 kPa, dm3 per mole. */
+  readonly molarVolumeStp: 22.7; /** Molar volume at 298 K and 100 kPa, dm3 per mole: the figure room-temperature questions use. */
+  readonly molarVolumeRoom: 24; /** Specific heat capacity of water, J per gram per kelvin. */
+  readonly waterHeatCapacity: 4.18;
+};
+/** Kelvin from degrees Celsius. One line, and the source of a great many wrong gas answers. */
+declare const kelvinFrom: (celsius: number) => number;
+/**
+ * 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.
+ */
+declare 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.
+   */
+  readonly dilution: {
+    readonly kind: "derived";
+    readonly 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.";
+    readonly invariant: "the number of moles of solute, which water does not create or destroy";
+    readonly arrivesAt: "c2";
+    readonly steps: readonly [{
+      readonly relation: () => Relation;
+      readonly solveFor: "n";
+      readonly using: {
+        readonly c: "c1";
+        readonly V: "V1";
+      };
+      readonly gives: "n";
+      readonly because: "first find how many moles the stock solution you measured out actually contains";
+    }, {
+      readonly relation: () => Relation;
+      readonly solveFor: "c";
+      readonly using: {
+        readonly n: "n";
+        readonly V: "V2";
+      };
+      readonly gives: "c2";
+      readonly 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.
+   */
+  readonly massForSolution: {
+    readonly kind: "derived";
+    readonly summary: "You cannot weigh out moles, so work out how many moles the solution needs and then what that many moles weigh.";
+    readonly invariant: "nothing is held fixed here: this is two definitions used one after the other";
+    readonly arrivesAt: "m";
+    readonly steps: readonly [{
+      readonly relation: () => Relation;
+      readonly solveFor: "n";
+      readonly using: {
+        readonly c: "c";
+        readonly V: "V";
+      };
+      readonly gives: "n";
+      readonly because: "the volume you are making up, at the concentration you want, needs this many moles";
+    }, {
+      readonly relation: () => Relation;
+      readonly solveFor: "m";
+      readonly using: {
+        readonly n: "n";
+        readonly M: "M";
+      };
+      readonly gives: "m";
+      readonly because: "and that many moles of this substance weigh this much, which is what goes on the balance";
+    }];
+  };
+  readonly concentration: {
+    readonly kind: "definition";
+    readonly summary: "Concentration is how many moles are dissolved in each unit of volume. That is what the word means.";
+  };
+  readonly molesFromMass: {
+    readonly kind: "definition";
+    readonly 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.
+   */
+  readonly beerLambert: {
+    readonly kind: "measured";
+    readonly 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.";
+    readonly 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.";
+  };
+  readonly idealGas: {
+    readonly kind: "measured";
+    readonly 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.";
+    readonly 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.";
+  };
+  readonly heatEnergy: {
+    readonly kind: "definition";
+    readonly 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/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 };