Simulation and Assertion Reference
On this page
Kessetsu compiles each source to canonical SPICE and runs the same typed analysis contract in native CLI and Web Hub. Native execution discovers a version-probed Ngspice executable; the browser uses the pinned Ngspice-derived worker runtime. Simulator console text is not the public API: datasets, measurements and assertions are versioned Rust Core objects.
Analyses
| Statement | Result | Typical use |
|---|---|---|
simulate op |
scalar operating point | bias voltages/currents |
simulate tran <step> <stop> |
time series | waveform, RMS, THD, clipping, dissipation |
simulate tran <step> <stop> uic |
initialized time series | skips DC operating point; applies model capacitor and initial V(NET) = <voltage> conditions |
| `simulate ac dec | lin | oct <points> <start> <stop>` |
simulate dc <source> <start> <stop> <step> |
swept real series | transfer curve |
Arguments must be dimensionally valid. Transient step/stop and AC point counts/frequencies
must be positive, with AC start below stop. DC sweep supports independent voltage/current
sources and signed endpoints; its nonzero step must move from start toward stop, including
descending sweeps. Multiple analysis kinds may coexist in one source. Operating-point,
transient, and AC analyses are unique, while DC sweeps are unique per source; ambiguous
repetitions fail semantic validation with KES-C009. The browser runs valid analyses
independently in a cancellable Worker and Core combines them into kessetsu.simulation.v1.
The Web plots recorded samples against physical axes, with explicit V/A sweep units. AC plots show absolute signal magnitude relative to 1 V or 1 A, not a transfer ratio, and the selected signal's phase. Output/input metrics use the Core measurement definitions below. Assertion measurements/limits are displayed separately; a reduced measurement is not a point-by-point waveform limit. See the Web guide for cursor and zoom behavior.
Assertions
The form is assert metric(arguments) comparator threshold. Comparators are <, >, ==, <= and >=. Result states are:
PASS: valid measurement satisfies the comparison.FAIL: valid measurement violates the comparison.ERROR: the metric could not be evaluated from the available typed data.SKIPPED: simulation did not complete, so the assertion was not evaluated.
Unsupported metric names and invalid argument shapes fail semantic validation with KES-C006 before a simulator starts. Strict inequalities are not loosened. Equality and inclusive comparisons use the versioned absolute/relative tolerance reported with kessetsu.assertion.v1.
For supervised agents and CI, the same assertions may live in an evaluator-owned .kessreq file and be supplied with kess test design.kess --requirements limits.kessreq. This mode forbids inline assertions in the design, records the exact requirement-file SHA-256, and optionally verifies --requirements-sha256. See the CLI reference for ownership and file behavior. Hash pinning detects changed limits; it is not a substitute for filesystem permissions controlled by the supervising process.
Measurements
Primitive reductions include value, min, max, absolute peak, pk2pk/p2p/vpp, average/avg and rms. Voltage primitives accept single-ended net or device measurements (V(OUT), V(Q1)) as well as differential net voltages V(A, B) — comparing two named nets (V(OUT_P, OUT_N)), a net against ground (V(OUT, GND) or V(OUT, 0)), terminal pairs (V(Q1.c, Q1.e)), or mixed component-pin and net endpoints (V(R1.p1, OUT)) across OP, transient, DC sweep, and AC analyses (where AC metrics compute elementwise complex V(A) - V(B) and ground maps to 0 + j0).
Derived metrics include:
- AC transfer and edge metrics:
gain,gain_at,lower_cutoff,upper_cutoff,bandwidth/cutoff, andphase. - Periodic and pulse metrics over transient traces (accepting either
signalor a windowedsignal, start, stopform):frequency(aliasfreq): dominant frequency inHzfrom rising mean crossings.period: dominant waveform period1 / frequencyin seconds (s).duty_cycle(aliasduty): pulse high-time percentage (%) above the(min + max) / 2midpoint over complete rising-crossing cycles.
- Power, distortion, and dynamic step metrics:
output_power,efficiency,clipping,dissipation,rise_time,fall_time,settling_time,overshoot,energy, andthd(accepting 2-argumentthd(signal, fundamental)over the full trace, 4-argumentthd(signal, fundamental, start, stop), or 5-argumentthd(signal, fundamental, start, stop, hann)with Hann windowing).
Exact formulas, windows, required datasets, current polarity and power sign are normative in engineering measurements.
CLI examples
kess simulate circuit.kess --format json
kess test circuit.kess --format json
Get-Content circuit.kess | kess test - --format json
Exit 3 denotes simulator/runtime failure; exit 4 denotes assertion FAIL, ERROR or SKIPPED. kess test also returns exit 4 and KES-T000 without launching the simulator when no assertions are defined; use kess simulate when verification is not intended. JSON stdout remains one parseable object. Use --include datasets,raw-log only for debugging large/raw data.
If a physical part assignment includes provided ratings, simulation/test JSON also includes
part_stress (kessetsu.part-stress.v1) and its summary. Exceeding such a value does not change
the command exit code: these records may be user-entered, conditions may be incomplete, and the
electrical model may omit thermal/SOA behavior. Express required acceptance behavior with an
assert or evaluator-owned .kessreq; use part stress to keep selection evidence visible.
Reproducibility boundary
Kessetsu fixes source, Core schema, generated netlist, model/package hashes, simulator identity and evaluation formulas. Floating-point samples may differ slightly across simulator builds and platforms, so parity gates compare engineering decisions with declared tolerances instead of treating recorded decimals as universal golden bytes.