kessetsu
Skip to content

Kessetsu Language Reference

On this page

This document describes Kessetsu 1.3.0. Kessetsu is line-oriented, case-sensitive except for documented device polarities, and uses // comments. Backends never consume syntax directly: source is parsed, flattened and validated into typed Circuit IR first.

Names and values

Identifiers begin with an ASCII letter and continue with letters, digits or _. Component and net names share a namespace and must be unique. Engineering values accept SI suffixes such as 10k, 2.2uF, 100mV, 1kHz, 45deg and 3%; the expected physical dimension is checked from context.

Nets, components and sources

net GND
net IN
net OUT

resistor R1 1k
capacitor C1 159.154943nF
inductor L1 10mH
diode D1 1N4148
transistor Q1 npn 2N3904
mosfet M1 IRF540
opamp U1 KESSETSU_OPAMP_V1

source VDC 5V
source VIN sine_ac(0V,100mV,1kHz,1V)
current_source IBIAS 1mA

Source waveforms are typed: scalar DC, sine(offset,amplitude,frequency), pulse(low,high,delay,rise,fall,width,period), pwl(time,value,...), ac(amplitude) and sine_ac(offset,amplitude,frequency,ac_amplitude). PWL requires at least two time/value pairs with non-negative, strictly increasing times. See supported domain for component and model limits.

Named quantities and arithmetic

param supply: V = 12V
param resistance: Ohm = 10k
param target_gain: ratio = 20
source VCC {supply}
resistor RG {resistance}
resistor RF {(target_gain - 1) * resistance}

Parameters are optional, declared at the top level or inside modules, and explicitly typed: Ohm, F, H, V, A, Hz, s, W, J, ratio, percent or deg. Forward references are allowed; duplicate/unknown names and dependency cycles produce errors. pi is read-only. Expressions support finite SI literals, names, parentheses, unary signs and + - * /, with ordinary precedence.

Braces are accepted in resistor, capacitor, inductor and scalar DC voltage/current-source values. A whole literal keeps contextual units (10k in an Ohm declaration); bare literals inside arithmetic are dimensionless. Use resistance + 1kOhm, not resistance + 1000. Percentages normalize to fractions during arithmetic (5% * 12V is 0.6 V), while a percent quantity/threshold is expressed in percentage points. Angles cannot become ratios.

Parameters do not infer topology or guarantee a named target: the circuit must explicitly use the relationship, then simulation/assertions verify its actual behavior. Supported waveform and analysis numeric fields also accept braced expressions; names, model fields and other non-numeric fields do not accept expressions in this slice. Inline assertions accept expressions in their thresholds and supported numeric measurement arguments. Kessetsu 1.2.0 accepts numeric root --param inputs; see the CLI contract. Module defaults and component expressions do not implicitly capture global or caller parameters. Evaluator-owned .kessreq files remain independent and assertion-only.

Independent module parameters

param base_cutoff: Hz = 500Hz
module RC(input,output,gnd) {
  param resistance: Ohm = 1k
  param cutoff: Hz = 1k
  param capacitance: F = 1 / (2 * pi * resistance * cutoff)
  resistor R1 {resistance}
  capacitor C1 {capacitance}
  connect input to R1.p1
  connect R1.p2, C1.p1 to output
  connect C1.p2 to gnd
}
use RC SLOW(cutoff={base_cutoff})
use RC FAST(cutoff={base_cutoff * 4})

This is a block-definition example, not a complete connected simulation. See the two-filter fixture for sources, external port connections, AC analysis and fixed assertions.

use RC DEFAULT keeps defaults. Named overrides accept whole literals with the child's declared unit (cutoff=500Hz, resistance=2k) or braced expressions evaluated in the caller's parameter scope. Defaults and component expressions use only the module's own parameters and pi; pass parent values explicitly. Nested instances follow the same rule. Each instance resolves independently, including forward references and recalculated defaults. Every parameter is overrideable, including calculated capacitance: choosing a standard capacitor does not guarantee the originally named cutoff target.

Duplicate/unknown overrides and incompatible units fail compilation. All default expressions must have valid names and units even when overridden. Dependency cycles are checked in effective definitions; an override may deliberately break a default cycle. Electrical IDs retain the existing underscore prefixes (SLOW_R1), while parameter provenance carries separate instance-path segments, defaults, overrides and qualified dependencies. Ambiguous flattened paths are rejected rather than silently renamed. Declared interface pins are checked by ERC. Module-local named nets are scoped too.

Put analyses and assertions at the root: parameterized module-local analysis/assertion contexts are not supported yet and fail explicitly. Kessetsu accepts root CLI inputs such as --param supply=15V; see the CLI contract for effective-source export and reproducibility. No model-name expressions, automatic topology generation or extra editor panel is introduced.

Compilation safety

