Ryan Malloy
f2c18982ae
Astro/Starlight documentation at docs/ with 21 pages: - Getting started (prerequisites, Claude Code setup, first simulation) - Tutorials (filter design, Monte Carlo yield) - Reference (all 37 tools, 5 resources, 7 prompts) - Concepts (LTspice on Linux, simulation types) Docker infrastructure with dev/prod compose overlays, Caddy reverse proxy for mcltspice.warehack.ing, and Makefile targets. Includes patch for Starlight 0.37 head schema default bug.
417 lines
15 KiB
Plaintext
417 lines
15 KiB
Plaintext
---
|
|
title: Schematic and Netlist Tools
|
|
description: Read, edit, compare, and create circuit files.
|
|
---
|
|
|
|
import { Tabs, TabItem, Aside, Code } from '@astrojs/starlight/components';
|
|
|
|
Eight tools for working with LTspice `.asc` schematics, SPICE `.cir` netlists, and Touchstone S-parameter files. These cover the full lifecycle: read an existing circuit, edit component values, compare revisions, run design rule checks, build new circuits from scratch or from templates, and parse RF measurement data.
|
|
|
|
---
|
|
|
|
### read_schematic
|
|
|
|
Read and parse an LTspice `.asc` schematic file. Extracts all component instances with their symbols, values, positions, and attributes; net flag names; SPICE directives (simulation commands, `.param`, `.lib`, etc.); and wire count.
|
|
|
|
<table class="param-table">
|
|
<thead><tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
|
|
<tbody>
|
|
<tr><td>schematic_path</td><td>`str`</td><td>---</td><td>Path to the `.asc` schematic file.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
**Returns:** A dict with `version` (schematic format version), `components` (array of objects each containing `name`, `symbol`, `value`, `x`, `y`, and `attributes`), `nets` (array of net flag names), `directives` (array of SPICE directive strings), and `wire_count`.
|
|
|
|
<details>
|
|
<summary>Example</summary>
|
|
|
|
```json
|
|
{
|
|
"version": 4,
|
|
"components": [
|
|
{
|
|
"name": "R1",
|
|
"symbol": "res",
|
|
"value": "10k",
|
|
"x": 192,
|
|
"y": 128,
|
|
"attributes": {"Value": "10k"}
|
|
},
|
|
{
|
|
"name": "C1",
|
|
"symbol": "cap",
|
|
"value": "100n",
|
|
"x": 320,
|
|
"y": 128,
|
|
"attributes": {"Value": "100n"}
|
|
},
|
|
{
|
|
"name": "V1",
|
|
"symbol": "voltage",
|
|
"value": "AC 1",
|
|
"x": 64,
|
|
"y": 128,
|
|
"attributes": {"Value": "AC 1"}
|
|
}
|
|
],
|
|
"nets": ["0", "in", "out"],
|
|
"directives": [".ac dec 100 1 1meg"],
|
|
"wire_count": 8
|
|
}
|
|
```
|
|
|
|
</details>
|
|
|
|
---
|
|
|
|
### edit_component
|
|
|
|
Modify a component's value in a schematic. Parses the `.asc` file, finds the component by instance name (case-insensitive), updates its value, and writes the result. Can overwrite the original file or save to a new path.
|
|
|
|
<table class="param-table">
|
|
<thead><tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
|
|
<tbody>
|
|
<tr><td>schematic_path</td><td>`str`</td><td>---</td><td>Path to the `.asc` schematic file.</td></tr>
|
|
<tr><td>component_name</td><td>`str`</td><td>---</td><td>Instance name of the component to modify, e.g. `"R1"`, `"C2"`, `"M1"`.</td></tr>
|
|
<tr><td>new_value</td><td>`str`</td><td>---</td><td>New value string, e.g. `"10k"`, `"100n"`, `"2N7000"`.</td></tr>
|
|
<tr><td>output_path</td><td>`str | None`</td><td>`None`</td><td>Where to save the modified schematic. `None` overwrites the original.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
**Returns:** A dict with `success` (boolean), `component` (the component name), `new_value`, `output_path` (path written to), and `symbol` (the component's symbol type). On failure, returns `success: false` with an `error` message listing available component names.
|
|
|
|
<details>
|
|
<summary>Example</summary>
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"component": "R1",
|
|
"new_value": "22k",
|
|
"output_path": "/tmp/filter_modified.asc",
|
|
"symbol": "res"
|
|
}
|
|
```
|
|
|
|
</details>
|
|
|
|
---
|
|
|
|
### diff_schematics
|
|
|
|
Compare two schematics and produce a structured diff. Reports component additions, removals, and value changes; directive additions, removals, and modifications; net flag additions and removals; and wire count changes. Components are matched by instance name, so renaming a component shows up as a removal plus an addition.
|
|
|
|
<table class="param-table">
|
|
<thead><tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
|
|
<tbody>
|
|
<tr><td>schematic_a</td><td>`str`</td><td>---</td><td>Path to the "before" `.asc` file.</td></tr>
|
|
<tr><td>schematic_b</td><td>`str`</td><td>---</td><td>Path to the "after" `.asc` file.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
**Returns:** A dict with `has_changes` (boolean), `component_changes` (array of objects with `name`, `change_type` of `"added"` / `"removed"` / `"modified"`, `symbol`, `old_value`, `new_value`, `old_attributes`, `new_attributes`, and `moved`), `directive_changes` (array with `change_type`, `old_text`, `new_text`), `nets_added`, `nets_removed`, `wires_added`, `wires_removed`, and a human-readable `summary` string.
|
|
|
|
<details>
|
|
<summary>Example</summary>
|
|
|
|
```json
|
|
{
|
|
"has_changes": true,
|
|
"component_changes": [
|
|
{
|
|
"name": "R1",
|
|
"change_type": "modified",
|
|
"symbol": "res",
|
|
"old_value": "10k",
|
|
"new_value": "22k",
|
|
"old_attributes": {"Value": "10k"},
|
|
"new_attributes": {"Value": "22k"},
|
|
"moved": false
|
|
},
|
|
{
|
|
"name": "C3",
|
|
"change_type": "added",
|
|
"symbol": "cap",
|
|
"old_value": null,
|
|
"new_value": "47n",
|
|
"old_attributes": {},
|
|
"new_attributes": {"Value": "47n"},
|
|
"moved": false
|
|
}
|
|
],
|
|
"directive_changes": [
|
|
{
|
|
"change_type": "modified",
|
|
"old_text": ".tran 1m",
|
|
"new_text": ".tran 10m"
|
|
}
|
|
],
|
|
"nets_added": ["feedback"],
|
|
"nets_removed": [],
|
|
"wires_added": 3,
|
|
"wires_removed": 0,
|
|
"summary": "1 component modified:\n R1: 10k -> 22k\n1 component added: C3 (cap) = 47n\n1 directive changed: .tran 1m -> .tran 10m\n1 net added: feedback\n3 wires added"
|
|
}
|
|
```
|
|
|
|
</details>
|
|
|
|
---
|
|
|
|
### run_drc
|
|
|
|
Run design rule checks on a schematic. Parses the `.asc` file and runs seven checks against common issues that cause simulation failures or unexpected behavior. Each violation is classified as `error` (will likely prevent simulation), `warning` (may produce unexpected results), or `info` (suggestion).
|
|
|
|
Checks performed:
|
|
|
|
1. **NO_GROUND** -- Missing ground (node `0`) connection.
|
|
2. **FLOATING_NODE** -- Wire endpoint with only one connection and no flag or component nearby.
|
|
3. **NO_SIM_DIRECTIVE** -- No simulation command (`.tran`, `.ac`, `.dc`, `.op`, `.noise`, `.tf`).
|
|
4. **VSOURCE_LOOP** -- Two voltage sources connected in parallel (short circuit).
|
|
5. **MISSING_VALUE** -- Resistor, capacitor, inductor, or source with no value set.
|
|
6. **DUPLICATE_NAME** -- Two components sharing the same instance name.
|
|
7. **UNCONNECTED_COMPONENT** -- Component with no wire endpoints within one grid step of its origin.
|
|
|
|
<table class="param-table">
|
|
<thead><tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
|
|
<tbody>
|
|
<tr><td>schematic_path</td><td>`str`</td><td>---</td><td>Path to the `.asc` schematic file.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
**Returns:** A dict with `passed` (boolean --- `true` if zero errors), `checks_run` (number of checks executed), `summary` (human-readable string), `error_count`, `warning_count`, and `violations` (array of objects each containing `rule`, `severity`, `message`, `component`, and `location`).
|
|
|
|
<details>
|
|
<summary>Example</summary>
|
|
|
|
```json
|
|
{
|
|
"passed": false,
|
|
"checks_run": 7,
|
|
"summary": "DRC FAILED: 7 checks run, 1 error, 1 warning.",
|
|
"error_count": 1,
|
|
"warning_count": 1,
|
|
"violations": [
|
|
{
|
|
"rule": "NO_GROUND",
|
|
"severity": "error",
|
|
"message": "No ground node found. Every circuit needs at least one ground (0) connection.",
|
|
"component": null,
|
|
"location": null
|
|
},
|
|
{
|
|
"rule": "MISSING_VALUE",
|
|
"severity": "warning",
|
|
"message": "Resistor 'R3' has no value set.",
|
|
"component": "R3",
|
|
"location": [320, 256]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</details>
|
|
|
|
---
|
|
|
|
### create_netlist
|
|
|
|
Create a SPICE netlist programmatically and save it as a `.cir` file. Build circuits from scratch without needing the LTspice graphical editor. The resulting file can be passed directly to `simulate_netlist`.
|
|
|
|
<table class="param-table">
|
|
<thead><tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
|
|
<tbody>
|
|
<tr><td>title</td><td>`str`</td><td>---</td><td>Circuit title/description (appears as the first line of the `.cir` file).</td></tr>
|
|
<tr><td>components</td><td>`list[dict]`</td><td>---</td><td>List of component dicts. Each must have `name` (e.g. `"R1"`, `"V1"`, `"X1"`), `nodes` (list of node name strings, use `"0"` for ground), and `value` (value or model name). Optional `params` key for extra parameters.</td></tr>
|
|
<tr><td>directives</td><td>`list[str]`</td><td>---</td><td>List of SPICE directive strings, e.g. `[".tran 10m", ".meas tran vmax MAX V(out)"]`.</td></tr>
|
|
<tr><td>output_path</td><td>`str | None`</td><td>`None`</td><td>Where to save the `.cir` file. `None` saves to a temp directory with a name derived from the title.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
**Returns:** A dict with `success` (boolean), `output_path` (where the file was written), `netlist_preview` (full rendered netlist text), and `component_count`.
|
|
|
|
<details>
|
|
<summary>Example -- RC lowpass filter</summary>
|
|
|
|
Calling `create_netlist` with these arguments:
|
|
|
|
```json
|
|
{
|
|
"title": "RC Lowpass Filter",
|
|
"components": [
|
|
{"name": "V1", "nodes": ["in", "0"], "value": "AC 1"},
|
|
{"name": "R1", "nodes": ["in", "out"], "value": "1k"},
|
|
{"name": "C1", "nodes": ["out", "0"], "value": "100n"}
|
|
],
|
|
"directives": [".ac dec 100 1 1meg"]
|
|
}
|
|
```
|
|
|
|
Produces this netlist:
|
|
|
|
```text
|
|
* RC Lowpass Filter
|
|
|
|
V1 in 0 AC 1
|
|
R1 in out 1k
|
|
C1 out 0 100n
|
|
|
|
.ac dec 100 1 1meg
|
|
.backanno
|
|
.end
|
|
```
|
|
|
|
And returns:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"output_path": "/tmp/RC_Lowpass_Filter.cir",
|
|
"netlist_preview": "* RC Lowpass Filter\n\nV1 in 0 AC 1\nR1 in out 1k\nC1 out 0 100n\n\n.ac dec 100 1 1meg\n.backanno\n.end\n",
|
|
"component_count": 3
|
|
}
|
|
```
|
|
|
|
</details>
|
|
|
|
---
|
|
|
|
### create_from_template
|
|
|
|
Create a circuit netlist from a pre-built template. Each template generates a complete, ready-to-simulate `.cir` file with default component values that can be selectively overridden. All parameter values are passed as strings.
|
|
|
|
Available templates:
|
|
|
|
| Template | Description |
|
|
|---|---|
|
|
| `voltage_divider` | Resistive voltage divider with `.op` or custom analysis |
|
|
| `rc_lowpass` | RC lowpass filter with AC sweep |
|
|
| `inverting_amplifier` | Inverting op-amp (gain = -Rf/Rin), +/-15V supply |
|
|
| `non_inverting_amplifier` | Non-inverting op-amp (gain = 1 + Rf/Rin), +/-15V supply |
|
|
| `differential_amplifier` | Diff amp: Vout = (R2/R1)(V2-V1), +/-15V supply |
|
|
| `common_emitter_amplifier` | BJT common-emitter with voltage divider bias |
|
|
| `buck_converter` | Step-down DC-DC converter with MOSFET switch |
|
|
| `ldo_regulator` | LDO regulator: Vout = Vref * (1 + R1/R2) |
|
|
| `colpitts_oscillator` | LC oscillator: f ~ 1/(2 pi sqrt(L Cseries)) |
|
|
| `h_bridge` | 4-MOSFET H-bridge motor driver with dead time |
|
|
| `sallen_key_lowpass` | Sallen-Key lowpass (unity gain, 2nd order) |
|
|
| `boost_converter` | Step-up DC-DC converter with MOSFET switch |
|
|
| `instrumentation_amplifier` | 3-opamp instrumentation amp: gain = (1 + 2R1/Rgain)(R3/R2) |
|
|
| `current_mirror` | BJT current mirror with reference resistor |
|
|
| `transimpedance_amplifier` | TIA: Vout = -Iin * Rf |
|
|
|
|
<table class="param-table">
|
|
<thead><tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
|
|
<tbody>
|
|
<tr><td>template_name</td><td>`str`</td><td>---</td><td>Template name from the table above.</td></tr>
|
|
<tr><td>params</td><td>`dict[str, str] | None`</td><td>`None`</td><td>Optional parameter overrides as key-value string pairs. Use `list_templates` to see available parameters and defaults for each template.</td></tr>
|
|
<tr><td>output_path</td><td>`str | None`</td><td>`None`</td><td>Where to save the `.cir` file. `None` saves to `/tmp/<template_name>.cir`.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
**Returns:** A dict with `success` (boolean), `template` (name used), `description`, `output_path`, `netlist_preview` (full rendered netlist text), `component_count`, and `params_used` (merged defaults and overrides).
|
|
|
|
<details>
|
|
<summary>Example</summary>
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"template": "rc_lowpass",
|
|
"description": "RC lowpass filter with AC sweep",
|
|
"output_path": "/tmp/rc_lowpass.cir",
|
|
"netlist_preview": "* RC Lowpass Filter\n\nV1 in 0 AC 1\nR1 in out 4.7k\nC1 out 0 10n\n\n.ac dec 100 1 1meg\n.backanno\n.end\n",
|
|
"component_count": 3,
|
|
"params_used": {
|
|
"r": "4.7k",
|
|
"c": "10n",
|
|
"f_start": "1",
|
|
"f_stop": "1meg"
|
|
}
|
|
}
|
|
```
|
|
|
|
</details>
|
|
|
|
---
|
|
|
|
### generate_schematic
|
|
|
|
Generate an LTspice `.asc` graphical schematic file from a template. Unlike `create_from_template` which produces a text-based `.cir` netlist, this tool creates a ready-to-open `.asc` file with proper component placement, wire routing, net labels, and simulation directives. The output can be loaded directly into the LTspice GUI.
|
|
|
|
Uses the same template names and parameters as `create_from_template`.
|
|
|
|
<table class="param-table">
|
|
<thead><tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
|
|
<tbody>
|
|
<tr><td>template</td><td>`str`</td><td>---</td><td>Template name (same set as `create_from_template`).</td></tr>
|
|
<tr><td>params</td><td>`dict[str, str] | None`</td><td>`None`</td><td>Optional parameter overrides as key-value string pairs.</td></tr>
|
|
<tr><td>output_path</td><td>`str | None`</td><td>`None`</td><td>Where to save the `.asc` file. `None` saves to `/tmp/<template>.asc`.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
**Returns:** A dict with `success` (boolean), `output_path` (path to the generated `.asc` file), `template` (name used), and `schematic_preview` (first 500 characters of the rendered `.asc` content).
|
|
|
|
<details>
|
|
<summary>Example</summary>
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"output_path": "/tmp/inverting_amp.asc",
|
|
"template": "inverting_amp",
|
|
"schematic_preview": "Version 4\nSHEET 1 880 680 0\nWIRE 96 192 96 128\nWIRE 96 320 96 256\nWIRE 224 160 160 160\nWIRE 224 224 160 224\n..."
|
|
}
|
|
```
|
|
|
|
</details>
|
|
|
|
---
|
|
|
|
### read_touchstone
|
|
|
|
Parse a Touchstone (.s1p, .s2p, .snp) S-parameter file. Supports all standard format types (MA, DB, RI), all frequency units (Hz, kHz, MHz, GHz), and any port count. Frequencies are converted to Hz and S-parameters are returned in dB magnitude.
|
|
|
|
<table class="param-table">
|
|
<thead><tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
|
|
<tbody>
|
|
<tr><td>file_path</td><td>`str`</td><td>---</td><td>Path to the Touchstone file (`.s1p`, `.s2p`, `.s3p`, `.s4p`, etc.).</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
**Returns:** A dict with `filename`, `n_ports`, `n_frequencies` (number of frequency points), `freq_range_hz` (two-element array `[min, max]`), `reference_impedance` (ohms), `s_parameters` (a dict keyed by parameter name like `"S11"`, `"S21"`, each containing a `magnitude_db` array), and `comments` (first five comment lines from the file).
|
|
|
|
<details>
|
|
<summary>Example</summary>
|
|
|
|
```json
|
|
{
|
|
"filename": "filter.s2p",
|
|
"n_ports": 2,
|
|
"n_frequencies": 201,
|
|
"freq_range_hz": [100000000.0, 6000000000.0],
|
|
"reference_impedance": 50.0,
|
|
"s_parameters": {
|
|
"S11": {
|
|
"magnitude_db": [-25.3, -24.8, -23.1, "..."]
|
|
},
|
|
"S12": {
|
|
"magnitude_db": [-45.0, -44.2, -43.8, "..."]
|
|
},
|
|
"S21": {
|
|
"magnitude_db": [-0.8, -0.9, -1.2, "..."]
|
|
},
|
|
"S22": {
|
|
"magnitude_db": [-22.1, -21.5, -20.3, "..."]
|
|
}
|
|
},
|
|
"comments": [
|
|
"2-port bandpass filter measurement",
|
|
"VNA: Keysight N5222B",
|
|
"Date: 2025-01-15"
|
|
]
|
|
}
|
|
```
|
|
|
|
</details>
|