@mstone6969/graph 0.0.0-stage → 0.2.0

package/dist/charts/engineering/NyquistHelix3D.js

@@ -0,0 +1,149 @@
+import { Chart3D } from "../../core/Chart3D.js";
+import { ChartFamily, DataShape, Dimension, ScaleKind } from "../../core/enums.js";
+import { TransferFunction } from "./TransferFunction.js";
+import { scaleLinear, scaleLog } from "d3";
+import { BufferGeometry, CatmullRomCurve3, DoubleSide, Float32BufferAttribute, Line, LineBasicMaterial, Mesh, MeshStandardMaterial, PlaneGeometry, TorusGeometry, TubeGeometry, Vector3 } from "three";
+// src/charts/engineering/NyquistHelix3D.ts
+/** Keep the frequency a Nyquist plot hides: the complex response stretched along a frequency axis. */
+var NyquistHelix3D = class extends Chart3D {
+	static meta = {
+		id: "nyquist-helix-3d",
+		name: "Nyquist helix",
+		family: ChartFamily.Scientific,
+		dimension: Dimension.Three,
+		shape: DataShape.Table,
+		description: "Unrolls a complex frequency response along a frequency axis, linking the Nyquist and Bode views.",
+		tags: [
+			"control",
+			"frequency response",
+			"complex",
+			"nyquist"
+		],
+		sample: (seed) => TransferFunction.demoResponse(seed),
+		variants: {
+			frequencyScale: [ScaleKind.Log, ScaleKind.Linear],
+			tube: [true, false],
+			projection: [true, false],
+			rings: [true, false]
+		}
+	};
+	defaults() {
+		return {
+			frequency: "frequency",
+			magnitude: "magnitude",
+			phase: "phase",
+			system: "system",
+			frequencyScale: ScaleKind.Log,
+			tube: true,
+			projection: true,
+			rings: true,
+			azimuth: 58,
+			elevation: 20
+		};
+	}
+	build(ctx) {
+		const { frequency, magnitude, phase, system, frequencyScale, tube, projection, rings } = this.options;
+		const parts = (Array.isArray(this.options.data) ? this.options.data : []).map((row) => {
+			const size = 10 ** (+row[magnitude] / 20), angle = +row[phase] * Math.PI / 180;
+			return {
+				name: String(row[system] ?? "System"),
+				w: +row[frequency],
+				re: size * Math.cos(angle),
+				im: size * Math.sin(angle)
+			};
+		}).filter((p) => p.w > 0 && Number.isFinite(p.re) && Number.isFinite(p.im));
+		if (!parts.length) {
+			ctx.label("No data", [
+				0,
+				0,
+				0
+			], "muted");
+			return;
+		}
+		const log = frequencyScale === ScaleKind.Log;
+		const lowest = Math.min(...parts.map((p) => p.w)), highest = Math.max(...parts.map((p) => p.w));
+		const along = log ? scaleLog([lowest, highest], [-1, 1]) : scaleLinear([0, highest / 10], [-1, 1]).clamp(true);
+		const [reLow, reHigh] = [Math.min(0, ...parts.map((p) => p.re)), Math.max(0, ...parts.map((p) => p.re))];
+		const [imLow, imHigh] = [Math.min(0, ...parts.map((p) => p.im)), Math.max(0, ...parts.map((p) => p.im))];
+		const scale = 1.84 / Math.max(1, reHigh - reLow, imHigh - imLow);
+		const midRe = (reLow + reHigh) / 2, midIm = (imLow + imHigh) / 2;
+		const place = (p) => new Vector3(along(p.w), (p.im - midIm) * scale, (p.re - midRe) * scale);
+		const names = [...new Set(parts.map((p) => p.name))];
+		const seen = parts.filter((p) => log || p.w <= highest / 10);
+		for (const name of names) {
+			const color = ctx.color(ctx.palette.color(name));
+			const points = seen.filter((p) => p.name === name).map(place);
+			if (points.length < 2) continue;
+			const body = new Mesh(new TubeGeometry(new CatmullRomCurve3(points), 320, tube ? .026 : .009, 10), new MeshStandardMaterial({
+				color,
+				roughness: .4
+			}));
+			body.castShadow = true;
+			const draw = body.geometry;
+			ctx.reveal((progress) => draw.setDrawRange(0, Math.ceil(progress * draw.index.count)));
+			ctx.root.add(body);
+			ctx.pick(body, () => ({
+				title: name,
+				color: ctx.palette.color(name),
+				rows: [["Samples", points.length]]
+			}));
+			if (projection) {
+				const shadow = new BufferGeometry();
+				shadow.setAttribute("position", new Float32BufferAttribute(points.flatMap((p) => [
+					-1.02,
+					p.y,
+					p.z
+				]), 3));
+				ctx.root.add(new Line(shadow, new LineBasicMaterial({
+					color,
+					transparent: true,
+					opacity: .7
+				})));
+			}
+		}
+		const axis = new Mesh(new TubeGeometry(new CatmullRomCurve3([new Vector3(-1, -midIm * scale, -midRe * scale), new Vector3(1, -midIm * scale, -midRe * scale)]), 1, .006, 6), new MeshStandardMaterial({ color: ctx.theme.axis }));
+		ctx.root.add(axis);
+		if (projection) {
+			const wall = new Mesh(new PlaneGeometry(1.9, 1.9), new MeshStandardMaterial({
+				color: ctx.theme.grid,
+				side: DoubleSide,
+				transparent: true,
+				opacity: .45
+			}));
+			wall.rotation.y = Math.PI / 2;
+			wall.position.x = -1.03;
+			ctx.root.add(wall);
+		}
+		if (rings) {
+			const ticks = log ? along.ticks(4).filter((w) => Math.log10(w) % 1 === 0) : along.ticks(4);
+			const material = new MeshStandardMaterial({ color: ctx.theme.axis });
+			for (const w of ticks) {
+				const ring = new Mesh(new TorusGeometry(scale, .004, 8, 96), material);
+				ring.rotation.y = Math.PI / 2;
+				ring.position.set(along(w), -midIm * scale, -midRe * scale);
+				ctx.root.add(ring);
+				ctx.label(`${w}`, [
+					along(w),
+					-.86,
+					0
+				], "muted", 10);
+			}
+		}
+		ctx.label("Frequency", [
+			0,
+			-.98,
+			.4
+		], "secondary");
+		ctx.label("Re", [
+			-1.05,
+			0,
+			.92
+		], "secondary");
+		ctx.label("Im", [
+			-1.05,
+			.92,
+			0
+		], "secondary");
+	}
+};
+export { NyquistHelix3D };

