Circuit Inputs And Compatibility

Recommended Circuit Preparation

For a new fixed-step circuit operator, use workflow prepare. It defaults to the source-defined endpoint contract (AS_IS), with full, uncompressed history and real-part causality correction. No input-hold option is needed for this workflow. Select PWL or ZOH explicitly only when that endpoint contract is part of the external interface you are modelling.

tdse workflow prepare --case case.json --matrix z --ports "1,0" \
  --dt 0.001 --nh 256 --out-pack circuit.pack

The numbers are example settings, not an accuracy recommendation. Select the port representation, step and history duration for the actual circuit, and verify timestep and history convergence. Preparation success is not a general accuracy certificate. This workflow does not change arbitrary coupled, nonlinear or switching solvers to PWL and does not certify their stability.

C and C++ applications can use the recommended request factory, then call the same existing workflow API:

tdse_circuit_workflow_handle_to_pack_request_t req =
    tdse_circuit_workflow_handle_simulation_request_init(0.001, 256);
/* Set handle, ports/named_ports, port_count, matrix_kind, out_pack_path. */
tdse_workflow_result_t result = tdse_circuit_workflow_result_init();
tdse_status_t status = tdse_circuit_workflow_handle_to_pack(&req, &result);

C++ offers tdse::workflow::simulationRequest(dt, nh) and handleToPack(req). Import external data into ModelSpace, compile it, and assign the resulting handle.

Integration Adapters And Legacy Projects

PWL and ZOH are input definitions, not accuracy levels. Register-updated DAC outputs and held numeric co-simulation inputs may require ZOH. The integration adapter owns this choice; it must preserve communication delays and event times. A held command does not imply that every solved port current is held. Mixed-input and coupled circuits need an explicitly consistent host algorithm.

A sinusoidal physical source remains sinusoidal; its sampled PWL approximation has a timestep-dependent reconstruction error. Switching events must not be smeared into arbitrary ramps. Do not choose a mode by whichever gives the smallest measured error, or silently fall back to AS_IS after a rejection.

Fixed-Step Runtime Contract

The pack records its mode and timestep. After loading, query tdse_model_get_input_hold_info() or C++ model.inputHoldInfo() to inspect them. Runtime consumes one input vector at each sample time. PWL does not require future input values or another per-step interpolation or convolution pass. With the same history length, port count, precision and backend, the convolution work and history storage have the same size. Step entry adds fixed-cost checks of the pack timestep and continuous timeline; this is not a zero-overhead claim.

ZOH/PWL packs use a fixed step, start at t=0 and require gap-free committed timestamps. Trial/discard/retry remains supported. For zero-state PWL tests, start with u[0]=0 and apply the excitation afterward. A nonzero initial sample with zero negative-index samples implies a ramp over [-T,0], not an abrupt zero-state step at t=0. Nonzero physical initial states need separate treatment.

Changing mode or step requires rebuilding from the raw continuous response. Preparation can require additional computation and memory, especially for large multiports; this does not automatically increase the retained history.

Alias Pair Control

PWL and ZOH preparation may need raw frequency data above the final Runtime Nyquist band. The public alias configuration controls that preparation budget:

tdse_input_hold_alias_config_t alias = tdse_input_hold_alias_config_init();
alias.policy = TDSE_INPUT_HOLD_ALIAS_AUTO;
alias.max_alias_pairs = 16; /* zero uses the product default ceiling */
req.input.alias_config = &alias;

AUTO uses the default convergence criterion. Applications may override it with convergence_tolerance; zero selects the default. This field is ignored by FIXED:

tdse_input_hold_alias_config_t alias = tdse_input_hold_alias_config_fixed(2);
req.input.alias_config = &alias;

For compact call sites, the SDK also provides tdse_input_hold_alias_config_auto(max_pairs) and tdse_input_hold_alias_config_fixed(pairs). Both return a value that can be adjusted before assigning its address to the request.

