Simulation Tools

simulate

Run an LTspice simulation on a schematic file. Executes any simulation directives (.tran, .ac, .dc, .op, etc.) found in the schematic. Returns available signal names and the path to the .raw file for waveform extraction.

Parameter	Type	Default	Description
schematic_path	`str`	---	Absolute path to an `.asc` schematic file.
timeout_seconds	`float`	`300`	Maximum time in seconds to wait for the simulation to finish.

Returns: A dict containing success (bool), elapsed_seconds, error (str or null), variables (list of name/type pairs), points (total data points), plotname (analysis type string), raw_file (path to the binary .raw file), and optionally measurements and log_errors parsed from the LTspice log.

Example

{
  "success": true,
  "elapsed_seconds": 1.42,
  "error": null,
  "variables": [
    { "name": "time", "type": "time" },
    { "name": "V(out)", "type": "voltage" },
    { "name": "I(R1)", "type": "device_current" }
  ],
  "points": 8192,
  "plotname": "Transient Analysis",
  "raw_file": "/tmp/ltspice/my_circuit.raw"
}

simulate_netlist

Run an LTspice simulation on a netlist file (.cir or .net). Functionally identical to simulate, but accepts a text-based netlist instead of a graphical schematic.

Parameter	Type	Default	Description
netlist_path	`str`	---	Absolute path to a `.cir` or `.net` netlist file.
timeout_seconds	`float`	`300`	Maximum time in seconds to wait for the simulation to finish.

Returns: Same structure as simulate --- success, elapsed_seconds, error, variables, points, raw_file, and optional measurements / log_errors.

Example

{
  "success": true,
  "elapsed_seconds": 0.87,
  "error": null,
  "variables": [
    { "name": "frequency", "type": "frequency" },
    { "name": "V(out)", "type": "voltage" }
  ],
  "points": 801,
  "raw_file": "/tmp/ltspice/bandpass.raw"
}

parameter_sweep

Sweep a parameter across a range of values. Runs multiple simulations, substituting the parameter value each time. The netlist should contain a .param directive for the parameter being swept.

Parameter	Type	Default	Description
netlist_text	`str`	---	Complete netlist text containing a `.param` directive for the target parameter.
param_name	`str`	---	Name of the parameter to sweep (e.g., `"Rval"`).
start	`float`	---	Start value of the sweep range.
stop	`float`	---	Stop value of the sweep range.
num_points	`int`	`10`	Number of linearly spaced sweep points.
timeout_seconds	`float`	`300`	Per-simulation timeout in seconds.

Returns: A dict with success_count, failure_count, total_elapsed (seconds), parameter_values (list of swept values), and raw_files (list of .raw file paths, one per sweep point --- null for failed runs).

Example

{
  "success_count": 10,
  "failure_count": 0,
  "total_elapsed": 12.5,
  "parameter_values": [100, 200, 300, 400, 500, 600, 700, 800, 900, 1000],
  "raw_files": [
    "/tmp/ltspice/sweep_0.raw",
    "/tmp/ltspice/sweep_1.raw",
    "/tmp/ltspice/sweep_2.raw",
    "/tmp/ltspice/sweep_3.raw",
    "/tmp/ltspice/sweep_4.raw",
    "/tmp/ltspice/sweep_5.raw",
    "/tmp/ltspice/sweep_6.raw",
    "/tmp/ltspice/sweep_7.raw",
    "/tmp/ltspice/sweep_8.raw",
    "/tmp/ltspice/sweep_9.raw"
  ]
}

temperature_sweep

Run simulations at different temperatures. Each temperature produces an independent simulation run with its own .raw file, letting you compare temperature-dependent behavior across the range.

Parameter	Type	Default	Description
netlist_text	`str`	---	Complete netlist text.
temperatures	`list[float]`	---	List of temperatures in degrees Celsius (e.g., `[-40, 25, 85, 125]`).
timeout_seconds	`float`	`300`	Per-simulation timeout in seconds.

Returns: A dict with success_count, failure_count, total_elapsed, parameter_values (the temperature list), and raw_files (one .raw path per temperature).

Example

{
  "success_count": 4,
  "failure_count": 0,
  "total_elapsed": 5.3,
  "parameter_values": [-40.0, 25.0, 85.0, 125.0],
  "raw_files": [
    "/tmp/ltspice/temp_0.raw",
    "/tmp/ltspice/temp_1.raw",
    "/tmp/ltspice/temp_2.raw",
    "/tmp/ltspice/temp_3.raw"
  ]
}

monte_carlo

Run Monte Carlo analysis with component tolerances. Randomly varies component values within tolerance using a normal distribution, then runs an independent simulation for each variant. Useful for yield analysis and worst-case estimation.

