API Reference

Import as import pyspice_rs as ps; units from pyspice_rs.unit. All element/analysis arguments are keyword-only unless noted.

Contents

Circuit / Subcircuit
Element methods
Directives
Testbench
CircuitSimulator
Analysis methods
Backend-specific analyses
Result types
Units
ModelLibrary
Module functions

Circuit / Subcircuit

Signature	Description
`Circuit(title: str)`	Flat circuit. `str(circuit)` → netlist.
`Subcircuit(name: str, ports: list[str] = None, **params)`	Reusable, nestable design block. Same element/directive methods as `Circuit`.
`.gnd`	Ground node (`"0"`).
`.node(name) -> str`	Node name passthrough.
`.element(name) -> str` / `circuit[name]`	Retrieve an element's netlist line.
`.set_source_value(name, value)`	Update a V/I source value after construction.
`.simulator(simulator: str = None) -> CircuitSimulator`	`Circuit` only. Auto-selects backend unless overridden.
`.subcircuit(subckt: Subcircuit)`	Add a subcircuit definition.

Element methods

Available on Circuit, Subcircuit, and (for stimulus) Testbench. value accepts a float or a UnitValue (10 @ u_kOhm).

Method	SPICE	Signature
`R`	R	`(name, positive, negative, value, raw_spice=None)`
`C`	C	`(name, positive, negative, value)`
`L`	L	`(name, positive, negative, value)`
`K`	K	`(name, inductor1, inductor2, coupling)`
`V`	V	`(name, positive, negative, value, ac=None, ac_phase=None)`
`I`	I	`(name, positive, negative, value, ac=None, ac_phase=None)`
`BV`	B	`(name, positive, negative, expression)` — behavioral voltage
`BI`	B	`(name, positive, negative, expression)` — behavioral current
`E`	E	`(name, positive, negative, control_positive, control_negative, voltage_gain)` — VCVS
`G`	G	`(name, positive, negative, control_positive, control_negative, transconductance)` — VCCS
`F`	F	`(name, positive, negative, vsense, current_gain)` — CCCS
`H`	H	`(name, positive, negative, vsense, transresistance)` — CCVS
`D`	D	`(name, anode, cathode, model)`
`Q` / `BJT`	Q	`(name, collector, base, emitter, model)`
`M` / `MOSFET`	M	`(name, drain, gate, source, bulk, model, **params)` — params e.g. `L=0.5, W=5`
`J`	J	`(name, drain, gate, source, model)` — JFET
`Z`	Z	`(name, drain, gate, source, model)` — MESFET
`S`	S	`(name, positive, negative, control_positive, control_negative, model)` — V-controlled switch
`W`	W	`(name, positive, negative, vcontrol, model)` — I-controlled switch
`T`	T	`(name, input_positive, input_negative, output_positive, output_negative, Z0, TD)`
`X`	X	`(name, subcircuit_name, *nodes)` — positional
`A`	A	`(name, connections: list[str], model)` — XSPICE code model

Waveform source builders

Method	Signature
`SinusoidalVoltageSource` / `SinusoidalCurrentSource`	`(name, positive, negative, dc_offset=0.0, offset=0.0, amplitude=1.0, frequency=1000.0)`
`PulseVoltageSource` / `PulseCurrentSource`	`(name, positive, negative, initial_value=0.0, pulsed_value=1.0, pulse_width=50e-9, period=100e-9, rise_time=1e-9, fall_time=1e-9)`
`PieceWiseLinearVoltageSource`	`(name, positive, negative, values: list[tuple[float, float]])` — (time, value) pairs

Verilog / HDL

Method	Description
`.veriloga(source_or_path) -> str`	Compile Verilog-A (inline string or `.va` path) to OSDI; returns the `.osdi` path. Requires `openvaf`.
`.osdi(path)`	Load a pre-compiled OSDI binary.
`.verilog(source, mode="simulate"\|"synthesize", instance_name, connections: dict, pdk=None, liberty=None, spice_models=None)`	Wire a digital Verilog module via co-simulation or synthesis.

Directives

Method	Emits
`.model(name, kind, **params)`	`.model`
`.include(path)`	`.include`
`.lib(path, section)`	`.lib`
`.parameter(name, value)`	`.param`
`.options(**kwargs)`	`.options`
`.temp(temperature)`	`.temp`
`.raw_spice(line)`	verbatim netlist line

Testbench

Member	Description
`Testbench(dut: Subcircuit)`	Wrap a DUT for simulation.
`.with_backend(name: str)`	Select simulator backend.
`.add_subcircuit(subckt)`	Register a subcircuit definition used by the DUT.
`.use_pdk(lib: ModelLibrary)`	Attach a PDK model library.
`.check_backend(name) -> list[str]`	Compatibility issues for a backend.
stimulus methods	All element methods above (V, I, waveform builders, …).
config methods	Same as `CircuitSimulator` below.
analysis methods	Same as `CircuitSimulator` below.

CircuitSimulator

Created by circuit.simulator(simulator=None).

Member	Description
`CircuitSimulator.available_backends() -> list[str]`	Static. Backends installed locally.
`.options(**kwargs)`	Solver options (`RELTOL`, `ABSTOL`, `VNTOL`, `GMIN`, …).
`.initial_condition(**node_values)`	`.ic`
`.node_set(**node_values)`	`.nodeset`
`.save(*signals)`	Explicit save list, e.g. `"V(out)"`, `"I(Vdd)"`.
`.save_currents = bool`	Save all branch currents.
`.measure(*parts)`	`.meas`, e.g. `("TRAN", "v_peak", "MAX", "V(out)")`.
`.temperature = float` / `.nominal_temperature = float`	`.temp` / `tnom`.
`.step(param, start, stop, step)`	Linear `.step`.
`.step_sweep(param, start, stop, step, sweep_type)`	`"lin" \| "oct" \| "dec"`.
`.check_backend(name) -> list[str]`	Compatibility issues.

Analysis methods

On both Testbench and CircuitSimulator.

Method	Returns
`operating_point()`	`OperatingPoint`
`dc(**{source: slice(start, stop, step)})`	`DcAnalysis`
`ac(variation="dec", number_of_points=10, start_frequency=1.0, stop_frequency=1e9)`	`AcAnalysis`
`transient(step_time, end_time, start_time=None, max_time=None, use_initial_condition=False)`	`TransientAnalysis`
`noise(output_node, ref_node, src, variation="dec", points=10, start_frequency=1e3, stop_frequency=1e8, points_per_summary=None)`	`NoiseAnalysis`
`transfer_function(outvar, insrc)` / `tf(...)`	`TransferFunctionAnalysis`
`dc_sensitivity(output_variable)`	`SensitivityAnalysis`
`ac_sensitivity(output_variable, variation="dec", number_of_points=10, start_frequency=100.0, stop_frequency=1e5)`	`SensitivityAnalysis`
`polezero(node1, node2, node3, node4, tf_type, pz_type)`	`PoleZeroAnalysis`
`distortion(variation="dec", points=10, start_frequency=100.0, stop_frequency=1e8, f2overf1=None)`	`DistortionAnalysis`
`pss(fundamental_frequency, stabilization_time, observe_node, points_per_period=128, harmonics=10)`	`PssAnalysis`
`s_param(variation="dec", number_of_points=10, start_frequency=1e6, stop_frequency=1e10)`	`SParamAnalysis`
`harmonic_balance(fundamental_frequencies: list, num_harmonics=None)`	`HarmonicBalanceAnalysis`
`stability(probe, variation="dec", number_of_points=10, start_frequency=1.0, stop_frequency=1e10)`	`StabilityAnalysis`
`transient_noise(step_time, end_time)`	`TransientNoiseAnalysis`
`network_params(output_current, input_source, z_in=50.0, z_out=50.0, variation="dec", points=100, start_freq=1e3, stop_freq=1e9)`	`SParamAnalysis`

Backend-specific analyses

Spectre

