API Reference¶

This page is generated from the pulsim package surface (stubs + public exports).

Canonical usage

For new integrations, prefer YamlParser + SimulationOptions + Simulator.

Circuit Runtime¶

Circuit ¶

Circuit()

VirtualComponent ¶

VirtualComponent()

MixedDomainStepResult ¶

MixedDomainStepResult()

VirtualChannelMetadata ¶

VirtualChannelMetadata()

Linear Devices¶

Resistor ¶

Resistor(resistance: float, name: str = '')

Capacitor ¶

Capacitor(capacitance: float, initial_voltage: float = 0.0, name: str = '')

Inductor ¶

Inductor(inductance: float, initial_current: float = 0.0, name: str = '')

VoltageSource ¶

VoltageSource(voltage: float, name: str = '')

CurrentSource ¶

CurrentSource(current: float, name: str = '')

Nonlinear and Switching Devices¶

IdealDiode ¶

IdealDiode(name: str = '')

IdealSwitch ¶

IdealSwitch(name: str = '')

MOSFETParams ¶

MOSFETParams()

MOSFET ¶

MOSFET(params: MOSFETParams, name: str = '')

IGBTParams ¶

IGBTParams()

IGBT ¶

IGBT(params: IGBTParams, name: str = '')

Time-Varying Sources¶

PWMParams ¶

PWMParams()

PWMVoltageSource ¶

PWMVoltageSource(params: PWMParams, name: str = '')

SineParams ¶

SineParams()

SineVoltageSource ¶

SineVoltageSource(params: SineParams, name: str = '')

RampParams ¶

RampParams()

RampGenerator ¶

RampGenerator(params: RampParams, name: str = '')

PulseParams ¶

PulseParams()

PulseVoltageSource ¶

PulseVoltageSource(params: PulseParams, name: str = '')

Control and Signal Blocks¶

PIController ¶

PIController(kp: float = 1.0, ki: float = 0.0, name: str = '')

PIDController ¶

PIDController(kp: float = 1.0, ki: float = 0.0, kd: float = 0.0, name: str = '')

Comparator ¶

Comparator(threshold: float = 0.0, name: str = '')

SampleHold ¶

SampleHold(name: str = '')

RateLimiter ¶

RateLimiter(max_rate: float = 1.0, name: str = '')

MovingAverageFilter ¶

MovingAverageFilter(window_size: int = 10, name: str = '')

HysteresisController ¶

HysteresisController(upper: float = 1.0, lower: float = -1.0, name: str = '')

LookupTable1D ¶

LookupTable1D(x: List[float], y: List[float], name: str = '')

Parser and Simulation Entry Points¶

YamlParserOptions ¶

YamlParserOptions()

YamlParser ¶

YamlParser(options: YamlParserOptions = ...)

Simulator ¶

Simulator(circuit: Circuit, options: SimulationOptions = ...)

SimulationOptions ¶

SimulationOptions()

SimulationResult ¶

SimulationResult()

Solver Configuration¶

Tolerances ¶

Tolerances()

NewtonOptions ¶

NewtonOptions()

NewtonResult ¶

NewtonResult()

LinearSolverKind ¶

Bases: Enum

PreconditionerKind ¶

Bases: Enum

IterativeSolverConfig ¶

IterativeSolverConfig()

LinearSolverStackConfig ¶

LinearSolverStackConfig()

LinearSolverConfig ¶

LinearSolverConfig()

LinearSolverTelemetry ¶

LinearSolverTelemetry()

Integration and Timestep¶

Integrator ¶

Bases: Enum

StepMode ¶

Bases: Enum

TimestepMethod ¶

Bases: Enum

TimestepConfig ¶

TimestepConfig()

AdvancedTimestepConfig ¶

AdvancedTimestepConfig()

Bases: TimestepConfig

RichardsonLTEConfig ¶

RichardsonLTEConfig()

BDFOrderConfig ¶

BDFOrderConfig()

StiffnessConfig ¶

StiffnessConfig()

DC and Convergence¶

DCStrategy ¶

Bases: Enum

GminConfig ¶

