@classytic/stage 0.3.0 → 0.4.0

package/dist/waves/wave.d.mts

@@ -0,0 +1,154 @@
+//#region src/waves/wave.d.ts
+/**
+ * The travelling wave, as the one equation everything else in this module is a
+ * special case of:
+ *
+ *     y(x, t) = A·sin(kx − ωt + φ)
+ *
+ * with k = 2π/λ the wave number (radians per metre, the spatial rate) and
+ * ω = 2πf the angular frequency (radians per second, the temporal rate). The
+ * two rates are the whole content of the formula: a wave is something periodic
+ * in space AND in time, and v = fλ is the statement that the two periodicities
+ * have to keep step.
+ *
+ * ## The sign inside the bracket is the direction of travel
+ *
+ * `kx − ωt` moves in the +x direction and `kx + ωt` moves in −x, because a
+ * point of constant phase needs x to grow with t in the first and shrink in the
+ * second. Getting it backwards is silent: the wave still looks like a wave, it
+ * just goes the wrong way, and a standing-wave lab built on two of them will
+ * produce a travelling wave instead of nodes. `direction` is therefore an
+ * explicit field rather than a sign a caller is trusted to embed.
+ *
+ * ## Why velocity and acceleration are here
+ *
+ * A particle in the wave oscillates; the wave profile translates. Those are
+ * different motions with different speeds, and conflating them is the standard
+ * misconception. `waveSpeed` is how fast the PATTERN moves (v = fλ);
+ * `particleVelocity` is how fast a bit of the medium moves (∂y/∂t), which is
+ * zero at the crests and maximum at zero displacement. Both are exported, named
+ * so they cannot be mistaken for one another.
+ *
+ * Units: SI. Amplitude and displacement in metres, wavelength in metres,
+ * frequency in hertz, time in seconds, angles in radians.
+ */
+type Direction = 'forward' | 'backward';
+interface Wave {
+  /** Peak displacement from equilibrium, m. */
+  amplitude: number;
+  /** Distance between repeats, m. */
+  wavelength: number;
+  /** Repeats per second, Hz. */
+  frequency: number;
+  /** Phase offset at x = 0, t = 0, radians. */
+  phase?: number;
+  /** '+x' when omitted: the `kx − ωt` form. */
+  direction?: Direction;
+}
+/** Wave number k = 2π/λ, radians per metre. */
+declare const waveNumber: (wavelength: number) => number;
+/** Angular frequency ω = 2πf, radians per second. */
+declare const angularFrequency: (frequency: number) => number;
+/** Frequency from angular frequency, Hz. */
+declare const frequencyFromAngular: (omega: number) => number;
+/** Wavelength from a wave number, m. */
+declare const wavelengthFromWaveNumber: (k: number) => number;
+/** Period T = 1/f, seconds. */
+declare const period: (frequency: number) => number;
+/** Frequency from a period, Hz. */
+declare const frequencyFromPeriod: (periodSeconds: number) => number;
+/**
+ * Wave speed v = fλ, m/s: how fast the PATTERN travels.
+ *
+ * Not the speed of the medium. A water wave can carry a crest across a pond at
+ * a metre a second while every drop merely bobs up and down; `particleVelocity`
+ * is the other number.
+ */
+declare const waveSpeed: (frequency: number, wavelength: number) => number;
+/** Wavelength from speed and frequency: λ = v/f, m. */
+declare const wavelengthFromSpeed: (speed: number, frequency: number) => number;
+/** Frequency from speed and wavelength: f = v/λ, Hz. */
+declare const frequencyFromSpeed: (speed: number, wavelength: number) => number;
+/** The speed of this particular wave, m/s. */
+declare const speedOf: (wave: Wave) => number;
+/** The total phase kx − ωt + φ at a point and time, radians. */
+declare function phaseAt(wave: Wave, x: number, t: number): number;
+/** Displacement y = A·sin(kx − ωt + φ), m. */
+declare function displacement(wave: Wave, x: number, t: number): number;
+/**
+ * Velocity of the MEDIUM at a point, m/s: ∂y/∂t = −ωA·cos(kx − ωt + φ).
+ *
+ * Zero at the crests and troughs, largest as the particle passes through zero.
+ * That is the opposite of where the displacement is largest, and it is the
+ * whole reason the energy of an oscillation keeps sloshing between kinetic and
+ * potential rather than sitting still.
+ */
+declare function particleVelocity(wave: Wave, x: number, t: number): number;
+/**
+ * Acceleration of the medium, m/s²: ∂²y/∂t² = −ω²y.
+ *
+ * Proportional to the displacement and opposite to it, which is the definition
+ * of simple harmonic motion. Every particle in a sinusoidal wave is an
+ * oscillator, and `shm.ts` is that statement followed through.
+ */
+declare function particleAcceleration(wave: Wave, x: number, t: number): number;
+/**
+ * Largest speed any particle reaches, m/s: ωA.
+ *
+ * Unpacks the wave and hands off to `shm.maxSpeed`, because a particle in a
+ * wave is an oscillator and ωA is that oscillator's top speed, not a separate
+ * fact about waves. It was written out here as well until the two were noticed
+ * to be the same line.
+ *
+ * Note this is the speed of the MEDIUM, not of the wave. The two are unrelated
+ * and routinely confused: a ripple crossing a tank at 0.3 m/s is made of water
+ * moving at a few millimetres per second.
+ */
+declare const maxParticleSpeed: (wave: Wave) => number;
+/**
+ * Phase difference from a path difference, radians: Δφ = 2π·Δx/λ.
+ *
+ * The bridge between the geometric picture (one route is longer) and the
+ * algebraic one (the waves arrive out of step), and the single most useful
+ * conversion in interference.
+ */
+declare const phaseFromPath: (pathDifference: number, wavelength: number) => number;
+/** Path difference from a phase difference, m: Δx = λ·Δφ/2π. */
+declare const pathFromPhase: (phase: number, wavelength: number) => number;
+/**
+ * Whether two waves arriving with this path difference reinforce or cancel.
+ *
+ * A whole number of wavelengths is constructive, a half-odd number is
+ * destructive, and anything else is in between. Returned as a fraction of a
+ * cycle rather than a boolean, because the in-between case is most of the
+ * pattern and calling it "neither" throws away the part that varies.
+ */
+declare function interferenceAt(pathDifference: number, wavelength: number): {
+  /** Path difference in wavelengths. */orders: number; /** How far through a cycle out of step, 0 to 1. */
+  cycleFraction: number; /** Resultant amplitude as a fraction of the maximum, for equal sources. */
+  amplitudeFraction: number;
+  constructive: boolean;
+  destructive: boolean;
+};
+/**
+ * Sample one wave across a span, for drawing.
+ *
+ * Returns `samples + 1` points so both ends are included, which is what makes a
+ * polyline close on a full wavelength instead of stopping a step short.
+ */
+declare function sampleWave(wave: Wave, from: number, to: number, t: number, samples?: number): {
+  x: number;
+  y: number;
+}[];
+/**
+ * Intensity relative to a reference amplitude.
+ *
+ * Intensity goes as the SQUARE of amplitude, which is why halving the amplitude
+ * quarters the brightness or the loudness, and why a decibel scale exists at
+ * all. Kept as a ratio rather than absolute watts, because the constant of
+ * proportionality depends on the medium and cancels in every question that asks
+ * this.
+ */
+declare const intensityRatio: (amplitude: number, referenceAmplitude: number) => number;
+//#endregion
+export { Direction, Wave, angularFrequency, displacement, frequencyFromAngular, frequencyFromPeriod, frequencyFromSpeed, intensityRatio, interferenceAt, maxParticleSpeed, particleAcceleration, particleVelocity, pathFromPhase, period, phaseAt, phaseFromPath, sampleWave, speedOf, waveNumber, waveSpeed, wavelengthFromSpeed, wavelengthFromWaveNumber };

package/dist/waves/wave.mjs

@@ -0,0 +1,178 @@
+import { maxSpeed } from "./shm.mjs";
+
+//#region src/waves/wave.ts
+/**
+* The travelling wave, as the one equation everything else in this module is a
+* special case of:
+*
+*     y(x, t) = A·sin(kx − ωt + φ)
+*
+* with k = 2π/λ the wave number (radians per metre, the spatial rate) and
+* ω = 2πf the angular frequency (radians per second, the temporal rate). The
+* two rates are the whole content of the formula: a wave is something periodic
+* in space AND in time, and v = fλ is the statement that the two periodicities
+* have to keep step.
+*
+* ## The sign inside the bracket is the direction of travel
+*
+* `kx − ωt` moves in the +x direction and `kx + ωt` moves in −x, because a
+* point of constant phase needs x to grow with t in the first and shrink in the
+* second. Getting it backwards is silent: the wave still looks like a wave, it
+* just goes the wrong way, and a standing-wave lab built on two of them will
+* produce a travelling wave instead of nodes. `direction` is therefore an
+* explicit field rather than a sign a caller is trusted to embed.
+*
+* ## Why velocity and acceleration are here
+*
+* A particle in the wave oscillates; the wave profile translates. Those are
+* different motions with different speeds, and conflating them is the standard
+* misconception. `waveSpeed` is how fast the PATTERN moves (v = fλ);
+* `particleVelocity` is how fast a bit of the medium moves (∂y/∂t), which is
+* zero at the crests and maximum at zero displacement. Both are exported, named
+* so they cannot be mistaken for one another.
+*
+* Units: SI. Amplitude and displacement in metres, wavelength in metres,
+* frequency in hertz, time in seconds, angles in radians.
+*/
+const finite = (value, what) => {
+	if (!Number.isFinite(value)) throw new RangeError(`${what} must be a finite number.`);
+	return value;
+};
+const positive = (value, what) => {
+	if (!Number.isFinite(value) || value <= 0) throw new RangeError(`${what} must be positive.`);
+	return value;
+};
+/** Wave number k = 2π/λ, radians per metre. */
+const waveNumber = (wavelength) => 2 * Math.PI / positive(wavelength, "A wavelength");
+/** Angular frequency ω = 2πf, radians per second. */
+const angularFrequency = (frequency) => 2 * Math.PI * positive(frequency, "A frequency");
+/** Frequency from angular frequency, Hz. */
+const frequencyFromAngular = (omega) => positive(omega, "An angular frequency") / (2 * Math.PI);
+/** Wavelength from a wave number, m. */
+const wavelengthFromWaveNumber = (k) => 2 * Math.PI / positive(k, "A wave number");
+/** Period T = 1/f, seconds. */
+const period = (frequency) => 1 / positive(frequency, "A frequency");
+/** Frequency from a period, Hz. */
+const frequencyFromPeriod = (periodSeconds) => 1 / positive(periodSeconds, "A period");
+/**
+* Wave speed v = fλ, m/s: how fast the PATTERN travels.
+*
+* Not the speed of the medium. A water wave can carry a crest across a pond at
+* a metre a second while every drop merely bobs up and down; `particleVelocity`
+* is the other number.
+*/
+const waveSpeed = (frequency, wavelength) => positive(frequency, "A frequency") * positive(wavelength, "A wavelength");
+/** Wavelength from speed and frequency: λ = v/f, m. */
+const wavelengthFromSpeed = (speed, frequency) => positive(speed, "A wave speed") / positive(frequency, "A frequency");
+/** Frequency from speed and wavelength: f = v/λ, Hz. */
+const frequencyFromSpeed = (speed, wavelength) => positive(speed, "A wave speed") / positive(wavelength, "A wavelength");
+/** The speed of this particular wave, m/s. */
+const speedOf = (wave) => waveSpeed(wave.frequency, wave.wavelength);
+/** The total phase kx − ωt + φ at a point and time, radians. */
+function phaseAt(wave, x, t) {
+	const k = waveNumber(wave.wavelength);
+	const omega = angularFrequency(wave.frequency);
+	const travel = wave.direction === "backward" ? 1 : -1;
+	return k * finite(x, "A position") + travel * omega * finite(t, "A time") + (wave.phase ?? 0);
+}
+/** Displacement y = A·sin(kx − ωt + φ), m. */
+function displacement(wave, x, t) {
+	return positive(wave.amplitude, "An amplitude") * Math.sin(phaseAt(wave, x, t));
+}
+/**
+* Velocity of the MEDIUM at a point, m/s: ∂y/∂t = −ωA·cos(kx − ωt + φ).
+*
+* Zero at the crests and troughs, largest as the particle passes through zero.
+* That is the opposite of where the displacement is largest, and it is the
+* whole reason the energy of an oscillation keeps sloshing between kinetic and
+* potential rather than sitting still.
+*/
+function particleVelocity(wave, x, t) {
+	const omega = angularFrequency(wave.frequency);
+	return (wave.direction === "backward" ? 1 : -1) * -omega * positive(wave.amplitude, "An amplitude") * Math.cos(phaseAt(wave, x, t));
+}
+/**
+* Acceleration of the medium, m/s²: ∂²y/∂t² = −ω²y.
+*
+* Proportional to the displacement and opposite to it, which is the definition
+* of simple harmonic motion. Every particle in a sinusoidal wave is an
+* oscillator, and `shm.ts` is that statement followed through.
+*/
+function particleAcceleration(wave, x, t) {
+	const omega = angularFrequency(wave.frequency);
+	return -(omega * omega) * displacement(wave, x, t);
+}
+/**
+* Largest speed any particle reaches, m/s: ωA.
+*
+* Unpacks the wave and hands off to `shm.maxSpeed`, because a particle in a
+* wave is an oscillator and ωA is that oscillator's top speed, not a separate
+* fact about waves. It was written out here as well until the two were noticed
+* to be the same line.
+*
+* Note this is the speed of the MEDIUM, not of the wave. The two are unrelated
+* and routinely confused: a ripple crossing a tank at 0.3 m/s is made of water
+* moving at a few millimetres per second.
+*/
+const maxParticleSpeed = (wave) => maxSpeed(wave.amplitude, angularFrequency(wave.frequency));
+/**
+* Phase difference from a path difference, radians: Δφ = 2π·Δx/λ.
+*
+* The bridge between the geometric picture (one route is longer) and the
+* algebraic one (the waves arrive out of step), and the single most useful
+* conversion in interference.
+*/
+const phaseFromPath = (pathDifference, wavelength) => 2 * Math.PI * finite(pathDifference, "A path difference") / positive(wavelength, "A wavelength");
+/** Path difference from a phase difference, m: Δx = λ·Δφ/2π. */
+const pathFromPhase = (phase, wavelength) => finite(phase, "A phase difference") * positive(wavelength, "A wavelength") / (2 * Math.PI);
+/**
+* Whether two waves arriving with this path difference reinforce or cancel.
+*
+* A whole number of wavelengths is constructive, a half-odd number is
+* destructive, and anything else is in between. Returned as a fraction of a
+* cycle rather than a boolean, because the in-between case is most of the
+* pattern and calling it "neither" throws away the part that varies.
+*/
+function interferenceAt(pathDifference, wavelength) {
+	const orders = finite(pathDifference, "A path difference") / positive(wavelength, "A wavelength");
+	const cycleFraction = (orders % 1 + 1) % 1;
+	const amplitudeFraction = Math.abs(Math.cos(Math.PI * orders));
+	const TOL = 1e-9;
+	return {
+		orders,
+		cycleFraction,
+		amplitudeFraction,
+		constructive: Math.min(cycleFraction, 1 - cycleFraction) < TOL,
+		destructive: Math.abs(cycleFraction - .5) < TOL
+	};
+}
+/**
+* Sample one wave across a span, for drawing.
+*
+* Returns `samples + 1` points so both ends are included, which is what makes a
+* polyline close on a full wavelength instead of stopping a step short.
+*/
+function sampleWave(wave, from, to, t, samples = 200) {
+	if (!Number.isInteger(samples) || samples < 1) throw new RangeError("A wave needs at least one sample interval to be drawn.");
+	const span = finite(to, "The end of the span") - finite(from, "The start of the span");
+	return Array.from({ length: samples + 1 }, (_, i) => {
+		const x = from + span * i / samples;
+		return {
+			x,
+			y: displacement(wave, x, t)
+		};
+	});
+}
+/**
+* Intensity relative to a reference amplitude.
+*
+* Intensity goes as the SQUARE of amplitude, which is why halving the amplitude
+* quarters the brightness or the loudness, and why a decibel scale exists at
+* all. Kept as a ratio rather than absolute watts, because the constant of
+* proportionality depends on the medium and cancels in every question that asks
+* this.
+*/
+const intensityRatio = (amplitude, referenceAmplitude) => (finite(amplitude, "An amplitude") / positive(referenceAmplitude, "A reference amplitude")) ** 2;
+
+//#endregion
+export { angularFrequency, displacement, frequencyFromAngular, frequencyFromPeriod, frequencyFromSpeed, intensityRatio, interferenceAt, maxParticleSpeed, particleAcceleration, particleVelocity, pathFromPhase, period, phaseAt, phaseFromPath, sampleWave, speedOf, waveNumber, waveSpeed, wavelengthFromSpeed, wavelengthFromWaveNumber };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/stage",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Domain-neutral visual primitive engine for the web. Declarative SVG diagram/math primitives, draggable handles, a math↔pixel coordinate system, a motion core + energy effect defs, theming, pure sim cores, and a small kit of neutral glyph primitives. Reactive, web-native, agent-drivable. The render foundation under @classytic/labs (subject-matter glyphs live there); canvas + 3D subpaths later.",
   "author": "Classytic",
   "license": "MIT",
