Circuit Authoring Workflows

For new fixed-step circuit packs, use tdse workflow prepare with explicit --dt and --nh. Source-defined (AS_IS) endpoint input handling and real-part causality correction are selected by default; PWL and ZOH are explicit alternatives. See Circuit Inputs And Compatibility for held interfaces and advanced kernel imports. This does not change coupled-solver semantics.

This chapter owns Circuit command workflows and the ModelSpace authoring path. Exact option syntax remains in the separate CLI Reference.

Common CLI Tasks

The CLI is the fastest way to validate a ModelSpace case, explore a circuit, or generate Builder-facing artifacts. The sections below explain the intent of each command family. Use CLI Reference when you need exhaustive flag or output-field detail.

Circuit routing accepts the global --json-out <path|-> option for a machine-readable command envelope. Execution commands consume a ModelSpace JSON file with --case <case.json>; discovery commands such as caps do not.

If you are writing a script, use --json-out - (stdout) and parse the JSON envelope. Send data/report outputs to files; the CLI rejects configurations where both a data output and --json-out target stdout. Human-readable output is for interactive use only and may change between versions.

caps: Check Available Backends

Before you run any computation, you need to know what solver backends are available on your machine. The caps command answers this: it prints a table of every backend the SDK was built with, and whether each one is usable right now.

tdse circuit caps --out-caps circuit-caps.txt --json-out -

This is the first thing to run on a new machine or after upgrading the SDK. A backend might show as unavailable because a required library is missing (CUDA, MKL), because the GPU driver is outdated, or because the backend was not compiled into this build.

For accelerated execution, use tdse circuit capability-matrix. Its JSON report separates TDSE Circuit CUDA solver, TDSE Circuit accelerated transient, and TDSE GPU Add-on Runtime provider rows. The report identifies the product_surface as TDSE Circuit, technical_package_type as SDK, the core_contract as the TDSE Circuit execution capability contract, and the capability_explain_schema as tdse.circuit.execution_capability.explain.v1. Each row includes an availability_boundary (build, discovery, device, runtime, or available), user_explanation, and recommended_action, so scripts and users see the same reason boundary.

Import Architecture Boundary

Native imports share one result, issue, capability, semantic, and reporting contract. Format-specific code owns parsing and source-to-ModelSpace mapping; it does not invent a separate report vocabulary or approximation policy. The active importer layout keeps parser/file input, semantic mapping, and diagnostics/reporting in separate files for RAW, SPICE, ATP, OpenDSS, and GridLAB-D. Their result structs derive from the shared native import result envelope, so success state, ModelSpace case payload, report JSON, errors, and warnings have one storage shape across native importers.

matrix: Compute Y or Z over Frequency

This is the workhorse command. You have a ModelSpace case and a set of ports, and you want the admittance (Y) or impedance (Z) matrix at each frequency in a grid. The output goes directly to Builder - the port order you specify here must match the port order you use in h_from_spectrum.

tdse circuit matrix \
  --case case.json \
  --matrix y --ports "1,0;2,0" \
  --w0 0 --dw 100 --nfreq 5 \
  --out-data matrix.csv --json-out -

The frequency grid is defined by three numbers: a start frequency w0 in rad/s, a step dw in rad/s, and a count nfreq. The grid covers w0, w0 + dw, w0 + 2*dw, ..., w0 + (nfreq-1)*dw. For a DC start use --w0 0.

DC policy values:

Solving at exactly zero frequency (DC) is harder than it sounds. Inductors become shorts, capacitors become opens, and the MNA matrix can become singular. These policies control how the solver handles omega = 0:

The default (exact_dc_then_fallback) is the right choice for most circuits. Switch to extrapolate_from_positive if your circuit has no DC path to ground (floating nets, ideal transformers) and regularization isn't helping.

series: Compute VOC or ISC Time Sequences

The matrix command gives you frequency-domain behavior. But to drive a time-domain simulation, you often need source waveforms - the open-circuit voltage or short-circuit current seen at each port as a function of time. That's what series computes.

tdse circuit series \
  --case case.json \
  --series voc --ports "1,0" \
  --method transient --dt 1e-4 --steps 64 \
  --out-data series.csv --json-out -

The output is a time series: one row per time step, one column per port. The time at step k is t0 + k * dt.

Choosing a synthesis method:

The method you pick depends on your circuit and what accuracy you need:

If you are unsure, start with transient because it is the broadest supported time-domain method. It is not a universal correctness guarantee: validate the selected method, timestep, and output against an appropriate reference before experimenting with ifft for speed.

probe: Observe Internal Voltages or Currents

Port matrices tell you what happens at the terminals. But often you need to see inside the circuit - the voltage at an internal node, the current through a particular branch. Probes let you instrument the circuit and extract those values without modifying the netlist.

# AC probe -frequency sweep of internal quantities
tdse circuit probe \
  --domain ac --case case.json \
  --observe "v(1);v(2,0)" --observe-source argument \
  --ac-excitation small_signal \
  --sweep-kind lin --fstart-hz 50 --fstop-hz 5000 --sweep-points 100 \
  --out-data probe.csv --json-out -

# Transient probe -time-domain waveform of internal quantities
tdse circuit probe \
  --domain transient --case case.json \
  --observe "v(1);i(r1)" --observe-source argument \
  --method transient --dt 1e-4 --steps 64 \
  --out-data probe.csv --json-out -

Probes work in both AC and transient domains. In the AC domain, you get frequency sweeps of complex voltages and currents. In the transient domain, you get time-domain waveforms. The probe expressions use a simple syntax:

The --observe-source flag is worth understanding. When set to argument, the CLI uses the probes you specify with --observe. When set to study, it reads the persisted ModelSpace observations. The default auto selects argument_or_study when --observe is present and study otherwise. Select argument_or_study explicitly when you want the combined source behavior.

When to Use Which Command

If you are new to TDSE Circuit, this table is your cheat sheet: