@mstone6969/graph 0.0.0-stage → 0.2.0

package/dist/charts/engineering/PsychrometricChart.js

@@ -0,0 +1,258 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { EngineeringChart } from "./EngineeringChart.js";
+import { scaleLinear } from "d3";
+// src/charts/engineering/PsychrometricChart.ts
+var PsychrometricOverlay = /* @__PURE__ */ function(PsychrometricOverlay) {
+	PsychrometricOverlay["Humidity"] = "humidity-lines";
+	PsychrometricOverlay["Enthalpy"] = "enthalpy";
+	PsychrometricOverlay["WetBulb"] = "wet-bulb";
+	PsychrometricOverlay["Volume"] = "specific-volume";
+	PsychrometricOverlay["Full"] = "full-grid";
+	return PsychrometricOverlay;
+}({});
+var PsychrometricOrientation = /* @__PURE__ */ function(PsychrometricOrientation) {
+	PsychrometricOrientation["Ashrae"] = "ashrae";
+	PsychrometricOrientation["Mollier"] = "mollier-hx";
+	return PsychrometricOrientation;
+}({});
+var saturationPressure = (t) => .61094 * Math.exp(17.625 * t / (t + 243.04));
+var pressureAt = (elevation) => 101.325 * (1 - 225577e-10 * elevation) ** 5.2559;
+var ratioOf = (vapour, pressure) => .62198 * vapour / (pressure - vapour);
+var enthalpyRatio = (h, t) => (h - 1.006 * t) / (2501 + 1.86 * t);
+function sampleProcess(seed) {
+	const [a, b] = SampleData.points(seed, 2, 1).map((row) => (+row.size - 3) / 30);
+	const state = (temperature, humidity, process) => ({
+		temperature,
+		humidityRatio: +ratioOf(humidity / 100 * saturationPressure(temperature), 101.325).toFixed(5),
+		process
+	});
+	const outdoor = 32 + 4 * a, indoor = 24 + b, mixed = (outdoor + 2 * indoor) / 3;
+	return [
+		state(outdoor, 55, "Cooling"),
+		state(mixed, 58, "Cooling"),
+		state(13, 96, "Cooling"),
+		state(17, 72, "Cooling"),
+		state(indoor, 50, "Cooling"),
+		state(4, 80, "Heating"),
+		state(22, 21, "Heating"),
+		state(22 + 2 * b, 40, "Heating")
+	];
+}
+/** Design HVAC processes on the moist-air state chart, drawn for the site's actual pressure. */
+var PsychrometricChart = class extends EngineeringChart {
+	static meta = {
+		id: "psychrometric-chart",
+		name: "Psychrometric chart",
+		family: ChartFamily.Scientific,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Plots moist-air states over humidity, enthalpy, wet-bulb and volume curves for HVAC design.",
+		tags: [
+			"hvac",
+			"humidity",
+			"dew point",
+			"air conditioning",
+			"thermodynamics"
+		],
+		sample: sampleProcess,
+		variants: {
+			overlay: Object.values(PsychrometricOverlay),
+			orientation: ["ashrae", "mollier-hx"],
+			elevation: [0, 1600],
+			comfort: [true, false],
+			connected: [true, false]
+		}
+	};
+	defaults() {
+		return {
+			temperature: "temperature",
+			humidityRatio: "humidityRatio",
+			process: "process",
+			overlay: "humidity-lines",
+			orientation: "ashrae",
+			elevation: 0,
+			comfort: true,
+			connected: true
+		};
+	}
+	draw(ctx) {
+		const { temperature, humidityRatio, process, overlay, orientation, elevation, comfort, connected, xLabel, yLabel } = this.options;
+		const { width, height } = ctx.plot;
+		const pressure = pressureAt(elevation);
+		const states = this.rows.map((row) => ({
+			temperature: this.num(row, temperature),
+			ratio: this.num(row, humidityRatio),
+			process: String(row[process] ?? "States")
+		})).filter((s) => Number.isFinite(s.temperature) && Number.isFinite(s.ratio) && s.ratio >= 0);
+		const [tLow, tHigh] = this.span([
+			-5,
+			45,
+			...states.map((s) => s.temperature)
+		]);
+		const wTop = Math.max(.03, ...states.map((s) => s.ratio * 1.1));
+		const saturation = (t) => ratioOf(saturationPressure(t), pressure);
+		const hx = orientation === "mollier-hx";
+		const temperatureScale = scaleLinear([tLow, tHigh], hx ? [height, 0] : [0, width]);
+		const ratioScale = scaleLinear([0, wTop], hx ? [0, width] : [height, 0]);
+		const at = (t, w) => hx ? [ratioScale(w), temperatureScale(t)] : [temperatureScale(t), ratioScale(w)];
+		const milli = (value) => `${+(value * 1e3).toFixed(1)}`;
+		const axes = {
+			t: xLabel ?? "Dry-bulb temperature (°C)",
+			w: yLabel ?? "Humidity ratio (g/kg)"
+		};
+		this.frame(ctx, hx ? {
+			x: ratioScale,
+			y: temperatureScale,
+			xFormat: milli,
+			xTitle: axes.w,
+			yTitle: axes.t
+		} : {
+			x: temperatureScale,
+			y: ratioScale,
+			yFormat: milli,
+			xTitle: axes.t,
+			yTitle: axes.w
+		});
+		const sweep = (count) => Array.from({ length: count }, (_, i) => tLow + (tHigh - tLow) * i / (count - 1));
+		const clip = (t, w) => w >= 0 && w <= wTop && w <= saturation(t) * 1.0005 ? at(t, w) : [NaN, NaN];
+		const humidityLines = [
+			10,
+			20,
+			30,
+			40,
+			50,
+			60,
+			70,
+			80,
+			90
+		].filter((rh) => overlay !== "humidity-lines" || rh % 20 === 0 || rh === 50);
+		const curve = (rh) => sweep(70).map((t) => clip(t, ratioOf(rh / 100 * saturationPressure(t), pressure)));
+		this.guides(ctx, "humidity-lines", humidityLines.map((rh) => ({
+			key: `rh${rh}`,
+			points: curve(rh)
+		})));
+		const notes = humidityLines.filter((rh) => rh % 20 === 0).flatMap((rh) => {
+			const seat = curve(rh).filter((p) => Number.isFinite(p[0])).at(-1);
+			return seat ? [{
+				key: `rh${rh}`,
+				text: `${rh}%`,
+				x: seat[0] - (hx ? 0 : 2),
+				y: seat[1] + (hx ? 10 : -3),
+				anchor: hx ? "middle" : "end",
+				tone: "muted",
+				size: 9
+			}] : [];
+		});
+		const wants = (line) => overlay === line || overlay === "full-grid";
+		if (wants("enthalpy")) {
+			const lines = [
+				0,
+				20,
+				40,
+				60,
+				80,
+				100,
+				120
+			].map((h) => ({
+				key: `h${h}`,
+				h,
+				dash: "4 3",
+				points: sweep(50).map((t) => clip(t, enthalpyRatio(h, t)))
+			}));
+			this.guides(ctx, "enthalpy", lines);
+			notes.push(...lines.flatMap((line) => {
+				const seat = line.points.find((p) => Number.isFinite(p[0]));
+				return seat ? [{
+					key: line.key,
+					text: `${line.h} kJ`,
+					x: seat[0] + (hx ? 4 : -2),
+					y: seat[1] - 3,
+					anchor: hx ? "start" : "end",
+					tone: "muted",
+					size: 9
+				}] : [];
+			}));
+		}
+		this.annotate(ctx, "scale-notes", notes);
+		if (wants("wet-bulb")) this.guides(ctx, "wet-bulb", [
+			0,
+			5,
+			10,
+			15,
+			20,
+			25,
+			30
+		].map((wet) => {
+			const base = saturation(wet);
+			return {
+				key: `wb${wet}`,
+				dash: "1 3",
+				points: sweep(50).filter((t) => t >= wet).map((t) => clip(t, ((2501 - 2.326 * wet) * base - 1.006 * (t - wet)) / (2501 + 1.86 * t - 4.186 * wet)))
+			};
+		}));
+		if (wants("specific-volume")) this.guides(ctx, "specific-volume", [
+			.8,
+			.82,
+			.84,
+			.86,
+			.88,
+			.9,
+			.92,
+			.94
+		].map((v) => ({
+			key: `v${v}`,
+			dash: "7 3",
+			points: sweep(50).map((t) => clip(t, (v * pressure / (.287042 * (t + 273.15)) - 1) / 1.6078))
+		})));
+		this.traces(ctx, "saturation", [{
+			key: "sat",
+			color: ctx.theme.inkSecondary,
+			points: sweep(90).map((t) => clip(t, saturation(t)))
+		}]);
+		if (comfort) {
+			const edge = (rh) => Array.from({ length: 13 }, (_, i) => 20 + i * .5).map((t) => at(t, ratioOf(rh / 100 * saturationPressure(t), pressure)));
+			const box = [...edge(30), ...edge(60).reverse()];
+			this.shapes(ctx, "comfort", [{
+				key: "zone",
+				fill: ctx.theme.good,
+				opacity: .2,
+				d: `M${box.join("L")}Z`
+			}]);
+		}
+		const tip = (s) => {
+			const vapour = s.ratio * pressure / (.62198 + s.ratio);
+			return {
+				title: s.process,
+				color: ctx.palette.color(s.process),
+				rows: [
+					["Dry bulb", `${s.temperature.toFixed(1)} °C`],
+					["Humidity ratio", `${(s.ratio * 1e3).toFixed(1)} g/kg`],
+					["Relative humidity", `${(vapour / saturationPressure(s.temperature) * 100).toFixed(0)} %`],
+					["Enthalpy", `${(1.006 * s.temperature + s.ratio * (2501 + 1.86 * s.temperature)).toFixed(1)} kJ/kg`]
+				]
+			};
+		};
+		const chains = this.series(process, this.rows).map(([name]) => ({
+			name,
+			states: states.filter((s) => s.process === name)
+		}));
+		if (connected) {
+			this.traces(ctx, "processes", chains.map((chain) => ({
+				key: chain.name,
+				color: ctx.palette.color(chain.name),
+				points: chain.states.map((s) => at(s.temperature, s.ratio))
+			})));
+			this.shapes(ctx, "arrows", chains.flatMap((chain) => chain.states.slice(1).map((s, i) => {
+				const a = at(chain.states[i].temperature, chain.states[i].ratio), b = at(s.temperature, s.ratio), middle = [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2];
+				return {
+					key: `${chain.name}${i}`,
+					fill: ctx.palette.color(chain.name),
+					d: this.arrowhead(middle, Math.atan2(b[1] - a[1], b[0] - a[0]), 6)
+				};
+			})));
+		}
+		this.dots(ctx, "states", states, (s) => at(s.temperature, s.ratio), (s) => ctx.palette.color(s.process), tip);
+	}
+};
+export { PsychrometricChart, PsychrometricOrientation, PsychrometricOverlay };