Parameter	Type	Default	Description
netlist_text	`str`	---	Complete netlist text. Component names referenced in `tolerances` must appear in the netlist.
n_runs	`int`	---	Number of Monte Carlo iterations to run.
tolerances	`dict[str, float]`	---	Component tolerance map. Keys are component names, values are fractional tolerances (e.g., `{"R1": 0.05}` for 5%).
timeout_seconds	`float`	`300`	Per-simulation timeout in seconds.
seed	`int \| None`	`None`	Optional RNG seed for reproducible results.

Returns: A dict with success_count, failure_count, total_elapsed, parameter_values (list of per-run component value dicts), and raw_files (one .raw path per run).

Example

{
  "success_count": 50,
  "failure_count": 0,
  "total_elapsed": 48.7,
  "parameter_values": [
    { "R1": 1023.4, "C1": 9.87e-08 },
    { "R1": 978.2, "C1": 1.04e-07 },
    { "R1": 1051.0, "C1": 9.52e-08 }
  ],
  "raw_files": [
    "/tmp/ltspice/mc_0.raw",
    "/tmp/ltspice/mc_1.raw",
    "/tmp/ltspice/mc_2.raw"
  ]
}

optimize_circuit

Automatically optimize component values to hit target specifications. Runs real LTspice simulations in a loop, adjusting component values using binary search (single component) or coordinate descent (multiple components). The netlist template uses {ComponentName} placeholders that get substituted each iteration.

Parameter	Type	Default	Description
netlist_template	`str`	---	Netlist text with `{ComponentName}` placeholders (e.g., `{R1}`, `{C1}`) that are substituted each iteration.
targets	`list[dict]`	---	List of target specs. Each dict has: `signal_name` (e.g., `"V(out)"`), `metric` (one of `"bandwidth_hz"`, `"rms"`, `"peak_to_peak"`, `"settling_time"`, `"gain_db"`, `"phase_margin_deg"`), `target_value` (desired number), and `weight` (importance, default 1.0).
component_ranges	`list[dict]`	---	List of tunable components. Each dict has: `component_name` (matching a placeholder), `min_value` (base units), `max_value` (base units), and optional `preferred_series` (`"E12"`, `"E24"`, or `"E96"` to snap to standard values).
max_iterations	`int`	`20`	Maximum number of simulation-and-adjust iterations.

Returns: A dict with best_values (engineering-formatted strings like "4.7k"), best_values_raw (numeric values in base units), best_cost (final cost function value --- 0 means all targets met), iterations (how many loops ran), targets_met (bool), final_metrics (measured values at best point), and history_length.

Example

{
  "best_values": { "R1": "4.7k", "C1": "33n" },
  "best_values_raw": { "R1": 4700.0, "C1": 3.3e-08 },
  "best_cost": 0.002,
  "iterations": 14,
  "targets_met": true,
  "final_metrics": {
    "bandwidth_hz": 1025.3,
    "gain_db": 20.1
  },
  "history_length": 14
}

tune_circuit

Measure circuit performance and suggest parameter adjustments. Single-shot workflow: generates a circuit from a template, simulates it, measures key metrics, compares against targets, and suggests what to change. Call repeatedly with adjusted params until targets are met.

Parameter	Type	Default	Description
template	`str`	---	Template name (from `list_templates`). Works with both netlist and schematic templates.
params	`dict[str, str] \| None`	`None`	Component value overrides (e.g., `{"r": "2.2k", "c": "47n"}`). Use `list_templates` to see available parameters for each template.
targets	`dict[str, str] \| None`	`None`	Performance targets to check against. Keys are metric names, values are comparison strings: `">5000"`, `"<0.1"`, or `"~1000"` (within 10%). Supported metrics: `bandwidth_hz`, `gain_db`, `rms`, `peak_to_peak`, `settling_time_s`, `dc_value`, `fundamental_freq_hz`.
signal	`str`	`"V(out)"`	Signal name to measure.

Returns: A dict with template, params_used, metrics (measured values), targets (per-target pass/fail with actual vs. expected), targets_met (bool), suggestions (list of human-readable tuning advice), signal, and analysis_type ("ac" or "transient").

Example

{
  "template": "rc_lowpass",
  "params_used": { "r": "2.2k", "c": "47n" },
  "metrics": {
    "bandwidth_hz": 1536.4,
    "gain_db": -0.01,
    "dc_value": 0.9998
  },
  "targets": {
    "bandwidth_hz": {
      "target": ">1000",
      "actual": 1536.4,
      "met": true
    }
  },
  "targets_met": true,
  "suggestions": [],
  "signal": "V(out)",
  "analysis_type": "ac"
}