GminConfig()

SourceSteppingConfig ¶

SourceSteppingConfig()

PseudoTransientConfig ¶

PseudoTransientConfig()

InitializationConfig ¶

InitializationConfig()

DCConvergenceConfig ¶

DCConvergenceConfig()

DCAnalysisResult ¶

DCAnalysisResult()

Periodic and Harmonic Analysis¶

PeriodicSteadyStateOptions ¶

PeriodicSteadyStateOptions()

PeriodicSteadyStateResult ¶

PeriodicSteadyStateResult()

HarmonicBalanceOptions ¶

HarmonicBalanceOptions()

HarmonicBalanceResult ¶

HarmonicBalanceResult()

Thermal and Loss Modeling¶

ThermalCouplingPolicy ¶

Bases: Enum

ThermalCouplingOptions ¶

ThermalCouplingOptions()

ThermalDeviceConfig ¶

ThermalDeviceConfig()

DeviceThermalTelemetry ¶

DeviceThermalTelemetry()

ThermalSummary ¶

ThermalSummary()

SwitchingEnergy ¶

SwitchingEnergy()

MOSFETLossParams ¶

MOSFETLossParams()

IGBTLossParams ¶

IGBTLossParams()

DiodeLossParams ¶

DiodeLossParams()

ConductionLoss ¶

ConductionLoss()

SwitchingLoss ¶

SwitchingLoss()

LossBreakdown ¶

LossBreakdown()

LossAccumulator ¶

LossAccumulator()

EfficiencyCalculator ¶

EfficiencyCalculator()

LossResult ¶

LossResult()

SystemLossSummary ¶

SystemLossSummary()

FosterStage ¶

FosterStage()

FosterNetwork ¶

FosterNetwork()

CauerStage ¶

CauerStage()

CauerNetwork ¶

CauerNetwork()

ThermalSimulator ¶

ThermalSimulator()

ThermalLimitMonitor ¶

ThermalLimitMonitor()

ThermalResult ¶

ThermalResult()

Events and Backend Telemetry¶

SimulationEventType ¶

Bases: Enum

SimulationEvent ¶

SimulationEvent()

FallbackReasonCode ¶

Bases: Enum

FallbackPolicyOptions ¶

FallbackPolicyOptions()

FallbackTraceEntry ¶

FallbackTraceEntry()

BackendTelemetry ¶

BackendTelemetry()

Convergence Monitoring¶

IterationRecord ¶

IterationRecord()

ConvergenceHistory ¶

ConvergenceHistory()

VariableConvergence ¶

VariableConvergence()

PerVariableConvergence ¶

PerVariableConvergence()

Validation and Benchmarks¶

RCAnalytical ¶

RCAnalytical(R: float, C: float, V_initial: float, V_final: float)

RLAnalytical ¶

RLAnalytical(R: float, L: float, V_source: float, I_initial: float)

RLCAnalytical ¶

RLCAnalytical(R: float, L: float, C: float, V_source: float, V_initial: float, I_initial: float)

RLCDamping ¶

Bases: Enum

ValidationResult ¶

ValidationResult()

compare_waveforms ¶

compare_waveforms(name: str, simulated: List[tuple[float, float]], analytical: List[tuple[float, float]], threshold: float = 0.001) -> ValidationResult_v2

export_validation_csv ¶

export_validation_csv(results: List[ValidationResult_v2]) -> str

export_validation_json ¶

export_validation_json(results: List[ValidationResult_v2]) -> str

BenchmarkTiming ¶

BenchmarkTiming()

BenchmarkResult ¶

BenchmarkResult()

export_benchmark_csv ¶

export_benchmark_csv(results: List[BenchmarkResult]) -> str

export_benchmark_json ¶

export_benchmark_json(results: List[BenchmarkResult]) -> str

Pure-Python Utilities¶

ParsedNetlist `dataclass` ¶

ParsedNetlist(circuit: Circuit, title: str = '', warnings: List[NetlistWarning] = list(), models: Dict[str, Any] = dict(), node_map: Dict[str, int] = dict())