package/dist/charts/engineering/NyquistPlot.js

@@ -0,0 +1,201 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { FrequencyResponseChart } from "./FrequencyResponseChart.js";
+import { TransferFunction } from "./TransferFunction.js";
+// src/charts/engineering/NyquistPlot.ts
+var NyquistContour = /* @__PURE__ */ function(NyquistContour) {
+	NyquistContour["Positive"] = "positive-frequency";
+	NyquistContour["Full"] = "full-contour";
+	return NyquistContour;
+}({});
+var NyquistGuide = /* @__PURE__ */ function(NyquistGuide) {
+	NyquistGuide["None"] = "plain";
+	NyquistGuide["UnitCircle"] = "unit-circle";
+	NyquistGuide["MCircles"] = "m-circles";
+	return NyquistGuide;
+}({});
+var NyquistRadius = /* @__PURE__ */ function(NyquistRadius) {
+	NyquistRadius["Linear"] = "linear-radius";
+	NyquistRadius["Compressed"] = "compressed-radius";
+	return NyquistRadius;
+}({});
+var M_LEVELS = [
+	.5,
+	.7,
+	1.4,
+	2,
+	4
+];
+var circle = (cx, cy, r) => Array.from({ length: 121 }, (_, i) => [cx + r * Math.cos(i * Math.PI / 60), cy + r * Math.sin(i * Math.PI / 60)]);
+/** Judge closed-loop stability from how the open-loop response encircles -1. */
+var NyquistPlot = class extends FrequencyResponseChart {
+	static meta = {
+		id: "nyquist-plot",
+		name: "Nyquist plot",
+		family: ChartFamily.Scientific,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Traces a frequency response on the complex plane to test stability around the critical point.",
+		tags: [
+			"control",
+			"stability",
+			"polar plot",
+			"complex plane"
+		],
+		sample: (seed) => TransferFunction.demoResponse(seed),
+		variants: {
+			contour: ["positive-frequency", "full-contour"],
+			guide: [
+				"unit-circle",
+				"plain",
+				"m-circles"
+			],
+			radius: ["linear-radius", "compressed-radius"],
+			arrows: [true, false]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			contour: "positive-frequency",
+			guide: "unit-circle",
+			radius: "linear-radius",
+			arrows: true
+		};
+	}
+	project = ([re, im]) => {
+		if (this.options.radius !== "compressed-radius") return [re, im];
+		const r = Math.hypot(re, im);
+		return r ? [re / r * Math.log1p(r), im / r * Math.log1p(r)] : [0, 0];
+	};
+	draw(ctx) {
+		const { contour, guide, radius, arrows, xLabel, yLabel } = this.options;
+		const { width, height } = ctx.plot;
+		const full = contour === "full-contour";
+		const compressed = radius === "compressed-radius";
+		const loops = this.responses().map((loop) => ({
+			...loop,
+			path: loop.points.map((p) => {
+				const r = 10 ** (p.magnitude / 20), a = p.phase * Math.PI / 180;
+				return this.project([r * Math.cos(a), r * Math.sin(a)]);
+			})
+		}));
+		const all = [
+			...loops.flatMap((l) => l.path),
+			this.project([-1.15, 0]),
+			this.project([0, full ? 1 : 0])
+		];
+		const reach = this.span(all.flatMap((p) => [Math.abs(p[1])]), { pad: .1 })[1];
+		const { x, y } = this.equalScales(width, height, this.span(all.map((p) => p[0]), { pad: .08 }), [Math.min(...all.map((p) => p[1])) * 1.1, full ? reach : Math.max(.2, ...all.map((p) => p[1])) * 1.1]);
+		const at = (p) => [x(p[0]), y(p[1])];
+		const labelled = [
+			1,
+			10,
+			100
+		].flatMap((v) => [-v, v]).concat(0).map((v) => this.project([v, 0])[0]).sort((a, b) => a - b);
+		const shown = (scale) => labelled.filter((v) => v >= scale.domain()[0] && v <= scale.domain()[1]);
+		const undo = (v) => Math.sign(v) * Math.expm1(Math.abs(v));
+		this.frame(ctx, {
+			x,
+			y,
+			xTitle: xLabel ?? "Real",
+			yTitle: yLabel ?? "Imaginary",
+			...compressed ? {
+				xValues: shown(x),
+				yValues: shown(y),
+				xFormat: (v) => (+undo(v).toPrecision(2)).toString(),
+				yFormat: (v) => (+undo(v).toPrecision(2)).toString()
+			} : {}
+		});
+		if (guide === "unit-circle") this.guides(ctx, "unit-circle", [{
+			key: "unit",
+			dash: "4 4",
+			points: this.within(circle(0, 0, 1).map((p) => at(this.project(p))), width, height)
+		}]);
+		if (guide === "m-circles") {
+			const rings = M_LEVELS.map((m) => ({
+				key: `m${m}`,
+				m,
+				points: this.within(circle(-m * m / (m * m - 1), 0, m / Math.abs(m * m - 1)).map((p) => at(this.project(p))), width, height)
+			}));
+			this.guides(ctx, "m-circles", [...rings, {
+				key: "unity",
+				dash: "4 4",
+				points: this.within(Array.from({ length: 81 }, (_, i) => at(this.project([-.5, (i - 40) * .25]))), width, height)
+			}]);
+			const unit = at(this.project([-1, 0]));
+			this.annotate(ctx, "m-notes", rings.flatMap((ring) => {
+				const top = ring.points.filter((p) => Number.isFinite(p[0])).sort((a, b) => a[1] - b[1])[0];
+				return top && !(Math.abs(top[0] - unit[0]) < 36 && Math.abs(top[1] - unit[1]) < 22) ? [{
+					key: ring.key,
+					text: `${(20 * Math.log10(ring.m)).toFixed(0)} dB`,
+					x: top[0],
+					y: top[1] - 3,
+					anchor: "middle",
+					tone: "muted",
+					size: 10
+				}] : [];
+			}));
+		}
+		if (full) this.traces(ctx, "mirror", loops.map((loop) => ({
+			key: loop.system,
+			color: ctx.palette.color(loop.system),
+			dash: "5 4",
+			points: loop.path.map((p) => at([p[0], -p[1]]))
+		})));
+		this.traces(ctx, "curves", loops.map((loop) => ({
+			key: loop.system,
+			color: ctx.palette.color(loop.system),
+			points: loop.path.map(at)
+		})));
+		if (arrows) this.shapes(ctx, "arrows", loops.flatMap((loop) => {
+			const pixels = loop.path.map(at);
+			const lengths = pixels.map((p, i) => i ? Math.hypot(p[0] - pixels[i - 1][0], p[1] - pixels[i - 1][1]) : 0);
+			const total = lengths.reduce((sum, length) => sum + length, 0);
+			let walked = 0;
+			const seats = [
+				.3,
+				.6,
+				.8
+			].map((share) => pixels.findIndex((_, i) => (walked += lengths[i]) >= share * total && (walked = 0, true)));
+			walked = 0;
+			return seats.filter((i) => i > 0).map((i) => ({
+				key: `${loop.system}${i}`,
+				fill: ctx.palette.color(loop.system),
+				d: this.arrowhead(pixels[i], Math.atan2(pixels[i][1] - pixels[i - 1][1], pixels[i][0] - pixels[i - 1][0]))
+			}));
+		}));
+		const critical = at(this.project([-1, 0]));
+		this.traces(ctx, "critical", [{
+			key: "x",
+			color: ctx.theme.critical,
+			points: [
+				[critical[0] - 5, critical[1] - 5],
+				[critical[0] + 5, critical[1] + 5],
+				[NaN, 0],
+				[critical[0] - 5, critical[1] + 5],
+				[critical[0] + 5, critical[1] - 5]
+			]
+		}]);
+		this.annotate(ctx, "critical-note", [{
+			key: "c",
+			text: "−1",
+			x: critical[0] - 8,
+			y: critical[1] - 7,
+			anchor: "end",
+			tone: "ink"
+		}]);
+		loops.forEach((loop, i) => this.probes(ctx, `probe-${i}`, loop.points.map((p, j) => ({
+			...p,
+			seat: at(loop.path[j])
+		})), (d) => d.seat, (d) => ({
+			title: d.system,
+			color: ctx.palette.color(d.system),
+			rows: [
+				["Frequency", d.frequency.toPrecision(3)],
+				["Gain", `${d.magnitude.toFixed(1)} dB`],
+				["Phase", `${d.phase.toFixed(1)}°`]
+			]
+		})));
+	}
+};
+export { NyquistContour, NyquistGuide, NyquistPlot, NyquistRadius };