@@ -23,6 +23,10 @@
       "types": "./dist/core/index.d.mts",
       "default": "./dist/core/index.mjs"
     },
+    "./constants": {
+      "types": "./dist/core/constants.d.mts",
+      "default": "./dist/core/constants.mjs"
+    },
     "./primitives": {
       "types": "./dist/primitives/index.d.mts",
       "default": "./dist/primitives/index.mjs"
@@ -71,20 +75,88 @@
       "types": "./dist/thermo/index.d.mts",
       "default": "./dist/thermo/index.mjs"
     },
+    "./optics": {
+      "types": "./dist/optics/index.d.mts",
+      "default": "./dist/optics/index.mjs"
+    },
+    "./waves": {
+      "types": "./dist/waves/index.d.mts",
+      "default": "./dist/waves/index.mjs"
+    },
+    "./atomic": {
+      "types": "./dist/atomic/index.d.mts",
+      "default": "./dist/atomic/index.mjs"
+    },
     "./chem": {
       "types": "./dist/chem/index.d.mts",
       "default": "./dist/chem/index.mjs"
     },
+    "./electro": {
+      "types": "./dist/electro/index.d.mts",
+      "default": "./dist/electro/index.mjs"
+    },
+    "./colour": {
+      "types": "./dist/colour/index.d.mts",
+      "default": "./dist/colour/index.mjs"
+    },
+    "./physics": {
+      "types": "./dist/physics/index.d.mts",
+      "default": "./dist/physics/index.mjs"
+    },
+    "./physics/magnetism": {
+      "types": "./dist/physics/magnetism/index.d.mts",
+      "default": "./dist/physics/magnetism/index.mjs"
+    },
+    "./physics/electrostatics": {
+      "types": "./dist/physics/electrostatics/index.d.mts",
+      "default": "./dist/physics/electrostatics/index.mjs"
+    },
+    "./physics/ac": {
+      "types": "./dist/physics/ac/index.d.mts",
+      "default": "./dist/physics/ac/index.mjs"
+    },
     "./finance": {
       "types": "./dist/finance/index.d.mts",
       "default": "./dist/finance/index.mjs"
     },
+    "./finance/accounting": {
+      "types": "./dist/finance/accounting/index.d.mts",
+      "default": "./dist/finance/accounting/index.mjs"
+    },
+    "./finance/management-accounting": {
+      "types": "./dist/finance/management-accounting/index.d.mts",
+      "default": "./dist/finance/management-accounting/index.mjs"
+    },
+    "./networking": {
+      "types": "./dist/networking/index.d.mts",
+      "default": "./dist/networking/index.mjs"
+    },
+    "./networking/models": {
+      "types": "./dist/networking/models/index.d.mts",
+      "default": "./dist/networking/models/index.mjs"
+    },
+    "./networking/cloud": {
+      "types": "./dist/networking/cloud/index.d.mts",
+      "default": "./dist/networking/cloud/index.mjs"
+    },
+    "./networking/topology": {
+      "types": "./dist/networking/topology/index.d.mts",
+      "default": "./dist/networking/topology/index.mjs"
+    },
     "./steps": {
       "types": "./dist/steps/index.d.mts",
       "default": "./dist/steps/index.mjs"
     },
     "./styles.css": "./styles.css",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./quantity": {
+      "types": "./dist/quantity/index.d.mts",
+      "default": "./dist/quantity/index.mjs"
+    },
+    "./relation": {
+      "types": "./dist/relation/index.d.mts",
+      "default": "./dist/relation/index.mjs"
+    }
   },
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",