From 7419a82d3d6ad5feff13d657fe47ed78449592df Mon Sep 17 00:00:00 2001 From: ShiboSoftwareDev Date: Mon, 29 Jun 2026 17:03:10 +0200 Subject: [PATCH 1/2] Document ammeter and multi-axis simulation graph controls --- docs/elements/ammeter.mdx | 93 ++++++++++++++++++++++++++++++ docs/elements/analogsimulation.mdx | 59 +++++++++++++++++++ docs/elements/voltageprobe.mdx | 24 ++++++++ 3 files changed, 176 insertions(+) create mode 100644 docs/elements/ammeter.mdx diff --git a/docs/elements/ammeter.mdx b/docs/elements/ammeter.mdx new file mode 100644 index 00000000..2e946523 --- /dev/null +++ b/docs/elements/ammeter.mdx @@ -0,0 +1,93 @@ +--- +title: +description: Measure current through a branch during SPICE simulation. +--- + +## Overview + +`` measures current through a circuit branch during SPICE simulation. +Insert it between the two nodes of the branch you want to measure, then connect +`pos` and `neg` to define the positive current direction. + +An ammeter is primarily a schematic and simulation component. It emits a current +probe for simulation graphs. + +import CircuitPreview from "@site/src/components/CircuitPreview" + + ( + + + .pin1", + neg: ".R1 > .pin1", + }} + /> + + + + + + +) +`} +/> + +## Pins + +| Pin | Aliases | Description | +| --- | --- | --- | +| `pin1` | `pos` | Positive side of the current measurement. | +| `pin2` | `neg` | Negative side of the current measurement. | + +Positive current is measured entering `pos` and leaving `neg`. Reverse the +connections if the plotted current has the opposite sign from the direction you +want. + +## Properties + +| Property | Description | Example | +| --- | --- | --- | +| `name` | Label for the ammeter and its current trace. | `"AM1"` | +| `connections` | Connects the ammeter in series. Use either `pos`/`neg` or `pin1`/`pin2`. | `{{ pos: ".V1 > .pin1", neg: ".R1 > .pin1" }}` | +| `color` | Color used for the current trace in simulation graphs. | `"#ff0000"` | +| `graphDisplayName` | Optional label for oscilloscope-style graph display. | `"I_LOAD"` | +| `graphCenter` | Current value shown at the center of the trace display. | `0.01` | +| `graphOffsetDivs` | Vertical offset, in divisions, applied to the trace center. | `-1` | +| `graphUnitsPerDiv` | Current scale per division. For ammeters this is amps per division. | `0.005` | +| `footprint` | Optional footprint. Required if you position the ammeter on the PCB. | `"0402"` | + +## Scope-style graph display + +Use `graphCenter`, `graphOffsetDivs`, and `graphUnitsPerDiv` when plotting +multiple current and voltage signals on the same simulation graph. These props +scale the ammeter trace independently from voltage probes, so current can be +shown in amps per division while voltage probes use volts per division. + +```tsx + .pin2", + neg: ".V1 > .pin2", + }} +/> +``` diff --git a/docs/elements/analogsimulation.mdx b/docs/elements/analogsimulation.mdx index 9b09dae3..39afaaf9 100644 --- a/docs/elements/analogsimulation.mdx +++ b/docs/elements/analogsimulation.mdx @@ -48,5 +48,64 @@ Use `` once per `` to define how the simulation runs. Combine it with `` and `` elements to create and observe waveforms. +## Multi-axis scope display + +Simulation graphs can show multiple voltage and current channels on separate +colored value axes. Set graph display props on each `` or +`` channel: + +- `graphDisplayName` sets the channel label. +- `graphCenter` sets the measured voltage or current value at the channel center. +- `graphOffsetDivs` moves that center up or down by graph divisions. +- `graphUnitsPerDiv` sets the channel scale. Voltage probes use volts per + division. Ammeters use amps per division. + + ( + + + .pin1", + neg: ".R_LOAD > .pin1", + }} + /> + + + + + + + + +) +`} +/> + For more end-to-end examples and best practices, we recommend reviewing the [SPICE simulation guide](/category/spice-simulation). diff --git a/docs/elements/voltageprobe.mdx b/docs/elements/voltageprobe.mdx index c6281a57..0fc48852 100644 --- a/docs/elements/voltageprobe.mdx +++ b/docs/elements/voltageprobe.mdx @@ -47,7 +47,31 @@ export default () => ( | `name` | Optional label for the probe trace in graphs. | `"VP_OUT"` | | `connectsTo` | Port selector that identifies the measurement node. | `".R1 > .pin1"` | | `referenceTo` | Optional port selector for differential measurements. | `".R1 > .pin2"` | +| `color` | Color used for the voltage trace in simulation graphs. | `"#315cff"` | +| `graphDisplayName` | Optional label for oscilloscope-style graph display. | `"VOUT"` | +| `graphCenter` | Voltage value shown at the center of the trace display. | `3.3` | +| `graphOffsetDivs` | Vertical offset, in divisions, applied to the trace center. | `2` | +| `graphUnitsPerDiv` | Voltage scale per division. For voltage probes this is volts per division. | `0.1` | Add probes for every signal you want plotted in the simulation graph. When you provide `referenceTo`, the probe measures the voltage difference between the `connectsTo` node and the reference node. + +## Scope-style graph display + +Use the graph display props when several probes need different vertical scales. +This is useful when a small ripple signal and a larger supply rail share the same +simulation graph. + +```tsx + +``` \ No newline at end of file From 6aa37baf24803ab6d5c4533921abdf5f8700fcd0 Mon Sep 17 00:00:00 2001 From: ShiboSoftwareDev Date: Tue, 30 Jun 2026 10:45:10 +0200 Subject: [PATCH 2/2] new props --- docs/elements/ammeter.mdx | 30 ++++++++++-------------------- docs/elements/analogsimulation.mdx | 26 ++++++++++++-------------- docs/elements/voltageprobe.mdx | 25 ++++++++----------------- 3 files changed, 30 insertions(+), 51 deletions(-) diff --git a/docs/elements/ammeter.mdx b/docs/elements/ammeter.mdx index 2e946523..7f9eee72 100644 --- a/docs/elements/ammeter.mdx +++ b/docs/elements/ammeter.mdx @@ -66,28 +66,18 @@ want. | `color` | Color used for the current trace in simulation graphs. | `"#ff0000"` | | `graphDisplayName` | Optional label for oscilloscope-style graph display. | `"I_LOAD"` | | `graphCenter` | Current value shown at the center of the trace display. | `0.01` | -| `graphOffsetDivs` | Vertical offset, in divisions, applied to the trace center. | `-1` | -| `graphUnitsPerDiv` | Current scale per division. For ammeters this is amps per division. | `0.005` | +| `graphVerticalOffset` | Vertical offset from the graph center. Accepts numbers or SI-prefixed strings. | `"1mA"` | +| `graphCurrentPerDiv` | Current scale per division. Accepts numbers or SI-prefixed strings. | `"2mA"` | | `footprint` | Optional footprint. Required if you position the ammeter on the PCB. | `"0402"` | ## Scope-style graph display -Use `graphCenter`, `graphOffsetDivs`, and `graphUnitsPerDiv` when plotting -multiple current and voltage signals on the same simulation graph. These props -scale the ammeter trace independently from voltage probes, so current can be -shown in amps per division while voltage probes use volts per division. +Use `graphDisplayName`, `graphCenter`, `graphVerticalOffset`, and +`graphCurrentPerDiv` to override how an ammeter channel appears when an +`` uses `graphIndependentAxes`. These props are optional: +without them, tscircuit automatically centers and scales the current trace from +the simulated data. -```tsx - .pin2", - neg: ".V1 > .pin2", - }} -/> -``` +`graphVerticalOffset` is expressed in current units, not divisions. For example, +`graphVerticalOffset="1mA"` with `graphCurrentPerDiv="2mA"` places the trace +center half a division away from the axis center. diff --git a/docs/elements/analogsimulation.mdx b/docs/elements/analogsimulation.mdx index 39afaaf9..4bc4ceba 100644 --- a/docs/elements/analogsimulation.mdx +++ b/docs/elements/analogsimulation.mdx @@ -43,6 +43,7 @@ export default () => ( | `duration` | Total simulation time. Accepts numbers or time strings. | `"10ms"` | | `timePerStep` | Time interval between simulation steps. | `"0.1ms"` | | `spiceEngine` | SPICE engine to use. Typically `"ngspice"` or `"spicey"`. | `"ngspice"` | +| `graphIndependentAxes` | Give each voltage or current graph channel its own automatically scaled axis. | `true` | Use `` once per `` to define how the simulation runs. Combine it with `` and `` elements to @@ -50,15 +51,19 @@ create and observe waveforms. ## Multi-axis scope display -Simulation graphs can show multiple voltage and current channels on separate -colored value axes. Set graph display props on each `` or -`` channel: +Use `graphIndependentAxes` when a simulation graph contains signals with +different units or very different ranges. tscircuit creates one colored axis per +voltage or current channel and automatically chooses the center, offset, and +scale from the simulated data. + +You can optionally override a channel's display on the probe itself: - `graphDisplayName` sets the channel label. - `graphCenter` sets the measured voltage or current value at the channel center. -- `graphOffsetDivs` moves that center up or down by graph divisions. -- `graphUnitsPerDiv` sets the channel scale. Voltage probes use volts per - division. Ammeters use amps per division. +- `graphVerticalOffset` moves that center up or down in measured units, such as + `"1V"` or `"1mA"`. +- `graphVoltagePerDiv` sets volts per division for ``. +- `graphCurrentPerDiv` sets amps per division for ``. ( .pin1", neg: ".R_LOAD > .pin1", @@ -91,16 +92,13 @@ export default () => ( color="#315cff" connectsTo=".IIN > .pos" referenceTo=".V1 > .pin2" - graphDisplayName="VIN" - graphCenter={5} - graphOffsetDivs={-1} - graphUnitsPerDiv={0.5} /> ) diff --git a/docs/elements/voltageprobe.mdx b/docs/elements/voltageprobe.mdx index 0fc48852..ee242e30 100644 --- a/docs/elements/voltageprobe.mdx +++ b/docs/elements/voltageprobe.mdx @@ -50,8 +50,8 @@ export default () => ( | `color` | Color used for the voltage trace in simulation graphs. | `"#315cff"` | | `graphDisplayName` | Optional label for oscilloscope-style graph display. | `"VOUT"` | | `graphCenter` | Voltage value shown at the center of the trace display. | `3.3` | -| `graphOffsetDivs` | Vertical offset, in divisions, applied to the trace center. | `2` | -| `graphUnitsPerDiv` | Voltage scale per division. For voltage probes this is volts per division. | `0.1` | +| `graphVerticalOffset` | Vertical offset from the graph center. Accepts numbers or SI-prefixed strings. | `"1V"` | +| `graphVoltagePerDiv` | Voltage scale per division. Accepts numbers or SI-prefixed strings. | `"500mV"` | Add probes for every signal you want plotted in the simulation graph. When you provide `referenceTo`, the probe measures the voltage difference between the @@ -59,19 +59,10 @@ provide `referenceTo`, the probe measures the voltage difference between the ## Scope-style graph display -Use the graph display props when several probes need different vertical scales. -This is useful when a small ripple signal and a larger supply rail share the same -simulation graph. +Use the graph display props to override how a voltage probe channel appears when +an `` uses `graphIndependentAxes`. This is useful when a +small ripple signal and a larger supply rail share the same simulation graph. -```tsx - -``` \ No newline at end of file +`graphVerticalOffset` is expressed in voltage units, not divisions. For example, +`graphVerticalOffset="1V"` with `graphVoltagePerDiv="500mV"` places the trace +center two divisions away from the axis center.