Result of parsing a SPICE netlist.

NetlistParseError ¶

NetlistParseError(message: str, line_number: Optional[int] = None, line_content: Optional[str] = None)

Bases: Exception

Error during netlist parsing with line context.

NetlistWarning `dataclass` ¶

NetlistWarning(line_number: int, line_content: str, message: str)

Warning from netlist parsing.

parse_netlist ¶

parse_netlist(netlist: str, *, strict: bool = False, default_mosfet_params: Optional[MOSFETParams] = None, default_igbt_params: Optional[IGBTParams] = None) -> Circuit

Parse a SPICE-like netlist string and return a Pulsim Circuit.

Parameters:

Name	Type	Description	Default
`netlist`	`str`	SPICE netlist string	required
`strict`	`bool`	If True, raise error on unknown directives; if False, warn and skip	`False`
`default_mosfet_params`	`Optional[MOSFETParams]`	Default MOSFET parameters when model not specified	`None`
`default_igbt_params`	`Optional[IGBTParams]`	Default IGBT parameters when model not specified	`None`

Returns:

Type	Description
`Circuit`	Configured Circuit object ready for simulation

Raises:

Type	Description
`NetlistParseError`	On syntax errors or invalid device specifications

Example

netlist = ''' ... * RC Circuit ... V1 in 0 5 ... R1 in out 1k ... C1 out 0 1u IC=0 ... .end ... ''' ckt = parse_netlist(netlist) print(ckt.num_devices()) 3

parse_netlist_verbose ¶

parse_netlist_verbose(netlist: str, *, strict: bool = False, default_mosfet_params: Optional[MOSFETParams] = None, default_igbt_params: Optional[IGBTParams] = None) -> ParsedNetlist

Parse netlist and return detailed result with warnings.

Parameters:

Name	Type	Description	Default
`netlist`	`str`	SPICE netlist string	required
`strict`	`bool`	If True, raise error on unknown directives	`False`
`default_mosfet_params`	`Optional[MOSFETParams]`	Default MOSFET parameters	`None`
`default_igbt_params`	`Optional[IGBTParams]`	Default IGBT parameters	`None`

Returns:

Type	Description
`ParsedNetlist`	ParsedNetlist object containing:
`ParsedNetlist`	circuit: The built Circuit object
`ParsedNetlist`	title: Circuit title (first comment line)
`ParsedNetlist`	warnings: List of NetlistWarning objects
`ParsedNetlist`	models: Dict of parsed .model definitions
`ParsedNetlist`	node_map: Dict mapping node names to indices

Example

result = parse_netlist_verbose(netlist) print(f"Title: {result.title}") for w in result.warnings: ... print(f"Warning: {w}")

parse_value ¶

parse_value(value_str: str, line_number: Optional[int] = None) -> float

Parse a value string with optional engineering suffix.

Supports

Plain numbers: '100', '1.5', '-3.14'
Scientific notation: '1e-6', '1.5E3'
Engineering suffixes: '10k', '100u', '1.5meg', '4.7n'

Parameters:

Name	Type	Description	Default
`value_str`	`str`	Value string to parse	required
`line_number`	`Optional[int]`	Line number for error reporting	`None`

Returns:

Type	Description
`float`	Parsed float value

Raises:

Type	Description
`NetlistParseError`	If value cannot be parsed

Examples:

>>> parse_value('100')
100.0
>>> parse_value('10k')
10000.0
>>> parse_value('1.5meg')
1500000.0
>>> parse_value('100u')
0.0001
>>> parse_value('4.7n')
4.7e-09

SignalEvaluator ¶

SignalEvaluator(circuit_data: dict)

Evaluates a signal-flow DAG from a circuit description dict each step.

The evaluator is deliberately independent of any GUI framework. It operates on plain Python dicts (the circuit_data format) and uses the native C++ control objects from pulsim._pulsim when available, falling back to pure-Python equivalents otherwise.

Parameters¶

circuit_data : dict Circuit description with keys "components", "wires", "node_map", and "node_aliases". The format is identical to the dict produced by the GUI's SimulationService.convert_gui_circuit(), but it can also be constructed programmatically (no GUI needed).