Use TDSE_INPUT_HOLD_ALIAS_AUTO for normal Circuit workflows. The workflow starts at two pairs and doubles the raw sweep only when the current preparation does not meet convergence_tolerance, up to the default ceiling of 16 pairs. The SDK hard limit is 32 pairs. Use TDSE_INPUT_HOLD_ALIAS_FIXED when a benchmark or build pipeline needs an exact, repeatable sweep budget:

alias.policy = TDSE_INPUT_HOLD_ALIAS_FIXED;
alias.alias_pairs = 32;

Fixed mode never expands implicitly and requires the raw source to contain exactly the requested number of complete pairs. It does not run the convergence gate; the SDK only enforces the supported range and resource limits. A successful report separates the requested policy from the actual result: requested_alias_pairs, alias_pairs, max_alias_pairs, and attempt_count. alias_pairs is the number actually used to construct the pack; it is not the Runtime convolution length and does not add per-step work.

For the same raw spectrum and the same final pair count, AUTO and FIXED use the same alias evaluator. In particular, ZOH uses the same finite-band tail estimate in both policies. The difference is that AUTO evaluates its convergence gate while FIXED accepts the explicitly requested extent. Read convergence_checked before interpreting the diagnostics: it is one only when the AUTO gate ran. A successful FIXED report has converged=1 because preparation completed, but convergence_checked=0 means that no convergence claim was made.

The low-level Builder accepts the same configuration for an already available raw spectrum, but it cannot launch a new circuit sweep. In that API, AUTO means “use and validate the supplied raw extent”; use Circuit Workflow when AUTO must acquire additional frequency points.

The CLI spelling is --convergence-tolerance positive together with --alias-pairs auto|N. The default convergence criterion is 5e-5 and applies only to AUTO. auto uses the workflow policy; an integer selects FIXED mode. --alias-max-pairs N is an optional AUTO ceiling and is rejected unless --alias-pairs auto is present; its omitted value means 16 and its maximum is 32. The successful workflow prepare JSON includes the same requested, actual, ceiling and attempt fields as the C report. The report also exposes the logical raw-matrix payload size, the SDK raw payload capacity and the shape-dependent alias-pair capacity, so multi-port memory pressure can be reviewed before selecting a larger raw band.

Advanced Spectrum And Kernel Inputs

Raw external continuous spectra need an explicit TDSE_SPECTRUM_CONTINUOUS declaration for ZOH/PWL. Builder's atomic tdse_builder_apply_spectrum() binds the preparation and provenance. Use the request initializers. An explicitly zero-filled or legacy correction field means NONE, which is accepted for every input-hold mode. input_hold and correction_method are separate controls. DEFAULT in a workflow request is only a policy selector: it selects REAL for AS_IS, ZOH and PWL. It does not make AS_IS identical to NONE or PWL/ZOH identical to REAL. The low-level Builder spectrum request independently defaults to REAL. Adaptive sweeps, tail processing, IRC and nonuniform history are outside this new-mode workflow.

Complete all frequency-grid changes before causality correction. After that correction, proceed directly to kernel construction without editing the frequency values or endpoints. Read-only analysis must not feed modified spectra back into simulation.

An already discretized FIR or imported impulse-response kernel must not be converted for input hold again. Use the existing tdse_builder_apply_h() path with its defined coefficient scaling and sample indexing. AS_IS disables only the extra hold conversion; it does not by itself disable other spectrum processing. Do not pass an existing discrete operator through continuous-data correction. Untagged H imports do not inherit a prior PWL/ZOH provenance claim.

Failure Handling

On failure, read tdse_circuit_get_last_error_text() immediately. Preparation does not overwrite an existing destination pack on rejection.

Public diagnostics describe request boundaries, not an absolute error bound. The installed input-hold example and its customer validation tool compare the public Runtime against independent RC references for both input definitions. Validation results retain their tested source, binary, platform and input identities; a new frontend default does not change historical report results.