Source builds bound input to 8 MiB and 100,000 parsed declarations/statements; module expansion also stops at 100,000 statements and 64 instance levels. At most 4,096 effective parameter definitions are accepted across the expanded circuit. Each arithmetic expression is limited to 16 KiB, 1,024 nodes and depth 64. Parsing, elaboration and numeric conversion have separate 1,000,000-node expression-work ceilings; these are bounded passes, not an execution-time guarantee or a claimed single aggregate operation count. Oversized/unsupported input fails with diagnostics, without backend artifacts. Waveforms accept numeric arguments, not nested waveform/function calls. Existing literal/quoted waveforms remain supported.

Parameter diagnostics carry the actual declaration or supplied module-override location, including nested instances. Default provenance still identifies its original declaration. These precise parameter origins do not imply every ERC/component/measurement diagnostic has a complete source map.

Connections and pins

connect VIN.plus to IN
connect VIN.minus, C1.p2 to GND
connect R1.p1 to IN
connect R1.p2, C1.p1 to OUT

Canonical pins are p1/p2 for two-terminal passives and diodes, plus/minus for sources, c/b/e for BJTs, d/g/s for MOSFETs and in_p/in_n/vcc/vee/out for op-amps. Every required pin must be connected. GND is the reference net; ambiguous or missing reference topology fails ERC.

Analyses and assertions

Parameterized excitation and analyses

param amplitude: V = 1V
param frequency: Hz = 1kHz
param period: s = 1 / frequency
param points: ratio = 80
source VIN sine_ac(0V,{amplitude},{frequency},{amplitude})
simulate ac dec {points} {frequency / 100} {frequency * 100}
simulate tran {period / 100} {period * 10}

This excerpt illustrates numeric fields; the complete RC fixture includes connections and fixed requirements. One frequency controls the excitation, the AC range and a ten-period transient window without duplicating numbers. Existing literal syntax remains valid; use braces only where a formula or parameter is useful.

All numeric arguments of unquoted ac, sine, sine_ac, pulse and pwl calls accept expressions. Voltage/current levels use the source's unit, frequency uses Hz, and times use seconds. PWL keeps its alternating time/value arguments and increasing-time checks. Legacy quoted SPICE-style waveforms remain literal-only: do not put {name} inside quotes. Module waveform expressions use the module's own parameter scope, including overrides.

Transient step/stop, AC points/start/stop and DC start/stop/step accept expressions. AC points must resolve to a positive dimensionless integer within the supported unsigned 32-bit range; param points: ratio = 80 is the straightforward declaration. Scale keywords (dec, oct, lin) and DC source names are not numeric fields. Existing analysis arity, unit, sweep-direction and uniqueness checks apply after values resolve. Put analyses at the circuit root. Independently owned requirements cannot refer to design parameters. For combined AC/transient simulations, use explicit transient time windows when asserting waveform reductions such as RMS.

Parameterized inline measurements

param settling: s = 2ms
param duration: s = 10ms
param frequency: Hz = 1kHz
param maximum: V = 0.55V
assert rms(V(OUT),{settling},{duration}) < {maximum}
assert gain_at(V(OUT),V(IN),{frequency}) > 0.70

An excerpt, not a complete circuit; the measurement fixture provides connections, excitation and analyses. Threshold units come from the metric: V/A/W for voltage/current/power reductions, ratio for gain, Hz for frequency/cutoff, degrees for phase and percent for THD/clipping/efficiency. Whole-literal shorthand remains contextual; named or compound expressions must have compatible dimensions.

Supported numeric arguments are transient start/stop windows for reductions, output_power, dissipation and efficiency; target/reference frequency for gain_at, phase and cutoff edges; THD fundamental/time window; and clipping voltage rails. Signals, load/device names and THD's hann keyword remain literal. Measurement semantics/interpolation are unchanged. Expressions resolve to typed quantities before simulation, not substituted SPICE text. Place parameterized assertions at the root; module-local target qualification is not supported.

These are design-owned checks: a parameterized limit changes if you explicitly edit its definition. Do not derive a fixed acceptance limit from the value being tested merely to make a failing design pass. Independent .kessreq files remain literal-only and reject braced expressions, even constants; design parameters cannot change evaluator-owned limits.

Literal analyses and requirements

simulate op
simulate tran 10us 5ms
simulate ac dec 30 10Hz 10MHz
simulate dc VIN -1V 1V 10mV

assert gain(V(OUT),V(IN)) > 9.9
assert rms(V(OUT),2ms,5ms) < 6V
assert peak(V(Q1.c,Q1.e)) < 40V

Analysis arguments and assertions are dimension checked. Operating-point, transient, and AC analyses may each appear once; a DC sweep may appear once per independent source. Unsupported assertion metrics and ambiguous repeated analyses fail semantic validation before simulation. Missing signals or incompatible datasets become explicit errors, never implicit zeroes. Full formulas and sign conventions are in engineering measurements; execution behavior is in simulation and assertions.

An evaluator-owned .kessreq file uses the same assertion syntax but permits only comments and one or more assert statements. It is supplied to kess test with --requirements; a design using that option must not also define inline assertions. This is a CLI composition contract, not a second language or a backend bypass.

Modules

Modules provide reusable topology. A module instance is flattened before semantic analysis; backend-specific module shortcuts do not exist.