Examples¶

See module docstring for a complete usage example.

build ¶

build() -> None

Parse the circuit dict, build the signal DAG, and initialise state.

Must be called once before :meth:step. Call again to rebuild after the circuit description changes.

Raises¶

AlgebraicLoopError When a directed cycle exists among the signal-domain blocks.

has_signal_blocks ¶

has_signal_blocks() -> bool

Return True if there are any evaluable signal blocks.

pwm_components ¶

pwm_components() -> dict[str, str]

Return {comp_id: backend_name} for PWM generators with DUTY_IN connected.

update_probes ¶

update_probes(probe_values: dict[str, float]) -> None

Inject probe measurements into the evaluator state.

Call this after each electrical simulation step with the latest measured values so that feedback blocks (VOLTAGE_PROBE, CURRENT_PROBE) reflect the true circuit state.

Parameters¶

probe_values : dict[str, float] {component_id: measured_value} mapping. Unrecognised IDs are silently ignored.

step ¶

step(t: float) -> dict[str, Any]

Evaluate all signal blocks in topological order at time t.

Parameters¶

t : float Current simulation time in seconds.

Returns¶

dict[str, Any] {comp_id: output_value} for every signal block. PWM duty values are clamped to [0, 1].

get_pwm_duty ¶

get_pwm_duty(comp_id: str) -> float

Return current computed duty cycle [0, 1] for a PWM component.

reset ¶

reset() -> None

Reset all stateful controller objects (integrators, PI state, etc.).

AlgebraicLoopError ¶

AlgebraicLoopError(cycle_ids: list[str])

Bases: RuntimeError

Raised when a cycle is detected in the signal-flow graph.

Attributes¶

cycle_ids : list[str] Component names (or IDs) that form the cycle.

Magnetic-Core Helpers¶

MagneticCoreConfig `dataclass` ¶

MagneticCoreConfig(enabled: bool = True, model: str = 'saturation', loss_policy: str = 'telemetry_only', saturation_current: float | None = None, saturation_inductance: float | None = None, saturation_exponent: float | None = None, core_loss_k: float = 0.0, core_loss_alpha: float = 2.0, core_loss_freq_coeff: float = 0.0, i_equiv_init: float = 0.0, hysteresis_band: float | None = None, hysteresis_strength: float = 0.15, hysteresis_loss_coeff: float = 0.2, hysteresis_state_init: float = 1.0)

Typed nonlinear magnetic-core configuration for virtual components.

Use :func:apply_magnetic_core_config to merge into the numeric_params and metadata dictionaries passed to :meth:pulsim.Circuit.add_virtual_component.

to_numeric_params ¶

to_numeric_params() -> Dict[str, float]

Return numeric parameters compatible with Circuit.add_virtual_component.

to_metadata ¶

to_metadata() -> Dict[str, str]

Return metadata compatible with Circuit.add_virtual_component.

MagneticCoreConfigError ¶

MagneticCoreConfigError(message: str, *, code: str, field: str)

Bases: ValueError

Raised when a magnetic-core configuration is invalid.

Attributes¶

code : str Stable machine-readable error code. field : str Field path that failed validation.

apply_magnetic_core_config ¶

apply_magnetic_core_config(numeric_params: Dict[str, float], metadata: Dict[str, str], config: MagneticCoreConfig) -> Tuple[Dict[str, float], Dict[str, str]]

Merge a magnetic-core config into component parameter dictionaries.

Returns new dictionaries; the inputs are not mutated.

Performance Utilities and Enums¶

SIMDLevel ¶

Bases: Enum

DeviceType ¶

Bases: Enum

DeviceHint ¶

Bases: Enum

SolverStatus ¶

Bases: Enum

detect_simd_level ¶

detect_simd_level() -> SIMDLevel

simd_vector_width ¶

simd_vector_width() -> int

backend_capabilities ¶

backend_capabilities() -> Dict[str, bool]

solver_status_to_string ¶

solver_status_to_string(status: SolverStatus) -> str