package/dist/charts/engineering/PumpCurveChart.js

@@ -0,0 +1,310 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { EngineeringChart } from "./EngineeringChart.js";
+import { curveMonotoneX, scaleLinear } from "d3";
+// src/charts/engineering/PumpCurveChart.ts
+var PumpPanels = /* @__PURE__ */ function(PumpPanels) {
+	PumpPanels["Head"] = "head";
+	PumpPanels["HeadEfficiency"] = "head-efficiency";
+	PumpPanels["All"] = "head-efficiency-power";
+	return PumpPanels;
+}({});
+var PumpArrangement = /* @__PURE__ */ function(PumpArrangement) {
+	PumpArrangement["Single"] = "single-pump";
+	PumpArrangement["Parallel"] = "two-parallel";
+	PumpArrangement["Series"] = "two-series";
+	return PumpArrangement;
+}({});
+var LEVELS = [
+	.6,
+	.7,
+	.76
+];
+function samplePump(seed) {
+	const [a, b] = SampleData.points(seed, 2, 1).map((row) => (+row.size - 3) / 30);
+	const shutoff = 46 + 8 * a, reach = 300 + 60 * b;
+	return [
+		1,
+		.87,
+		.74
+	].flatMap((ratio) => Array.from({ length: 41 }, (_, i) => {
+		const share = .02 + i / 40 * .98, flow = share * reach * ratio, head = (shutoff - shutoff * .8 * share ** 2.1 + 3 * share) * ratio * ratio;
+		const efficiency = Math.max(.05, .82 * (1 - ((share - .68) / .68) ** 2));
+		return {
+			speed: `${Math.round(2950 * ratio)} rpm`,
+			flow: +flow.toFixed(1),
+			head: +head.toFixed(2),
+			efficiency: +efficiency.toFixed(3),
+			power: +(flow * head * 9.81 / 3600 / efficiency).toFixed(2)
+		};
+	}));
+}
+/** Select a pump: head, efficiency and power against flow, solved against the system it feeds. */
+var PumpCurveChart = class extends EngineeringChart {
+	static meta = {
+		id: "pump-curve-chart",
+		name: "Pump curve",
+		family: ChartFamily.Scientific,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Shows pump head, efficiency and power against flow, with best efficiency and duty points.",
+		tags: [
+			"centrifugal pump",
+			"fan curve",
+			"system curve",
+			"duty point",
+			"bep",
+			"hydraulics"
+		],
+		sample: samplePump,
+		variants: {
+			panels: [
+				"head-efficiency",
+				"head",
+				"head-efficiency-power"
+			],
+			arrangement: [
+				"single-pump",
+				"two-parallel",
+				"two-series"
+			],
+			system: [true, false],
+			isoEfficiency: [false, true]
+		}
+	};
+	defaults() {
+		return {
+			flow: "flow",
+			head: "head",
+			efficiency: "efficiency",
+			power: "power",
+			speed: "speed",
+			panels: "head-efficiency",
+			arrangement: "single-pump",
+			system: true,
+			isoEfficiency: false,
+			xLabel: "Flow (m³/h)",
+			yLabel: "Head (m)"
+		};
+	}
+	curves() {
+		const { flow, head, efficiency, power, speed } = this.options;
+		return this.series(speed).map(([name, rows]) => ({
+			speed: name,
+			points: rows.map((row) => ({
+				speed: name,
+				flow: this.num(row, flow),
+				head: this.num(row, head),
+				efficiency: this.num(row, efficiency),
+				power: this.num(row, power)
+			})).filter((p) => Number.isFinite(p.flow) && Number.isFinite(p.head)).sort((a, b) => a.flow - b.flow)
+		})).filter((curve) => curve.points.length);
+	}
+	combine(p) {
+		const { arrangement } = this.options;
+		if (arrangement === "two-parallel") return {
+			...p,
+			flow: p.flow * 2,
+			power: p.power * 2
+		};
+		if (arrangement === "two-series") return {
+			...p,
+			head: p.head * 2,
+			power: p.power * 2
+		};
+		return p;
+	}
+	duty(points, system) {
+		for (let i = 1; i < points.length; i++) {
+			const a = points[i - 1], b = points[i], u = a.head - system(a.flow), v = b.head - system(b.flow);
+			if (u * v > 0) continue;
+			const t = u / (u - v || 1), mix = (from, to) => from + (to - from) * t;
+			return {
+				speed: a.speed,
+				flow: mix(a.flow, b.flow),
+				head: mix(a.head, b.head),
+				efficiency: mix(a.efficiency, b.efficiency),
+				power: mix(a.power, b.power)
+			};
+		}
+		return null;
+	}
+	isolines(curves, level) {
+		const seats = curves.map(({ points }) => {
+			const peak = points.reduce((best, p, i) => p.efficiency > points[best].efficiency ? i : best, 0);
+			const find = (from, step) => {
+				for (let i = from; i > 0 && i < points.length; i += step) {
+					const a = points[i - 1], b = points[i];
+					if ((a.efficiency - level) * (b.efficiency - level) <= 0 && a.efficiency !== b.efficiency) {
+						const t = (level - a.efficiency) / (b.efficiency - a.efficiency);
+						return this.combine({
+							...a,
+							flow: a.flow + (b.flow - a.flow) * t,
+							head: a.head + (b.head - a.head) * t
+						});
+					}
+				}
+				return null;
+			};
+			return [find(peak, -1), find(peak + 1, 1)];
+		});
+		return [0, 1].map((side) => seats.flatMap((pair) => pair[side] ? [[pair[side].flow, pair[side].head]] : []));
+	}
+	trend(ctx, name, curves, x, height, value, title, label, hideX) {
+		const shown = curves.map((c) => ({
+			...c,
+			points: c.points.filter((p) => Number.isFinite(value(p)))
+		}));
+		const y = scaleLinear(this.span(shown.flatMap((c) => c.points.map(value)), {
+			zero: true,
+			pad: .06
+		}), [height, 0]).nice();
+		this.frame(ctx, {
+			x,
+			y,
+			name: `${name}-frame`,
+			hideX,
+			xTitle: this.options.xLabel,
+			yTitle: title,
+			yFormat: label
+		});
+		const at = (p) => [x(p.flow), y(value(p))];
+		this.traces(ctx, name, shown.map((c) => ({
+			key: c.speed,
+			color: ctx.palette.color(c.speed),
+			curve: curveMonotoneX,
+			points: c.points.map(at)
+		})));
+		shown.forEach((c, i) => this.probes(ctx, `${name}-probe-${i}`, c.points, at, (p) => this.tipFor(ctx, p)));
+	}
+	tipFor(ctx, p) {
+		return {
+			title: p.speed,
+			color: ctx.palette.color(p.speed),
+			rows: [
+				["Flow", p.flow.toFixed(1)],
+				["Head", p.head.toFixed(1)],
+				["Efficiency", `${(p.efficiency * 100).toFixed(0)}%`],
+				["Power", p.power.toFixed(1)]
+			]
+		};
+	}
+	draw(ctx) {
+		const { panels, arrangement, system, isoEfficiency, staticHead, friction, xLabel, yLabel } = this.options;
+		const { width, height } = ctx.plot;
+		const raw = this.curves();
+		const curves = raw.map((c) => ({
+			speed: c.speed,
+			points: c.points.map((p) => this.combine(p))
+		}));
+		const gap = 8;
+		const rows = panels === "head-efficiency-power" ? 3 : panels === "head-efficiency" ? 2 : 1;
+		const lower = rows === 1 ? 0 : Math.round(height * (rows === 3 ? .26 : .34));
+		const main = height - (rows - 1) * (lower + gap);
+		const flows = curves.flatMap((c) => c.points.map((p) => p.flow));
+		const x = scaleLinear([0, this.span(flows, { zero: true })[1]], [0, width]).nice();
+		const heads = curves.flatMap((c) => c.points.map((p) => p.head));
+		const shutoff = Math.max(1, ...heads);
+		const y = scaleLinear([0, shutoff * 1.08], [main, 0]).nice();
+		const top = ctx.nest("translate(0,0)", "head-panel");
+		this.frame(top, {
+			x,
+			y,
+			hideX: rows > 1,
+			xTitle: xLabel,
+			yTitle: yLabel
+		});
+		const at = (p) => this.within([[x(p.flow), y(p.head)]], width, main)[0];
+		if (arrangement !== "single-pump") this.traces(top, "single-curves", raw.map((c) => ({
+			key: c.speed,
+			color: ctx.palette.color(c.speed),
+			width: 1.5,
+			dash: "4 4",
+			opacity: .6,
+			curve: curveMonotoneX,
+			points: c.points.map(at)
+		})));
+		if (isoEfficiency && raw.length > 1) {
+			const lines = LEVELS.flatMap((level) => this.isolines(raw, level).map((points, side) => ({
+				key: `${level}${side}`,
+				level,
+				points: points.map((p) => [x(p[0]), y(p[1])])
+			})));
+			this.guides(top, "iso-efficiency", lines.map((line) => ({
+				...line,
+				dash: "3 3"
+			})));
+			this.annotate(top, "iso-notes", lines.filter((line) => line.points.length).map((line) => ({
+				key: line.key,
+				text: `${line.level * 100}%`,
+				x: line.points[0][0],
+				y: line.points[0][1] - 4,
+				anchor: "middle",
+				tone: "muted",
+				size: 9
+			})), {
+				width,
+				height: main
+			});
+		}
+		this.traces(top, "head-curves", curves.map((c) => ({
+			key: c.speed,
+			color: ctx.palette.color(c.speed),
+			curve: curveMonotoneX,
+			points: c.points.map(at)
+		})));
+		curves.forEach((c, i) => this.probes(top, `head-probe-${i}`, c.points, at, (p) => this.tipFor(ctx, p)));
+		const lead = curves[0];
+		if (lead) {
+			const best = lead.points.reduce((peak, p) => p.efficiency > peak.efficiency ? p : peak);
+			if (Number.isFinite(best.efficiency)) {
+				this.dots(top, "bep", [best], at, () => ctx.theme.ink, (p) => this.tipFor(ctx, p), 4.5);
+				this.annotate(top, "bep-note", [{
+					key: "b",
+					text: "BEP",
+					x: at(best)[0] + 7,
+					y: at(best)[1] - 7,
+					tone: "ink",
+					size: 10
+				}], {
+					width,
+					height: main
+				});
+			}
+			if (system) {
+				const base = staticHead ?? shutoff * .25;
+				const k = friction ?? (shutoff * .72 - base) / (x.domain()[1] * .7) ** 2;
+				const need = (flow) => base + k * flow * flow;
+				const line = Array.from({ length: 50 }, (_, i) => {
+					const flow = x.domain()[1] * i / 49;
+					return [x(flow), need(flow) <= y.domain()[1] ? y(need(flow)) : NaN];
+				});
+				this.traces(top, "system-curve", [{
+					key: "s",
+					color: ctx.theme.inkSecondary,
+					dash: "6 4",
+					points: line
+				}]);
+				const duty = this.duty(lead.points, need);
+				if (duty) {
+					this.dots(top, "duty", [duty], at, (p) => ctx.palette.color(p.speed), (p) => this.tipFor(ctx, p), 5.5);
+					this.annotate(top, "duty-note", [{
+						key: "d",
+						text: `Duty ${duty.flow.toFixed(0)} m³/h, ${duty.head.toFixed(0)} m`,
+						x: at(duty)[0] - 8,
+						y: at(duty)[1] + 16,
+						anchor: "end",
+						tone: "ink",
+						size: 10
+					}], {
+						width,
+						height: main
+					});
+				}
+			}
+		}
+		if (rows > 1) this.trend(ctx.nest(`translate(0,${main + gap})`, "efficiency-panel"), "efficiency", curves, x, lower, (p) => p.efficiency, "η", (v) => `${Math.round(v * 100)}%`, rows > 2);
+		if (rows > 2) this.trend(ctx.nest(`translate(0,${main + 16 + lower})`, "power-panel"), "power", curves, x, lower, (p) => p.power, "kW", (v) => `${v}`, false);
+	}
+};
+export { PumpArrangement, PumpCurveChart, PumpPanels };