For complete parameterized filter/amplifier circuits and a step-by-step workflow, see reuse a circuit block. Module definitions are source-local, not imported circuit packages. Structured instance paths survive in IR interface metadata independently of flattened electrical identifiers.

module divider(p1,p2) {
  resistor TOP 10k
  resistor BOTTOM 10k
  connect p1 to TOP.p1
  connect TOP.p2 to BOTTOM.p1
  connect BOTTOM.p2 to p2
}

use divider DIV1

Physical part assignments

An electrical component may carry a separate physical-part assignment:

resistor R1 10k
part R1 manufacturer="Yageo" mpn="RC0603FR-0710KL" footprint="Resistor_SMD:R_0603_1608Metric" pin_map="p1:1,p2:2" average_dissipation_limit="0.1W" average_dissipation_conditions="70 C ambient; apply manufacturer derating" rating_source="User-supplied manufacturer record" note="Verify stock before build"

Identity/handoff fields are manufacturer, mpn, footprint, pin_map and note; omit unknown information instead of using a guessed placeholder. A pin map is optional, but when present it requires a footprint and must map every logical catalog pin exactly once to a unique physical pad.

Optional provided-rating pairs are:

  • peak_voltage_limit (V) with peak_voltage_conditions;
  • peak_current_limit (A) with peak_current_conditions;
  • average_dissipation_limit (W) with average_dissipation_conditions.

Every limit must be a finite positive typed quantity and its matching conditions are mandatory. rating_source is an optional user-supplied citation shared by the ratings on that assignment; a rating without it is explicitly user-entered, not silently verified. simulate and test compare available model stress against these values in the separate kessetsu.part-stress.v1 report. Peak voltage uses the component's canonical terminal pair, peak current uses its supported device current, and average dissipation uses positive transient power. Unsupported models or missing analysis data are reported as unavailable. Exceeding a provided rating is prominent but advisory: it does not replace explicit design/evaluator assertions or change their exit status.

The assignment is stored in the versioned physical-part manifest and never changes component value, model, connectivity or generated simulation netlist.

Place part beside a component inside a module to assign each flattened instance independently. A module interface itself is virtual and cannot receive a physical part. Manufacturer identity is not a device model, footprint choice is not pin mapping, and a supplied limit is not proof of full datasheet compliance, safe operating area, thermal safety or availability. Independent voltage/current sources are simulation stimuli and are not BOM parts; represent a real sourced device through an appropriate typed component.

Typed models and packages

model diode SafeD version=1.0.0 license=MIT Is=2e-9 Rs=0.5
model bjt SafeN npn version=1.0.0 license=MIT Is=1e-12 Bf=100
model_include kessetsu_analog 1.0.0
external_subcircuit opamp OPA197 (in_p,in_n,vcc,vee,out) file="models/OPAx197.LIB" entry=OPAx197 sha256=<64-hex-digest> version="Final 1.3" license="vendor terms" source="vendor URL" simulator=ngspice_ps redistribution=prohibited

Raw .include, .model, .subckt and .control injection is intentionally rejected. Model kinds have parameter allowlists; package imports require an exact version and produce a provenance-bearing kessetsu.lock. External declarations bind a user-owned source-relative file by exact SHA-256, entry name, canonical pin order, provenance, simulator mode, and redistribution policy. Ordinary reports/exports never embed its body. Native stdin cannot bind files; native file commands resolve contained local files. The model cookbook shows the complete directory, hash and command workflow.

Additional external interfaces

Use external_subcircuit comparator Name (in_p,in_n,vcc,vee,out) or external_subcircuit two_terminal Name (p1,p2) with the same required metadata fields shown above, then instantiate with device U1 Name or device X1 Name. The model determines the catalog-backed interface; device cannot masquerade as an op-amp or infer arbitrary pin lists. Header defaults/continuations are supported; positional terminal count excludes .SUBCKT parameter defaults. By default, coefficients stay in the exact file. A declaration may explicitly expose existing header parameters with instance_parameters="Rinit:Ohm,Vt:V"; instances then use device XM Name (Rinit={initial_resistance}, Vt=1.6V) (or the same parenthesized form after an external opamp). Names are matched case-insensitively but emitted using the declared spelling. Unknown names, duplicates, missing library defaults and unit mismatches fail closed; the library body is never rewritten.

Development Web builds allow explicit local selection in View → Circuit details. Only the portable self-contained Ngspice profile can simulate in the browser; PSpice compatibility/unsupported constructs require native CLI. Files stay in memory, not in drafts/shares/exports. See the model catalog for complete examples, supported setups, licenses and dependency handling.

For models that require capacitor initial conditions, Kessetsu 1.2.0 accepts simulate tran <step> <stop> uic. This skips the DC operating point and applies the model's initial conditions; it is not the default. Ordinary transient forms and legacy analysis serialization are unchanged.

Compatibility rule

Unknown statements, components, pins, metrics, waveform arguments and analysis forms fail closed with source-located diagnostics. A future syntax addition must preserve every existing examples/*.kess program or explicitly introduce a new language/schema version.