package/dist/charts/engineering/PoleZeroPlot.js

@@ -0,0 +1,148 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { ComplexMath } from "./ComplexMath.js";
+import { SPlaneChart } from "./SPlaneChart.js";
+import { TransferFunction } from "./TransferFunction.js";
+// src/charts/engineering/PoleZeroPlot.ts
+var PoleZeroPlane = /* @__PURE__ */ function(PoleZeroPlane) {
+	/** Continuous rows, drawn on the s-plane. */
+	PoleZeroPlane["Laplace"] = "s-plane";
+	/** Continuous rows mapped to the z-plane by `exp(sT)`. */
+	PoleZeroPlane["Matched"] = "z-matched";
+	/** Continuous rows mapped to the z-plane by the bilinear transform. */
+	PoleZeroPlane["Bilinear"] = "z-bilinear";
+	/** Rows that are already discrete-time. */
+	PoleZeroPlane["Discrete"] = "z-plane";
+	return PoleZeroPlane;
+}({});
+/** Read stability and damping off where a system's poles and zeros sit. */
+var PoleZeroPlot = class extends SPlaneChart {
+	static meta = {
+		id: "pole-zero-plot",
+		name: "Pole-zero plot",
+		family: ChartFamily.Scientific,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Places the poles and zeros of a system on the s-plane or z-plane to show stability and damping.",
+		tags: [
+			"control",
+			"dsp",
+			"s-plane",
+			"z-plane",
+			"stability"
+		],
+		sample: (seed) => TransferFunction.demoPoles(seed),
+		variants: {
+			plane: [
+				"s-plane",
+				"z-matched",
+				"z-bilinear",
+				"z-plane"
+			],
+			guides: [true, false],
+			stability: [true, false],
+			upperHalf: [false, true],
+			pairs: [false, true]
+		},
+		valid: ({ upperHalf, pairs }) => !(upperHalf && pairs)
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			plane: "s-plane",
+			guides: true,
+			stability: true,
+			upperHalf: false,
+			pairs: false
+		};
+	}
+	matched(period) {
+		return ([re, im]) => ComplexMath.polar(Math.exp(re * period), im * period);
+	}
+	mapper(roots) {
+		const { plane, samplePeriod } = this.options;
+		const fastest = Math.max(1e-6, ...roots.map((root) => Math.hypot(root.real, root.imaginary)));
+		const period = samplePeriod ?? 1 / fastest;
+		if (plane === "z-matched") return this.matched(period);
+		if (plane === "z-bilinear") return ([re, im]) => ComplexMath.div([1 + re * period / 2, im * period / 2], [1 - re * period / 2, -im * period / 2]);
+		return (s) => s;
+	}
+	draw(ctx) {
+		const { plane, guides, stability, upperHalf, pairs, xLabel, yLabel } = this.options;
+		const { width, height } = ctx.plot;
+		const roots = this.roots();
+		const discrete = plane !== "s-plane";
+		const map = this.mapper(roots);
+		const placed = roots.map((root) => map([root.real, root.imaginary]));
+		const shown = upperHalf ? placed.filter((p) => p[1] >= -1e-9) : placed;
+		const reach = discrete ? Math.max(1.15, ...shown.flatMap((p) => [Math.abs(p[0]), Math.abs(p[1])]).map((v) => v * 1.1)) : 0;
+		const xs = this.span([...shown.map((p) => p[0]), ...discrete ? [] : [.5]], {
+			pad: .14,
+			zero: true
+		});
+		const top = Math.max(...shown.map((p) => p[1]), .5);
+		const bottom = upperHalf ? 0 : Math.min(...shown.map((p) => p[1]), -.5);
+		const { x, y } = this.equalScales(width, height, discrete ? [-reach, reach] : xs, discrete ? [upperHalf ? -.02 : -reach, reach] : [bottom * 1.2, top * 1.2]);
+		const at = (p) => [x(p[0]), y(p[1])];
+		const left = x.domain()[0];
+		const ring = (radius) => Array.from({ length: 145 }, (_, i) => at(ComplexMath.polar(radius, i * Math.PI / 72)));
+		this.frame(ctx, {
+			x,
+			y,
+			xTitle: xLabel ?? (discrete ? "Re(z)" : "Re(s)"),
+			yTitle: yLabel ?? (discrete ? "Im(z)" : "Im(s), rad/s")
+		});
+		if (stability) {
+			const disc = (upperHalf ? ring(1).slice(0, 73) : ring(1)).map((p) => p.join(",")).join("L");
+			this.shapes(ctx, "stable-region", [{
+				key: "stable",
+				fill: ctx.theme.good,
+				opacity: .09,
+				d: discrete ? `M${disc}Z` : `M0,0H${x(0)}V${height}H0Z`
+			}]);
+		}
+		if (discrete) this.guides(ctx, "unit-circle", [{
+			key: "unit",
+			points: this.within(ring(1), width, height)
+		}]);
+		if (guides) {
+			const onZ = plane === "z-plane";
+			const period = onZ ? 1 : Math.max(...roots.map((root) => Math.hypot(root.real, root.imaginary)), 1);
+			const trace = onZ ? this.matched(1) : map;
+			const traced = this.dampingGrid(discrete ? period * 3 : Math.max(-left, y.domain()[1]) * 1.3).map((guide) => ({
+				...guide,
+				dash: "2 3",
+				points: this.within(guide.points.map((p) => at(trace(p))), width, height)
+			}));
+			this.guides(ctx, "damping", traced);
+			this.annotate(ctx, "damping-notes", traced.filter((g) => g.label).flatMap((g) => {
+				const seat = [...g.points].reverse().find((p) => Number.isFinite(p[0]));
+				return seat ? [{
+					key: g.key,
+					text: g.label,
+					x: seat[0],
+					y: seat[1] + 11,
+					tone: "muted",
+					size: 9
+				}] : [];
+			}));
+		}
+		const seat = new Map(roots.map((root, i) => [root, at(placed[i])]));
+		if (pairs) {
+			const links = roots.flatMap((root) => {
+				const twin = root.imaginary > 1e-6 ? roots.find((other) => other.kind === root.kind && other.system === root.system && Math.abs(other.real - root.real) < 1e-6 && Math.abs(other.imaginary + root.imaginary) < 1e-6) : void 0;
+				return twin ? [
+					seat.get(root),
+					seat.get(twin),
+					[NaN, NaN]
+				] : [];
+			});
+			this.guides(ctx, "conjugate-pairs", [{
+				key: "pairs",
+				dash: "3 3",
+				points: links
+			}]);
+		}
+		this.rootMarks(ctx, "roots", upperHalf ? roots.filter((_, i) => placed[i][1] >= -1e-9) : roots, (root) => seat.get(root));
+	}
+};
+export { PoleZeroPlane, PoleZeroPlot };