kessetsu
Skip to content

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, and phase.
  • Periodic and pulse metrics over transient traces (accepting either signal or a windowed signal, start, stop form):
    • frequency (alias freq): dominant frequency in Hz from rising mean crossings.
    • period: dominant waveform period 1 / frequency in seconds (s).
    • duty_cycle (alias duty): pulse high-time percentage (%) above the (min + max) / 2 midpoint over complete rising-crossing cycles.
  • Power, distortion, and dynamic step metrics: output_power, efficiency, clipping, dissipation, rise_time, fall_time, settling_time, overshoot, energy, and thd (accepting 2-argument thd(signal, fundamental) over the full trace, 4-argument thd(signal, fundamental, start, stop), or 5-argument thd(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.