Method	Returns
`spectre_sweep(param, start, stop, step, inner_analysis, inner_type="ac")`	`RawData`
`spectre_montecarlo(num_iterations, inner_analysis, inner_type="ac", seed=None)`	`RawData`
`spectre_pac(pss_fundamental, pss_stabilization, pss_harmonics=10, variation="dec", points=100, start_freq=1.0, stop_freq=1e9, sweep_type="relative")`	`AcAnalysis`
`spectre_pnoise(pss_fundamental, pss_stabilization, pss_harmonics=10, output_node, ref_node, variation="dec", points=100, start_freq=1.0, stop_freq=1e9)`	`NoiseAnalysis`
`spectre_pxf(pss_fundamental, pss_stabilization, pss_harmonics=10, output_node, source, variation="dec", points=100, start_freq=1.0, stop_freq=1e9)`	`AcAnalysis`
`spectre_pstb(pss_fundamental, pss_stabilization, pss_harmonics=10, probe, variation="dec", points=100, start_freq=1.0, stop_freq=1e9)`	`StabilityAnalysis`

Xyce

Method	Returns
`xyce_sampling(num_samples, param_distributions: list[tuple[str, str]])`	`SamplingAnalysis`
`xyce_embedded_sampling(num_samples, param_distributions)`	`SamplingAnalysis`
`xyce_pce(num_samples, param_distributions, expansion_order=3)`	`SamplingAnalysis`
`xyce_fft(signal, np=1024, start=0.0, stop=1e-3, window="HANN", format="UNORM")`	`XyceFftAnalysis`

Distribution strings: "normal(mean,stddev)", "uniform(low,high)".

Result types

Common interface on every result: res["name"] / res.name → numpy array (float for OperatingPoint), .nodes, .branches, .measures (dict, name → float).

Type	Extra members
`OperatingPoint`	—
`DcAnalysis`	`.sweep` — sweep axis
`AcAnalysis`	`.frequency`
`TransientAnalysis`	`.time`
`NoiseAnalysis`, `TransferFunctionAnalysis`, `SensitivityAnalysis`	—
`PoleZeroAnalysis`	`.poles`, `.zeros`
`DistortionAnalysis`	`.frequency`
`PssAnalysis`, `SParamAnalysis`, `HarmonicBalanceAnalysis`, `StabilityAnalysis`, `TransientNoiseAnalysis`	`.frequency` or `.time` axis
`SamplingAnalysis`	—
`XyceFftAnalysis`	`.frequency`, `.magnitude`, `.phase`, `.enob`, `.sfdr_db`, `.snr_db`, `.thd_db`
`RawData`	`.title`, `.plot_name`, `.is_complex`, `.variable_names`

Units

Quantity	Constants
Voltage	`u_V, u_mV, u_uV` (`u_µV`)
Current	`u_A, u_mA, u_uA, u_nA` (`u_µA`)
Resistance	`u_Ohm, u_kOhm, u_MOhm` (`u_Ω, u_kΩ, u_MΩ`)
Capacitance	`u_F, u_mF, u_uF, u_nF, u_pF, u_fF` (`u_µF`)
Inductance	`u_H, u_mH, u_uH, u_nH` (`u_µH`)
Frequency	`u_Hz, u_kHz, u_MHz, u_GHz`
Time	`u_s, u_ms, u_us, u_ns, u_ps` (`u_µs`)
Power	`u_W, u_mW, u_uW` (`u_µW`)
Temperature	`u_Degree`

UnitValue (from value @ unit): .value → SI float, .str_spice() → netlist suffix form ("10k"), float(uv) works.

ModelLibrary

ModelLibrary(path: str, corner: str = None,
             setup_includes: list[str] = None, **backend_paths)

Properties: .name, .path, .corner. Per-backend keyword paths let one object map to different model files per simulator. Attach with tb.use_pdk(lib).

Module functions

Function	Description
`lint(netlist: str, backend=None) -> dict`	`{"errors": [{"line", "message"}], "warnings": [{"line", "message", "suggestion", "backends_affected"}]}`
`compile_veriloga(source_or_path: str) -> str`	Compile Verilog-A to an OSDI binary; returns its path. Requires `openvaf`.