Document ammeter and multi-axis simulation graph controls

docs/elements/ammeter.mdx

@@ -0,0 +1,83 @@
+---
+title: <ammeter />
+description: Measure current through a branch during SPICE simulation.
+---
+
+## Overview
+
+`<ammeter />` 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"
+
+<CircuitPreview
+  defaultView="schematic"
+  hidePCBTab={true}
+  hide3DTab={true}
+  verticalStack={true}
+  showSimulationGraph={true}
+  code={`
+export default () => (
+  <board routingDisabled>
+    <voltagesource name="V1" voltage="15V" schX={-3} />
+    <ammeter
+      name="AM1"
+      color="#ff0000"
+      connections={{
+        pos: ".V1 > .pin1",
+        neg: ".R1 > .pin1",
+      }}
+    />
+    <resistor name="R1" resistance="10ohm" schX={3} />
+
+    <trace from=".R1 > .pin2" to=".V1 > .pin2" />
+
+    <analogsimulation
+      duration="1ms"
+      timePerStep="100us"
+      spiceEngine="ngspice"
+    />
+  </board>
+)
+`}
+/>
+
+## 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` |
+| `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 `graphDisplayName`, `graphCenter`, `graphVerticalOffset`, and
+`graphCurrentPerDiv` to override how an ammeter channel appears when an
+`<analogsimulation />` uses `graphIndependentAxes`. These props are optional:
+without them, tscircuit automatically centers and scales the current trace from
+the simulated data.
+
+`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.

docs/elements/analogsimulation.mdx

@@ -43,10 +43,67 @@ 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 `<analogsimulation />` once per `<board />` to define how the simulation
 runs. Combine it with `<voltagesource />` and `<voltageprobe />` elements to
 create and observe waveforms.
 
+## Multi-axis scope display
+
+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.
+- `graphVerticalOffset` moves that center up or down in measured units, such as
+  `"1V"` or `"1mA"`.
+- `graphVoltagePerDiv` sets volts per division for `<voltageprobe />`.
+- `graphCurrentPerDiv` sets amps per division for `<ammeter />`.
+
+<CircuitPreview
+  defaultView="schematic"
+  hidePCBTab={true}
+  hide3DTab={true}
+  verticalStack={true}
+  showSimulationGraph={true}
+  code={`
+export default () => (
+  <board routingDisabled>
+    <voltagesource name="V1" voltage="5V" schX={-4} />
+    <ammeter
+      name="IIN"
+      color="#e05a00"
+      connections={{
+        pos: ".V1 > .pin1",
+        neg: ".R_LOAD > .pin1",
+      }}
+    />
+    <resistor name="R_LOAD" resistance="1k" schX={2} />
+
+    <trace from=".R_LOAD > .pin2" to=".V1 > .pin2" />
+
+    <voltageprobe
+      name="VIN"
+      color="#315cff"
+      connectsTo=".IIN > .pos"
+      referenceTo=".V1 > .pin2"
+    />
+
+    <analogsimulation
+      duration="4ms"
+      timePerStep="1ms"
+      spiceEngine="ngspice"
+      graphIndependentAxes
+    />
+  </board>
+)
+`}
+/>
+
 For more end-to-end examples and best practices, we recommend reviewing the
 [SPICE simulation guide](/category/spice-simulation).

docs/elements/voltageprobe.mdx

@@ -47,7 +47,22 @@ 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` |
+| `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
 `connectsTo` node and the reference node.
+
+## Scope-style graph display
+
+Use the graph display props to override how a voltage probe channel appears when
+an `<analogsimulation />` uses `graphIndependentAxes`. This is useful when a
+small ripple signal and a larger supply rail share the same simulation graph.
+
+`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.