Expressions

One expression language runs everywhere a value can be computed: global variables, component parameters, SDD device equations, and measurements. Anywhere you can type a number, you can type an expression — `2*pi*freq0`, `polar(0.1, 35)`, `if(Vg > Vth, gm*Vg, 0)`.

Where expressions are used

circuitRF parses an expression once into a tree and evaluates it against a scope — it never does text substitution. That makes it fast (an SDD equation is parsed once, evaluated thousands of times) and correct (no fragile longest-name-first variable replacement).

Values: Real, Complex, Bool, String

Every value carries a kind:

• Real — a plain number. Component values like R, L, C are Real (50 stays 50, not 50+j0).

• Complex — appears as soon as the imaginary unit j enters, or from an operation that is mathematically complex (e.g. sqrt of a negative). Impedances resolve here. Write imaginary values with j*: j*4, 2 + j*3.

• Bool — the result of a comparison or logical operator; used only as a condition in if / ?:. A parameter that resolves to Bool is an error (a condition isn't a component value).

• String — a double-quoted literal ("spline", "path/to/x.s2p"). Storage only — no string operators. Used for genuinely textual parameters (the SnP block's File, InterpMode, …).

Operators & precedence

Lowest-binding (evaluated last) to highest-binding (tightest):

Constants & functions

Constants: j = (0,1), pi, e. These (and all function names) are reserved — a variable may not shadow them.

Units

A unit attaches in two places. At the assignment level (after the expression, or in the row's unit column) it scales the value by a linear factor — L = L1 nH, Z = 50 Ohm, M = 0.5 pH. And glued to a number inside the expression, with no space, it makes a unit literal — 10um + 1mil, 2.4GHz, 10V + 100mV — scaled to base SI as it is read. 2 GHz, with a space, is not a literal.

An expression holding a unit literal, or naming a variable declared with a unit, is already in base units, so the assignment's unit is not applied to its result; a bare number added to, subtracted from or compared with such a term takes that unit instead (w + 5 in mil is 5 mil more than w), and a bare number that multiplies or divides stays a number (2*w). See Units.

Variables, scope & cell parameters

Global variables (authored in a VAR block) are visible everywhere. Cell parameters pass top-down: an instance binds overrides in the parent scope; the cell evaluates its own defaults and component values in its own scope, then passes its scope down to its sub-cells. A name resolves to the local cell variable/parameter first, then the global — a cell never sees a parent's locals or a sibling's, which is what keeps a cell's meaning independent of where it's placed.

User-defined functions

Define a function whose body is an expression in the same language, with any number of parameters:

gm(vgs, vth) = beta * tanh(vgs - vth)

A call binds arguments positionally into a fresh scope whose parent is the definition's scope (so a user function sees globals, not the caller's locals). User functions compose with built-ins and with each other, and are subject to the same cycle detection.

Cycle detection & errors

circuitRF detects and rejects dependency cycles across the whole graph — global variables, cell-parameter defaults, and overrides — and reports the chain (e.g. a → b → a) rather than hanging. Every error names the offending text, never a silent zero or NaN:

• Cycle — the dependency chain.

• Unresolved name — the name and the scope it was sought in.

• Type error — Bool where a number is required; ordering on a complex operand; a non-Bool if condition.

• Arity / unknown function — wrong argument count or an undefined function.

• Domain — log(0), sqrt of a negative in a real SDD context, division by zero (reported with context).

See also: Measurements · The SDD · VAR component. Full design: docs/design/expressions.md.