package/dist/charts/engineering/RootLocusPlot.js

@@ -0,0 +1,135 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SPlaneChart } from "./SPlaneChart.js";
+import { TransferFunction } from "./TransferFunction.js";
+// src/charts/engineering/RootLocusPlot.ts
+var RootLocusGain = /* @__PURE__ */ function(RootLocusGain) {
+	RootLocusGain["Positive"] = "positive-gain";
+	RootLocusGain["Negative"] = "negative-gain";
+	RootLocusGain["Both"] = "both-gains";
+	return RootLocusGain;
+}({});
+var RootLocusMarks = /* @__PURE__ */ function(RootLocusMarks) {
+	RootLocusMarks["Line"] = "line";
+	RootLocusMarks["Graded"] = "graded-gain";
+	return RootLocusMarks;
+}({});
+/** Tune one gain: how a loop's closed-loop poles travel as the gain sweeps. Computed from pole-zero rows. */
+var RootLocusPlot = class extends SPlaneChart {
+	static meta = {
+		id: "root-locus-plot",
+		name: "Root locus plot",
+		family: ChartFamily.Scientific,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Traces closed-loop poles from open-loop poles to zeros as loop gain sweeps, computed from your poles and zeros.",
+		tags: [
+			"control",
+			"gain",
+			"s-plane",
+			"stability"
+		],
+		sample: (seed) => TransferFunction.demoPoles(seed),
+		variants: {
+			gainSign: [
+				"positive-gain",
+				"negative-gain",
+				"both-gains"
+			],
+			marks: ["line", "graded-gain"],
+			guides: [true, false],
+			asymptotes: [true, false],
+			crossings: [true, false]
+		},
+		valid: (v) => v.gainSign !== "negative-gain" || v.crossings === true
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			gainSign: "positive-gain",
+			marks: "line",
+			guides: true,
+			asymptotes: true,
+			crossings: true
+		};
+	}
+	branches(system, sign) {
+		const reach = Math.max(1, ...system.poles.map(([re, im]) => Math.hypot(re, im)));
+		const gains = TransferFunction.logspace(1e-4 * reach, 1e5 * reach ** Math.max(1, system.poles.length - system.zeros.length), 420).map((gain) => sign * gain);
+		const steps = system.locus(gains);
+		return system.poles.map((_, branch) => steps.map((step, i) => ({
+			branch,
+			gain: gains[i],
+			root: step[branch]
+		})));
+	}
+	draw(ctx) {
+		const { gainSign, marks, guides, asymptotes, crossings, xLabel, yLabel } = this.options;
+		const { width, height } = ctx.plot;
+		const roots = this.roots();
+		const poles = roots.filter((r) => r.kind === "pole").map((r) => [r.real, r.imaginary]);
+		const zeros = roots.filter((r) => r.kind === "zero").map((r) => [r.real, r.imaginary]);
+		const excess = poles.length - zeros.length;
+		const reach = Math.max(1, ...roots.map((r) => Math.hypot(r.real, r.imaginary))) * 1.25;
+		const { x, y } = this.equalScales(width, height, [-reach * 1.1, reach * .55], [-reach * .8, reach * .8]);
+		this.frame(ctx, {
+			x,
+			y,
+			xTitle: xLabel ?? "Re(s)",
+			yTitle: yLabel ?? "Im(s), rad/s"
+		});
+		const at = (p) => [x(p[0]), y(p[1])];
+		const system = new TransferFunction(zeros, poles);
+		const centroid = excess > 0 ? (poles.reduce((sum, p) => sum + p[0], 0) - zeros.reduce((sum, z) => sum + z[0], 0)) / excess : 0;
+		if (guides) this.guides(ctx, "damping", this.dampingGrid(reach * 1.2).map((guide) => ({
+			key: guide.key,
+			dash: "2 3",
+			points: this.within(guide.points.map(at), width, height)
+		})));
+		if (asymptotes && excess > 0) {
+			const positive = gainSign !== "negative-gain", negative = gainSign !== "positive-gain";
+			const angles = Array.from({ length: excess }, (_, k) => [positive ? (2 * k + 1) * Math.PI / excess : null, negative ? 2 * k * Math.PI / excess : null]).flat().filter((a) => a !== null);
+			this.guides(ctx, "asymptotes", angles.map((angle, i) => ({
+				key: `a${i}`,
+				dash: "6 4",
+				points: this.within(Array.from({ length: 60 }, (_, step) => at([centroid + step / 59 * reach * 2.4 * Math.cos(angle), step / 59 * reach * 2.4 * Math.sin(angle)])), width, height)
+			})));
+		}
+		const paths = (gainSign === "both-gains" ? [1, -1] : gainSign === "negative-gain" ? [-1] : [1]).flatMap((sign) => excess >= 0 && poles.length ? this.branches(system, sign) : []);
+		const keep = (p) => this.within([at(p.root)], width, height)[0];
+		this.traces(ctx, "branches", paths.map((path, i) => ({
+			key: `b${i}`,
+			dash: path[0].gain < 0 && gainSign === "both-gains" ? "5 4" : void 0,
+			color: ctx.palette.color(`Branch ${path[0].branch + 1}`),
+			opacity: marks === "graded-gain" ? .35 : void 0,
+			points: path.map(keep)
+		})));
+		const logs = paths.flat().map((p) => Math.log10(Math.abs(p.gain)));
+		const [lowest, highest] = this.span(logs);
+		const tip = (p) => ({
+			title: `Branch ${p.branch + 1}`,
+			color: ctx.palette.color(`Branch ${p.branch + 1}`),
+			rows: [
+				["Gain", p.gain.toPrecision(3)],
+				["Real", p.root[0].toFixed(3)],
+				["Imaginary", p.root[1].toFixed(3)]
+			]
+		});
+		if (marks === "graded-gain") {
+			const stride = paths.flatMap((path) => path.filter((p, i) => i % 10 === 0 && Number.isFinite(keep(p)[0])));
+			this.dots(ctx, "gain-dots", stride, keep, (p) => ctx.palette.sequential(.2 + .8 * (Math.log10(Math.abs(p.gain)) - lowest) / (highest - lowest || 1)), tip, 3.5);
+		} else paths.forEach((path, i) => this.probes(ctx, `probe-${i}`, path.filter((p) => Number.isFinite(keep(p)[0])), keep, tip));
+		if (crossings) {
+			const hits = paths.flatMap((path) => path.flatMap((p, i) => i && Math.abs(p.root[1]) > 1e-6 && path[i - 1].root[0] < 0 && p.root[0] >= 0 ? [p] : []));
+			this.dots(ctx, "stability-crossings", hits, keep, () => ctx.theme.critical, tip, 4.5);
+			this.annotate(ctx, "crossing-notes", hits.filter((p) => p.root[1] > 0).slice(0, 1).map((p) => ({
+				key: "k",
+				text: `K ${p.gain.toPrecision(3)}`,
+				x: keep(p)[0] + 8,
+				y: keep(p)[1] - 6,
+				tone: "ink"
+			})));
+		}
+		this.rootMarks(ctx, "roots", roots, (root) => at([root.real, root.imaginary]), () => ctx.theme.ink);
+	}
+};
+export { RootLocusGain, RootLocusMarks, RootLocusPlot };