Specification

Overview

Zener is a domain-specific language built on top of Starlark for describing PCB schematics. It provides primitives for defining components, symbols, nets, interfaces, and modules in a type-safe, composable manner. This specification describes the language extensions and primitives added on top of Starlark. For the base Starlark language features, please refer to the Starlark specification and the starlark-rust types extension.

Evaluation Model
Core Types
Built-in Functions
Module System
Type System

Evaluation Model

Files as Modules

Each .zen file is a Starlark module. It can be used in two ways:

Its exported symbols can be load()ed into other modules. For example, load("./MyFile.zen", "MyFunction", "MyType") will load the MyFunction and MyType symbols from the MyFile.zen module.
It can be loaded as a schematic module using the Module() helper. For example, MyFile = Module("./MyFile.zen") will import MyFile.zen as a schematic module, which you can instantiate like so:
```
MyFile = Module("./MyFile.zen")
MyFile(
    name = "MyFile",
    ...
)
```

Load Resolution

The load() and Module() statements support multiple resolution strategies:

# Local file (relative to current file)
load("./utils.zen", "helper")

# Package reference
load("@stdlib:1.2.3/math.zen", "calculate")

# GitHub repository
load("@github/user/repo:branch/path.zen", "function")

# GitLab repository
load("@gitlab/user/repo:branch/path.zen", "function")

# GitLab repository (nested groups)
Symbol(library = "@gitlab/kicad/libraries/kicad-symbols:v7.0.0/Device.kicad_sym", name = "R_US")

Default Package Aliases

Zener provides built-in package aliases for commonly used libraries:

@kicad-footprints → @gitlab/kicad/libraries/kicad-footprints:9.0.0
@kicad-symbols → @gitlab/kicad/libraries/kicad-symbols:9.0.0
@stdlib → @github/diodeinc/stdlib:HEAD

These can be used directly:

# Load from stdlib
load("@stdlib/units.zen", "kohm", "uF")

# Load from KiCad symbols library
R_symbol = Symbol(library = "@kicad-symbols/Device.kicad_sym", name = "R")

Custom Package Aliases

You can define custom package aliases or override the defaults in your workspace’s pcb.toml:

[packages]
# Override default version
kicad-symbols = "@gitlab/kicad/libraries/kicad-symbols:7.0.0"

# Add custom aliases
my-lib = "@github/myorg/mylib:v1.0.0"
local-lib = "./path/to/local/lib"

Core Types

Net

A Net represents an electrical connection between component pins.

# Create a net with optional name
net1 = Net()
net2 = Net("VCC")

Type: Net
Constructor: Net(name="")

name (optional): String identifier for the net

Symbol

A Symbol represents a schematic symbol definition with its pins. Symbols can be created manually or loaded from KiCad symbol libraries.

# Create a symbol from explicit definition
my_symbol = Symbol(
    name = "MyDevice",
    definition = [
        ("VCC", ["1", "8"]),    # VCC on pins 1 and 8
        ("GND", ["4"]),         # GND on pin 4
        ("IN", ["2"]),          # IN on pin 2
        ("OUT", ["7"])          # OUT on pin 7
    ]
)

# Load from a KiCad symbol library
op_amp = Symbol(library = "./symbols/LM358.kicad_sym")

# For multi-symbol libraries, specify which symbol
mcu = Symbol(library = "./symbols/microcontrollers.kicad_sym", name = "STM32F103")

# Shorthand syntax: library path and symbol name in one string
gnd = Symbol("@kicad-symbols/power.kicad_sym:GND")
resistor = Symbol("./symbols/passives.kicad_sym:R_0402")

# For single-symbol libraries, the name can be omitted
op_amp = Symbol("./symbols/LM358.kicad_sym")

Type: Symbol
Constructor: Symbol(library_spec=None, name=None, definition=None, library=None)

library_spec: (positional) String in format “library_path:symbol_name” or just “library_path” for single-symbol libraries
name: Symbol name (required when loading from multi-symbol library with named parameters)
definition: List of (signal_name, [pad_numbers]) tuples
library: Path to KiCad symbol library file

Note: You cannot mix the positional library_spec argument with the named library or name parameters.

Component

Components represent physical electronic parts with pins and properties.

# Using a Symbol for pin definitions
my_symbol = Symbol(
    definition = [
        ("VCC", ["1"]),
        ("GND", ["4"]),
        ("OUT", ["8"])
    ]
)

Component(
    name = "U1",                   # Required: instance name
    footprint = "SOIC-8",          # Required: PCB footprint
    symbol = my_symbol,            # Symbol defines the pins
    pins = {                       # Required: pin connections
        "VCC": vcc_net,
        "GND": gnd_net,
        "OUT": output_net
    },
    prefix = "U",                  # Optional: reference designator prefix (default: "U")
    mpn = "LM358",                 # Optional: manufacturer part number
    type = "op-amp",               # Optional: component type
    properties = {                 # Optional: additional properties
        "voltage": "5V"
    }
)

Type: Component
Constructor: Component(**kwargs) Key parameters:

name: Instance name (required)
footprint: PCB footprint (required)
symbol: Symbol object defining pins (required)
pins: Pin connections to nets (required)
prefix: Reference designator prefix (default: “U”)
mpn: Manufacturer part number
type: Component type
properties: Additional properties dict

Interface

Interfaces define reusable connection patterns with field specifications, type validation, and promotion semantics.

Basic Syntax

InterfaceName = interface(
    field_name = field_specification,
    __post_init__ = callback_function,  # Optional
)

Field Types

Net Instances: Use the provided Net instance as the default template

NET = Net("VCC", symbol = Symbol(library = "@kicad-symbols/power.kicad_sym", name = "VCC"))
SDA = Net("I2C_SDA")

Interface Instances: Use the provided interface instance for composition

uart = Uart(TX=Net("UART_TX"), RX=Net("UART_RX"))
power = Power(NET=Net("VDD"))

field() Specifications: Enforce type checking with explicit defaults

voltage = field(Voltage, unit("3.3V", Voltage))
freqs = field(list[str], ["100kHz", "400kHz"])
count = field(int, 42)

using() Specifications: Mark fields as promotion targets for automatic type conversion

NET = using(Net("VCC"))
uart = using(Uart())

Interface Instantiation

InterfaceName([name], field1=value1, field2=value2, ...)

Optional name: First positional argument sets the interface instance name
Field overrides: Named parameters override defaults
Type validation: Values must match field specifications

Examples

# Define interfaces
Power = interface(
    NET = using(Net("VCC", symbol = Symbol(library = "@kicad-symbols/power.kicad_sym", name = "VCC"))),
    voltage = field(Voltage, unit("3.3V", Voltage)),
)

Uart = interface(
    TX = Net("UART_TX"),
    RX = Net("UART_RX"),
)

SystemInterface = interface(
    power = using(Power()),
    uart = using(Uart()),
    debug = field(bool, False),
)

# Create instances
power = Power()                                      # All defaults
vcc = Power("VCC_3V3")                               # Named instance
custom = Power("MAIN", voltage=unit("5V", Voltage))  # Named with override

system = SystemInterface("MAIN", debug=True)

Promotion Semantics

Fields marked with using() enable automatic type promotion when passing interfaces across module boundaries: Rules:

Unique promotion targets: Only one using() field per type per interface - duplicate promotion targets to the same type are not allowed
Cross-module promotion: Automatic conversion when crossing module boundaries
Same-module access: Explicit field access required within same module
Type safety: Promotion only occurs when target type exactly matches the expected type

# Valid: Single promotion target per type
Power = interface(
    NET = using(Net("VCC")),        # Only Net promotion target
    voltage = field(Voltage, ...),
)

# Invalid: Multiple promotion targets for same type
InvalidInterface = interface(
    NET1 = using(Net("VCC")),       # Error: duplicate Net promotion target
    NET2 = using(Net("GND")),       # Error: duplicate Net promotion target
)

# Automatic promotion when passed to modules
Resistor("R1", "10kOhm", "0603", P1=power, P2=gnd)  # power promotes to power.NET

# Explicit access within same module
net = power.NET  # Must use .NET explicitly

Post-Initialization Callbacks

def _power_post_init(self):
    if self.voltage.value <= 0:
        error("Power voltage must be positive")

Power = interface(
    NET = using(Net("VCC")),
    voltage = field(Voltage, unit("3.3V", Voltage)),
    __post_init__ = _power_post_init,
)

Callbacks receive self and cannot be overridden during instantiation. Type: interface
Constructor: interface(**fields)

Fields can be Net instances, interface instances, field() specifications, or using() specifications

Module

Modules represent hierarchical subcircuits that can be instantiated multiple times. Module objects support indexing to access child components and submodules directly.

# Load a module from a file
SubCircuit = Module("./subcircuit.zen")

# Instantiate the module
SubCircuit(
    name = "power_supply",
    # ... pass inputs defined by io() and config() in the module
)

# Access child components and submodules via indexing
component = module["ComponentName"]     # Access component by name
submodule = module["SubmoduleName"]     # Access submodule by name

# Chain indexing for nested access
nested_component = module["SubmoduleName"]["ComponentName"]

# Nested path syntax (equivalent to chained indexing)
nested_component = module["SubmoduleName.ComponentName"]  # Same as above

# Check if components exist using membership operator
if "ComponentName" in module:
    component = module["ComponentName"]

# Check nested paths
if "SubmoduleName.ComponentName" in module:
    nested_component = module["SubmoduleName.ComponentName"]

Type: Module
Constructor: Module(path) Module Indexing: module[name] supports:

Single names: module["ComponentName"] returns Component or Module objects
Nested paths: module["Sub.Component"] equivalent to module["Sub"]["Component"]
Deep nesting: module["A.B.C"] equivalent to module["A"]["B"]["C"]
Returns Component objects for leaf components, Module objects for intermediate submodules
Raises an error if any part of the path is not found

Module Membership: name in module supports:

Single names: "ComponentName" in module checks if component or submodule exists
Nested paths: "Sub.Component" in module equivalent to checking nested existence
Returns True if the path exists, False otherwise
Works with the same path syntax as indexing

Module Attributes:

module.nets: Dict mapping net names to lists of connected port tuples
module.components: Dict mapping component paths to component objects

Naming Conventions:

Component paths in module.components follow the pattern SubmoduleName.ComponentName (e.g., "BMI270.BMI270", "C1.C")
The first part is the submodule name, the second part is the component name within that submodule
Indexing supports both single names and nested paths:
- module["BMI270"] returns the BMI270 submodule
- module["BMI270"]["BMI270"] returns the component within the submodule (chained)
- module["BMI270.BMI270"] also returns the component (nested path syntax)
All three approaches are equivalent for accessing nested components

TestBench

TestBench values represent the results of module validation tests. They are created by the TestBench() function and contain information about the tested module and check results.

# TestBench values are returned by TestBench()
result = TestBench(
    name = "MyTest",
    module = MyModule,
    checks = [check_func1, check_func2]
)

# Access TestBench properties
print(result)  # TestBench(MyTest)

Type: TestBench
Created by: TestBench() function (see Built-in Functions) Properties accessible via the TestBench value:

name: The test bench identifier
Module evaluation status
Check function results

PhysicalRange

A PhysicalRange represents a bounded range of physical values with an optional nominal value, used for specifying operating ranges, tolerances, and electrical characteristics. Ranges have minimum and maximum bounds with consistent physical units.

# PhysicalRange values are created by unit-specific range constructors
# (See builtin.physical_range() in Built-in Functions)

# String parsing with range separators
voltage_range = VoltageRange("1.1–3.6V")              # 1.1–3.6 V
supply_range = VoltageRange("11V to 26V")             # 11–26 V

# With nominal value in parentheses
input_range = VoltageRange("11–26 V (12 V nom.)")     # 11–26 V (12 V nom.)

# Tolerance expansion
nominal_voltage = VoltageRange("15V 10%")             # 13.5–16.5 V

# From PhysicalValue
single_point = VoltageRange(Voltage(15))              # 15–15 V

# Keyword arguments
operating_range = VoltageRange(min=11, nominal=16, max=26)  # 11–26 V (16 V nom.)

# Mixed string/number keywords
custom_range = VoltageRange(min="11V", nominal="16", max="26V")  # 11–26 V (16 V nom.)

# Override nominal separately
with_nominal = VoltageRange("11V to 26V", nominal="16V")  # 11–26 V (16 V nom.)

Type: PhysicalRange Created by: Unit-specific range constructors (e.g., VoltageRange, CurrentRange) Properties:

min: Minimum value (Decimal)
max: Maximum value (Decimal)
nominal: Optional nominal/typical value (Decimal or None)
unit: Physical unit dimensions

Display Format:

With nominal: 11–26 V (12 V nom.)
Without nominal: 11–26 V

PhysicalRangeType

A PhysicalRangeType is a factory type that creates PhysicalRange instances for a specific physical unit. Each unit has its own range type (e.g., VoltageRange for volts, CurrentRange for amperes).

# Range types are created by builtin.physical_range()
VoltageRange = builtin.physical_range("V")
CurrentRange = builtin.physical_range("A")

# Range types are callable and return PhysicalRange instances
input_voltage = VoltageRange("3.3V to 5V")
load_current = CurrentRange("100mA to 500mA")

Type: PhysicalRangeType Created by: builtin.physical_range(unit) (see Built-in Functions) Standard Range Types (available in @stdlib/units.zen):

VoltageRange - Voltage ranges (V)
CurrentRange - Current ranges (A)
ResistanceRange - Resistance ranges (Ω)
CapacitanceRange - Capacitance ranges (F)
InductanceRange - Inductance ranges (H)
FrequencyRange - Frequency ranges (Hz)
TemperatureRange - Temperature ranges (K)
TimeRange - Time ranges (s)
PowerRange - Power ranges (W)

Construction Flexibility: Range constructors accept multiple input formats for maximum flexibility:

String parsing with separators:
- En-dash: "1.1–3.6V"
- Word “to”: "11V to 26V"
- Left side can omit unit: "11–26V"
Nominal value extraction:
- Parenthesized suffix: "11–26 V (12 V nom.)"
- Can be combined with string ranges or keyword override
Tolerance expansion:
- Percentage tolerance: "15V 10%" expands to 13.5–16.5 V
PhysicalValue conversion:
- Single value: VoltageRange(Voltage(15)) creates point range 15–15 V
- Toleranced value: VoltageRange(Voltage(15, 0.1)) expands tolerance to range
Keyword arguments:
- Explicit bounds: min=11, max=26
- With nominal: min=11, nominal=16, max=26
- Accepts numbers or strings: min="11V", max="26V"
Mixed modes:
- String range with keyword nominal: VoltageRange("11V to 26V", nominal="16V")

Type Safety:

Units must be consistent across min, max, and nominal values
Range types are distinct: VoltageRange ≠ CurrentRange
Type checking enforces unit correctness at compile time

Use Cases:

Component operating ranges: input_voltage = VoltageRange("2.7V to 5.5V")
Load specifications: output_current = CurrentRange("0A to 3A")
Environmental conditions: operating_temp = TemperatureRange("-40C to 85C")
Future: Electrical Rule Checking (ERC) - validate that supply ranges satisfy load requirements

Built-in Functions

moved(old_path, new_path)

Parameters

old_path: The old path that should be remapped
new_path: The new path to remap to

The moved() directive allows you to specify path remapping for refactoring support. When modules or components are moved or renamed, downstream artifacts (like layout files) may still reference the old paths. The moved() directive provides a mapping from old paths to new paths. moved() directives are scoped to the module where they are defined. They affect how paths from that module are resolved in downstream artifacts. If the path refers to a module, all children of that module are automatically remapped:

# This single directive handles:
# POW.PS1 -> PS1
# POW.PS1.some_resistor -> PS1.some_resistor  
# POW.PS1.inner.component -> PS1.inner.component
moved("POW.PS1", "PS1")

# Moved a power supply module from POW namespace to root
moved("POW.PS1", "PS1")

# Renamed a component
moved("OLD_COMP", "NEW_COMP")

# Moved components between modules
moved("ModuleA.ComponentX", "ModuleB.ComponentX")

# Net remapping for position comments
moved("AN_OLD_FILTERED_VCC_VCC", "FILTERED_VCC_VCC")

io(name, type, checks=None, default=None, optional=False)

Declares a net or interface input for a module.

# Required net input
vcc = io("vcc", Net)

# Optional interface input with default
PowerInterface = interface(vcc = Net, gnd = Net)
power = io("power", PowerInterface, optional=True)

# With explicit default
data = io("data", Net, default=Net("DATA"))

# With validation checks (single function)
def check_voltage_within(within):
    def check_fn(power_value):
        voltage = power_value.voltage
        check(voltage.min >= within.min and voltage.max <= within.max,
              f"Voltage {voltage} not within {within}")
    return check_fn

vbat = io("VBAT", Power, check_voltage_within(VoltageRange("10–30 V")))

# Or with multiple checks as a list
vbat = io("VBAT", Power, [check_voltage_within(VoltageRange("10–30 V")), check_current()])

# Or as a named argument
vbat = io("VBAT", Power, checks=check_voltage_within(VoltageRange("10–30 V")))

Parameters:

name: String identifier for the input (positional)
type: Expected type - Net or interface type (positional)
checks: Optional check function or list of check functions to run on the value at eval time (3rd positional or named)
default: Default value if not provided by parent (named)
optional: If True, returns None when not provided (unless default is specified) (named)

config(name, type, default=None, convert=None, optional=False)

Declares a configuration value input for a module.

# String configuration
prefix = config("prefix", str, default="U")

# Integer with conversion
baudrate = config("baudrate", int, convert=int)

# Enum configuration
Direction = enum("NORTH", "SOUTH", "EAST", "WEST")
heading = config("heading", Direction)

# Optional configuration
debug = config("debug", bool, optional=True)

Parameters:

name: String identifier for the input
type: Expected type (str, int, float, bool, enum, or record type)
default: Default value if not provided
convert: Optional conversion function
optional: If True, returns None when not provided (unless default is specified)

File(path)

Resolves a file or directory path using the load resolver.

# Get absolute path to a file
config_path = File("./config.json")

# Works with load resolver syntax
stdlib_path = File("@stdlib/components")

Path(path, allow_not_exist=False)

Advanced path resolution supporting all LoadSpec formats with optional existence checking.

# Basic path resolution (same as File)
config_path = Path("./config.json")

# LoadSpec format support
stdlib_path = Path("@stdlib/components")
github_path = Path("@github/user/repo:branch/path.zen")

# Allow non-existent paths (only works with local paths)
optional_file = Path("./optional.zen", allow_not_exist=True)

Parameters:

path: String path to resolve (supports any LoadSpec format)
allow_not_exist: Optional boolean (default: False). If True, allows non-existent paths. Can only be used with local path LoadSpecs, not package/GitHub/GitLab specs.

error(msg)

Raises a runtime error with the given message.

if not condition:
    error("Condition failed")

check(condition, msg)

Checks a condition and raises an error if false.

check(voltage > 0, "Voltage must be positive")
check(len(pins) == 8, "Expected 8 pins")

add_property(name, value)

Adds a property to the current module instance.

add_property("layout_group", "power_supply")
add_property("critical", True)

builtin.physical_range(unit)

Built-in function that creates unit-specific range constructor types for defining bounded physical value ranges.

# Create range constructors for different units
VoltageRange = builtin.physical_range("V")
CurrentRange = builtin.physical_range("A")
ResistanceRange = builtin.physical_range("Ohm")
CapacitanceRange = builtin.physical_range("F")
InductanceRange = builtin.physical_range("H")
FrequencyRange = builtin.physical_range("Hz")
TemperatureRange = builtin.physical_range("K")
TimeRange = builtin.physical_range("s")
PowerRange = builtin.physical_range("W")

# Use the constructors to create ranges
input_voltage = VoltageRange("2.7V to 5.5V")
output_current = CurrentRange("0A to 3A")
operating_temp = TemperatureRange("-40C to 85C")

# All construction patterns are supported
supply = VoltageRange("11–26 V (12 V nom.)")           # String with nominal
tolerance = VoltageRange("15V 10%")                    # Tolerance expansion
explicit = VoltageRange(min=11, nominal=16, max=26)    # Keyword arguments
from_value = VoltageRange(Voltage(15))                 # From PhysicalValue
mixed = VoltageRange("11V to 26V", nominal="16V")      # Mixed modes

Parameters:

unit: String identifier for the physical unit (e.g., "V", "A", "Ohm", "F", "H", "Hz", "K", "s", "W")

Returns: A PhysicalRangeType that can be called to create PhysicalRange instances Standard Usage: This builtin is typically accessed through @stdlib/units.zen, which provides pre-defined range constructors:

load("@stdlib/units.zen", "VoltageRange", "CurrentRange", "ResistanceRange")

# Use standard constructors from stdlib
input_range = VoltageRange("3.3V to 5V")
load_range = CurrentRange("100mA to 500mA")
pullup_range = ResistanceRange("4.7kOhm to 10kOhm")

Available in stdlib/units.zen:

VoltageRange - Voltage ranges (V)
CurrentRange - Current ranges (A)
ResistanceRange - Resistance ranges (Ω)
CapacitanceRange - Capacitance ranges (F)
InductanceRange - Inductance ranges (H)
FrequencyRange - Frequency ranges (Hz)
TemperatureRange - Temperature ranges (K)
TimeRange - Time ranges (s)
PowerRange - Power ranges (W)

Construction Patterns: The returned range constructor accepts flexible input formats:

# String parsing with range separators
VoltageRange("1.1–3.6V")           # En-dash separator
VoltageRange("11V to 26V")         # Word "to" separator
VoltageRange("11–26V")             # Left side can omit unit

# Nominal value in parentheses
VoltageRange("11–26 V (12 V nom.)")

# Tolerance expansion
VoltageRange("15V 10%")            # Expands to 13.5–16.5 V

# From PhysicalValue
VoltageRange(Voltage(15))          # Single point: 15–15 V
VoltageRange(Voltage(15, 0.1))     # With tolerance: 13.5–16.5 V

# Keyword arguments (all must be present)
VoltageRange(min=11, max=26)
VoltageRange(min=11, nominal=16, max=26)

# Mixed string/number keywords
VoltageRange(min="11V", nominal="16", max="26V")

# Override nominal separately
VoltageRange("11V to 26V", nominal="16V")

Type Safety:

Units must be consistent: VoltageRange("5V to 3A") → Error (mixing V and A)
Range types are distinct: Cannot pass a VoltageRange where CurrentRange is expected
Type checking enforces correctness at compile time

Use Cases: Physical ranges are used to specify operating characteristics, constraints, and requirements:

# Component specifications
input_voltage = VoltageRange("2.7V to 5.5V")
output_current = CurrentRange("0A to 3A (1.5A nom.)")
operating_temp = TemperatureRange("-40C to 85C")

# Load requirements
supply_current = CurrentRange("10mA to 100mA")
clock_frequency = FrequencyRange("1MHz to 100MHz")

# Tolerance specifications
capacitance = CapacitanceRange("100nF 10%")  # 90nF to 110nF
resistance = ResistanceRange("10kOhm 5%")    # 9.5kΩ to 10.5kΩ

# Future: Electrical Rule Checking (ERC)
# Validate that supply ranges satisfy load requirements
# check(supply_voltage_range.contains(load_voltage_range))

See PhysicalRange in Core Types for detailed information about the returned range values.

builtin.add_board_config(name, config, default=False)

Built-in function for registering board configurations with the layout system. Parameters:

name: String identifier for the board configuration
config: BoardConfig object containing design rules and stackup
default: If True, this becomes the default board config for the project

This builtin is typically called through the stdlib Board() function rather than directly.

builtin.add_electrical_check(name, check_fn, inputs=None)

Built-in function for registering electrical validation checks that run during pcb build. Parameters:

name: String identifier for the check (required)
check_fn: Function to execute for validation (required)
inputs: Optional dictionary of input parameters to pass to the check function

Electrical checks use lazy evaluation - they are registered during module evaluation but execute after the design is fully evaluated. This allows checks to validate electrical properties, design rules, or other constraints across the entire design. The check function receives the module as its first argument, followed by any specified inputs as keyword arguments:

def voltage_range_check(module, min_voltage, max_voltage):
    """Check that supply voltage is within acceptable range"""
    supply = module.supply_voltage
    if supply < min_voltage or supply > max_voltage:
        error("Supply voltage {} is outside range {}-{}".format(
            supply, min_voltage, max_voltage
        ))

builtin.add_electrical_check(
    name="supply_voltage_range",
    check_fn=voltage_range_check,
    inputs={
        "min_voltage": 3.0,
        "max_voltage": 5.5,
    }
)

Check Function Signature:

def check_function(module, **kwargs):
    # Validation logic
    # Raise error() or fail assertion to indicate failure
    pass

Example - Basic Check:

def check_no_floating_nets(module):
    """Ensure all nets are connected to at least 2 pins"""
    for net in module.nets:
        if len(net.pins) < 2:
            error("Net '{}' is floating (only {} pin connected)".format(
                net.name, len(net.pins)
            ))

builtin.add_electrical_check(
    name="no_floating_nets",
    check_fn=check_no_floating_nets
)

Example - Parameterized Check:

def check_power_capacity(module, max_current):
    """Verify power supply can handle load current"""
    total_load = sum([c.max_current for c in module.components])
    if total_load > max_current:
        error("Total load current {}A exceeds supply capacity {}A".format(
            total_load, max_current
        ))

builtin.add_electrical_check(
    name="power_capacity",
    check_fn=check_power_capacity,
    inputs={"max_current": 3.0}
)

Execution Model:

Checks are registered during module evaluation via builtin.add_electrical_check()
Check functions and inputs are stored as frozen values
During pcb build, after evaluation completes, all checks are collected from the module tree
Each check executes with a fresh evaluator context
Check failures generate error diagnostics that are reported through the standard diagnostic system
Build fails if any electrical checks fail

Notes:

Checks run only during pcb build, not during pcb test (use TestBench for test-specific validation)
Check failures generate error-level diagnostics
Checks can access the entire module structure, including components, nets, interfaces, and properties
Multiple checks with the same name are allowed (they execute independently)

Board Configuration Types

The board configuration record types are provided by @stdlib/board_config.zen and offer comprehensive control over PCB manufacturing specifications. Available Records and Functions:

load("@stdlib/board_config.zen", 
    "Board",              # Board configuration function
    "BoardConfig",        # Main configuration container
    "DesignRules",        # Design rule constraints  
    "Stackup",            # Layer stackup definition
    "Material",           # Material properties
    "CopperLayer",        # Copper layer specification
    "DielectricLayer",    # Dielectric layer specification
    "Constraints",        # Manufacturing constraints
    "Copper",             # Copper-specific rules
    "NetClass",           # Netclass definitions
    "merge_configs",      # Configuration merging utility
    "deep_merge"          # Deep merge utility
)

Board(name, layout_path, config=None, layers=None, layout_hints=None, default=False)

Stdlib function for declaring board configurations for PCB layout generation.

# Load from stdlib
load("@stdlib/board_config.zen", "Board", "BoardConfig", "DesignRules", "Stackup", "Material", "CopperLayer", "DielectricLayer")

# Simple usage with predefined layer count (recommended for most projects)
Board(
    name="MyBoard",
    layout_path="layout/",
    layers=4,
    default=True
)

# Advanced usage with custom configuration
config = BoardConfig(
    stackup=Stackup(
        materials=[
            Material(
                name="FR-4",
                vendor="Isola",
                relative_permittivity=4.21,
                loss_tangent=0.025,
                reference_frequency=1e9,
            ),
        ],
        silk_screen_color="#44805BFF",
        solder_mask_color="#191919E6",
        thickness=1.605,
        symmetric=True,
        copper_finish="ENIG",
        layers=[
            CopperLayer(thickness=0.035, role="mixed"),
            DielectricLayer(thickness=0.2, material="FR-4", form="prepreg"),
            CopperLayer(thickness=0.035, role="power"),
            DielectricLayer(thickness=1.065, material="FR-4", form="core"),
            CopperLayer(thickness=0.035, role="power"),
            DielectricLayer(thickness=0.2, material="FR-4", form="prepreg"),
            CopperLayer(thickness=0.035, role="mixed"),
        ],
    )
)

# Declare board using custom configuration
Board(
    name="MyBoard",
    layout_path="layout/",
    config=config,
    default=True
)

Parameters:

name: String identifier for the board configuration (required)
layout_path: Directory path where layout files will be generated (required)
config: BoardConfig record containing design rules and stackup (optional, mutually exclusive with layers)
layers: Number of layers - 2, 4, 6, or 8 (optional, mutually exclusive with config). When specified, uses predefined stackups from the stdlib:
- layers=2: 2-layer board (1.6mm, 1oz copper, SIG/SIG)
- layers=4: 4-layer board (1.6mm, 1oz outer/0.5oz inner, SIG/GND/PWR/SIG)
- layers=6: 6-layer board (1.6mm, 1oz outer/0.5oz inner, SIG/GND/(SIG/PWR)/(SIG/PWR)/GND/SIG)
- layers=8: 8-layer board (1.6mm, 1oz outer/0.5oz inner, SIG/GND/SIG/PWR/GND/SIG/GND/SIG)
layout_hints: Optional list of layout optimization hints
default: If True, this becomes the default board config for the project

Note: Either config or layers must be provided, but not both. If neither is provided, an error will be raised. Implementation: The stdlib Board() function calls the language builtin builtin.add_board_config() and sets layout properties. BoardConfig Structure:

BoardConfig = record(
    design_rules=DesignRules,     # PCB design rules and constraints  
    stackup=Stackup,              # Layer stackup and materials
    num_user_layers=int,          # Number of User.N layers (default: 4)
    spec=str | None,              # Optional path to specification file
)

Parameters:

design_rules: Optional PCB design rules and constraints
stackup: Optional layer stackup and materials configuration
num_user_layers: Number of User.N layers to create (default: 4)
spec: Optional path to a specification markdown file. Use Path() to resolve the path:
```
BoardConfig(spec=Path("./docs/my-spec.md"))
```

Design Rules Examples:

# Copper constraints (from @stdlib/board_config.zen)
Copper(
    minimum_clearance=0.1,              # mm
    minimum_track_width=0.1,            # mm  
    minimum_via_diameter=0.2,           # mm
    copper_to_edge_clearance=0.3,       # mm
)

# Netclasses for different signal types  
NetClass(
    name="Power",
    clearance=0.25,                     # mm
    track_width=0.6,                    # mm
    via_diameter=0.8,                   # mm
    color="#FF0000",
)

Stackup Configuration Examples:

# Material definitions (from @stdlib/board_config.zen)
Material(
    name="FR-4",
    vendor="Isola", 
    relative_permittivity=4.21,         # Dielectric constant
    loss_tangent=0.025,                 # Loss tangent  
    reference_frequency=1e9,            # Hz
)

# Layer definitions (from @stdlib/board_config.zen)
CopperLayer(thickness=0.035, role="signal")     # "signal", "power", "mixed"
DielectricLayer(thickness=1.6, material="FR-4", form="core")  # "core", "prepreg"

Configuration Merging (Stdlib Utilities): The stdlib provides utilities for merging multiple board configurations:

load("@stdlib/board_config.zen", "merge_configs", "deep_merge")

base_config = BoardConfig(stackup=my_stackup)
tight_rules = BoardConfig(design_rules=tight_constraints)

# Merge multiple configs using stdlib utilities
final_config = merge_configs(base_config, tight_rules)

# Use built-in Board() with merged config
Board("Production", final_config, "layout/", default=True)

TestBench(name, module, checks)

Creates a test bench for validating module connectivity and properties without requiring inputs.

# Load a module to test
MyCircuit = Module("./my_circuit.zen")

# Define check functions
def verify_power_connections(module):
    """Ensure all power pins are connected to VCC"""
    vcc_connections = module.nets.get("VCC", [])
    check(len(vcc_connections) >= 2, "Need at least 2 VCC connections")

def verify_ground_plane(module):
    """Check for proper ground connections"""
    check("GND" in module.nets, "Missing GND net")
    check(len(module.nets["GND"]) > 3, "GND net needs more than 3 connections")

# Create test bench
TestBench(
    name = "PowerTest",
    module = MyCircuit,
    checks = [verify_power_connections, verify_ground_plane]
)

Parameters:

name: String identifier for the test bench
module: Module instance to test (created with Module())
checks: List of check functions to execute

Check Function Signature: Check functions receive a single Module argument containing circuit data:

def check_function(module: Module):
    # Access circuit data through the Module
    nets = module.nets              # Map of net names to connected port tuples
    components = module.components  # Map of component paths to component objects
    
    # Access components via indexing (new preferred method)
    component = module["ComponentName"]              # Direct component access
    submodule = module["SubmoduleName"]              # Direct submodule access
    nested = module["SubmoduleName"]["ComponentName"] # Chained access
    
    # Access component attributes
    component_pins = component.pins     # Component pin connections
    component_type = component.type     # Component type (if available)
    component_props = component.properties  # Component properties dict
    
    # Perform validation - signal failures using check() or error()
    check(condition, "Failure message")  # Throws error if condition is False

Module Contents:

module.nets: Maps each net name to a list of connected port tuples (e.g., {"VCC": [("U1", "VDD"), ("C1", "P1")]})
module.components: Maps component paths to component objects (e.g., {"U1.IC": <Component>, "C1.C": <Component>})
module["name"]: Direct indexing access to child components and submodules by name

Check Function Behavior:

Check functions should use check(condition, message) or error(message) to signal failures
Any unhandled error or exception in a check function is treated as a test failure
Check functions do not need to return any specific value
Use print() for informational output during testing

TestBench Behavior:

Evaluates the module with relaxed input requirements (missing required inputs are allowed)
Stores check functions for deferred execution (checks run later when using pcb test command)
Returns a TestBench value containing test cases and deferred checks
When executed by pcb test: runs each check function in order, reports failures as diagnostics with precise source location pointing to the failing check() call, and prints a success message if all checks pass

Example with Modern Indexing Syntax:

def check_power_connections(module: Module):
    """Verify power IC connections using modern indexing syntax"""
    # Access submodule and then component within it (chained syntax)
    power_ic = module["PowerIC"]["LDO"]
    
    # Equivalent using nested path syntax
    power_ic_nested = module["PowerIC.LDO"]
    
    # Both approaches return the same component
    check(power_ic.name == power_ic_nested.name, "Chained and nested path syntax should be equivalent")
    
    # Check that power pins are connected properly
    check("VCC" in power_ic.pins["VIN"].name, "LDO input not connected to VCC")
    check("GND" in power_ic.pins["GND"].name, "LDO ground not connected")
    
    print(f"✓ {power_ic.name} power connections verified")

def check_capacitor_placement(module: Module):
    """Verify bypass capacitors are properly placed"""
    # Access capacitor components by name using both syntaxes
    c1 = module["C1"]["C"]    # Chained syntax
    c2 = module["C2.C"]       # Nested path syntax
    
    # Verify they're connected to power and ground
    check("VCC" in c1.pins["P1"].name, "C1 not connected to power")
    check("GND" in c1.pins["P2"].name, "C1 not connected to ground")
    check("VCC" in c2.pins["P1"].name, "C2 not connected to power")
    check("GND" in c2.pins["P2"].name, "C2 not connected to ground")
    
    print(f"✓ Capacitors {c1.name} and {c2.name} properly placed")

def check_traditional_syntax(module: Module):
    """Example using traditional components dict access"""
    for comp_path, component in module.components.items():
        if component.type == "capacitor":
            check(hasattr(component, 'capacitance'), f"{comp_path} missing capacitance")
            print(f"✓ {comp_path} capacitance: {component.capacitance}")

def check_net_connectivity(module: Module):
    """Verify net connections using nets attribute"""
    check("VCC" in module.nets, "Missing VCC power net")
    check("GND" in module.nets, "Missing GND net")
    
    vcc_connections = len(module.nets["VCC"])
    check(vcc_connections >= 2, f"VCC only has {vcc_connections} connections, need at least 2")
    
    print(f"✓ VCC net has {vcc_connections} connections")

def check_component_presence(module: Module):
    """Use membership operator to check component existence"""
    # Check if components exist before accessing them
    if "PowerIC" in module:
        power_ic = module["PowerIC"]
        print(f"✓ Found PowerIC submodule: {power_ic}")
        
        # Check nested component existence
        if "PowerIC.LDO" in module:
            ldo = module["PowerIC.LDO"]
            print(f"✓ Found LDO component: {ldo.name}")
        else:
            error("LDO component not found in PowerIC")
    else:
        print("PowerIC not present in this module")
    
    # Check multiple components at once
    required_caps = ["C1", "C2", "C3"]
    missing_caps = [cap for cap in required_caps if cap not in module]
    
    if missing_caps:
        error(f"Missing required capacitors: {missing_caps}")
    else:
        print("✓ All required capacitors present")

TestBench(
    name = "PowerCircuitValidation",
    module = MyPowerCircuit,
    checks = [
        check_power_connections,      # Uses modern indexing syntax
        check_capacitor_placement,    # Uses chained indexing
        check_traditional_syntax,     # Uses traditional components dict
        check_net_connectivity,       # Uses nets attribute
        check_component_presence,     # Uses membership operator
    ]
)

Circuit Graph Analysis & Path Validation

Overview

Zener provides circuit graph analysis for validating module connectivity and topology. The system converts circuit schematics into searchable graphs, enabling path finding between component pins and verification of component sequences. The graph analysis operates on the public interface paradigm: path finding works between component ports (specific IC pins) and external nets (module’s io() declarations), while automatically discovering internal routing paths.

Core Concepts

Circuit Graph

Every module automatically generates a circuit graph that models component connectivity:

def analyze_circuit(module: Module):
    # Get the circuit graph from any module
    graph = module.graph()
    
    # Find paths between public interface points
    paths = graph.paths(start=("TPS82140", "VIN"), end="GND_GND", max_depth=5)

Public Interface Boundaries

Path finding operates between two types of well-defined endpoints: Component Ports: Specific pins on specific components

("ComponentName", "PinName")  # e.g., ("TPS82140", "VIN"), ("STM32", "PA0")

External Nets: Public nets exposed by the module’s io() declarations

"NetName"  # e.g., "GND_GND", "VCC_VCC", "SPI_CLK"

Path Finding API

graph.paths(start, end, max_depth=10)

Finds all simple paths between two points in the circuit:

def validate_power_supply(module: Module):
    graph = module.graph()
    
    # IC pin to external net
    input_paths = graph.paths(start=("TPS82140", "VIN"), end="GND_GND")
    
    # IC pin to IC pin (internal feedback path)
    feedback_paths = graph.paths(start=("TPS82140", "VOUT"), end=("TPS82140", "FB"))
    
    # External net to IC pin
    enable_paths = graph.paths(start="EN_EN", end=("TPS82140", "EN"))

Parameters:

start: Component port tuple ("Component", "Pin") or external net name
end: Component port tuple ("Component", "Pin") or external net name
max_depth: Maximum number of components to traverse (default: 10)

Returns: List of Path objects

Path Objects

Each path contains discovered connectivity information:

def analyze_path(path):
    print("Path details:")
    print("  Ports:", path.ports)        # List of (component, pin) tuples traversed
    print("  Components:", len(path.components))  # Components in the path
    print("  Nets:", path.nets)          # Net names traversed

Path Validation Methods

Basic Validation

# Count components matching predicate
resistor_count = path.count(is_resistor)

# Ensure at least one component matches
path.any(is_capacitor)

# Ensure all components match
path.all(is_passive_component)

# Ensure no components match
path.none(is_active_component)

Sequential Pattern Matching

The path.matches() method validates component sequences in order:

def validate_filter_topology(module: Module):
    graph = module.graph()
    filter_paths = graph.paths(start=("OpAmp", "OUT"), end="GND_GND")
    
    # Validate exact component sequence
    filter_paths[0].matches(
        is_resistor("1kOhm"),    # Series resistor
        is_capacitor("100nF"),   # Filter capacitor
        is_resistor("10kOhm")    # Load resistor
    )

Design Principles

Datasheet Requirements Translation

Circuit validation can directly implement datasheet requirements by mapping component pin constraints to path validation: Power Supply Decoupling

def validate_vin_decoupling(module: Module):
    """Validate VIN decoupling per datasheet Figure 8-1"""
    graph = module.graph()
    
    # Find all paths from VIN pin to ground
    vin_paths = graph.paths(start=("TPS82140", "VIN"), end="GND_GND")
    
    # Datasheet requirement: "≥10µF bulk + 100nF ceramic"
    vin_paths.any(path.matches(is_capacitor("10uF")))   # Bulk capacitor
    vin_paths.any(path.matches(is_capacitor("100nF")))  # Bypass capacitor
    
    print("✓ VIN decoupling meets datasheet requirements")
    // Reference: Datasheet §8.2.1, Figure 8-1

Feedback Networks

def validate_feedback_divider(module: Module):
    """Validate feedback network per datasheet Section 8.3"""
    graph = module.graph()
    
    # Find path from output to feedback pin
    fb_paths = graph.paths(start=("TPS82140", "VOUT"), end=("TPS82140", "FB"))
    
    # Datasheet requirement: "Precision resistor divider"
    fb_paths[0].matches(
        is_resistor(),  # Upper feedback resistor
        is_resistor()   # Lower feedback resistor
    )
    
    print("✓ Feedback divider topology validated")
    // Reference: Datasheet §8.3.2, Equation 1

Bootstrap Circuits

def validate_bootstrap_cap(module: Module):
    """Validate bootstrap capacitor per datasheet Figure 8-4"""
    graph = module.graph()
    
    # Bootstrap cap connects BOOT pin to SW pin
    boot_paths = graph.paths(start=("TPS82140", "BOOT"), end=("TPS82140", "SW"))
    
    # Datasheet requirement: "100nF ceramic, X7R dielectric"
    boot_paths[0].matches(is_capacitor("100nF", dielectric="X7R"))
    
    print("✓ Bootstrap capacitor meets specifications")
    // Reference: Datasheet §8.4.1, Figure 8-4

Public Interface Paradigm

Start/End Points: Always use the module’s “public” interface:

Component ports: Known IC pins from the main component
External nets: Public nets from io() declarations

Internal Discovery: Path finding automatically traverses internal components and nets Benefits:

Deterministic scope: Clear rule boundaries
Implementation freedom: Internal routing flexibility
Hierarchical composability: Rules work at any module level
Performance: Constrained search space

Validation Strategies

Path Existence: Verify required connections exist

# "VIN must connect to GND through decoupling"
vin_paths = graph.paths(start=("IC", "VIN"), end="GND_GND")
check(len(vin_paths) > 0, "VIN decoupling missing")

Topology Validation: Verify exact component sequences

# "Output filter must be L-C configuration"
filter_paths = graph.paths(start=("IC", "SW"), end=("IC", "VOUT"))
filter_paths[0].matches(is_inductor(), is_capacitor())

Alternative Paths: Handle multiple valid implementations

# "Either RC or LC filter acceptable"
filter_paths = graph.paths(start=("IC", "OUT"), end="LOAD_LOAD")
rc_valid = any(path.matches(is_resistor(), is_capacitor()) for path in filter_paths)
lc_valid = any(path.matches(is_inductor(), is_capacitor()) for path in filter_paths)
check(rc_valid or lc_valid, "Filter topology required")

Error Suppression: Use suppress_errors=True for path identification

# Find all paths matching a pattern without failing
matching_paths = [p for p in all_paths if p.matches(
    is_resistor(), is_capacitor(), suppress_errors=True
)]
check(len(matching_paths) > 0, "No RC filter found")

path.matches() API Reference

Syntax

path.matches(*matchers, suppress_errors=False)

Parameters:

*matchers: Sequential matcher functions to apply in order
suppress_errors: If True, returns False on validation failure instead of raising errors

Sequential Processing Model

Matchers consume components sequentially using cursor-based processing
Each matcher receives (path, cursor_index) and returns components consumed
Validation fails if any matcher fails or if components remain after all matchers

Built-in Matcher Functions

# Basic component type matchers
is_resistor(expected_value=None)     # Match resistor, optionally with specific value
is_capacitor(expected_value=None)    # Match capacitor, optionally with specific value
is_inductor(expected_value=None)     # Match inductor, optionally with specific value

# Navigation matchers
skip(n)                             # Skip exactly n components
skip_rest()                         # Consume all remaining components

# Quantified matchers
exactly_n_resistors(n)              # Exactly n consecutive resistors
at_least_n_capacitors(n)            # At least n consecutive capacitors
at_most_n_components(n)             # At most n components of any type

# Conditional matching  
any_of(matcher1, matcher2, ...)     # Match any of the provided matchers
skip_until(matcher)                 # Skip components until matcher succeeds
contains_somewhere(matcher)         # Matcher succeeds somewhere in remaining path

# Component properties
has_package(size)                   # Component with specific package size
name_contains(pattern)              # Component name contains pattern

Custom Matcher Functions

def custom_matcher(path, cursor):
    """Custom matcher function template"""
    if cursor >= len(path.components):
        error("path ended, expected component")
    
    component = path.components[cursor]
    # Validation logic here
    check(component.type == "resistor", "Expected resistor")
    
    return 1  # Consume 1 component, advance cursor

Module System

Module Definition

A module is defined by a .zen file that declares its inputs and creates components:

# voltage_divider.zen

# Declare inputs
vin = io("vin", Net)
vout = io("vout", Net)
gnd = io("gnd", Net)

r1_value = config("r1", str, default="10k")
r2_value = config("r2", str, default="10k")

# Define a resistor symbol (could also load from library)
resistor_symbol = Symbol(
    definition = [
        ("1", ["1"]),
        ("2", ["2"])
    ]
)

# Create components
Component(
    name = "R1",
    type = "resistor",
    footprint = "0402",
    symbol = resistor_symbol,
    pins = {"1": vin, "2": vout},
    properties = {"value": r1_value}
)

Component(
    name = "R2",
    type = "resistor",
    footprint = "0402",
    symbol = resistor_symbol,
    pins = {"1": vout, "2": gnd},
    properties = {"value": r2_value}
)

Module Instantiation

# Load the module
VDivider = Module("./voltage_divider.zen")

# Create instances
VDivider(
    name = "divider1",
    vin = Net("INPUT"),
    vout = Net("OUTPUT"),
    gnd = Net("GND"),
    r1 = "100k",
    r2 = "47k"
)

Intro

Examples

Documentation

​Specification

​Overview

​Table of Contents

​Evaluation Model

​Files as Modules

​Load Resolution

​Default Package Aliases

​Custom Package Aliases

​Core Types

​Net

​Symbol

​Component

​Interface

​Basic Syntax

​Field Types

​Interface Instantiation

​Examples

​Promotion Semantics

​Post-Initialization Callbacks

​Module

​TestBench

​PhysicalRange

​PhysicalRangeType

​Built-in Functions

​moved(old_path, new_path)

​io(name, type, checks=None, default=None, optional=False)

​config(name, type, default=None, convert=None, optional=False)

​File(path)

​Path(path, allow_not_exist=False)

​error(msg)

​check(condition, msg)

​add_property(name, value)

​builtin.physical_range(unit)

​builtin.add_board_config(name, config, default=False)

​builtin.add_electrical_check(name, check_fn, inputs=None)

​Board Configuration Types

​Board(name, layout_path, config=None, layers=None, layout_hints=None, default=False)

​TestBench(name, module, checks)

​Circuit Graph Analysis & Path Validation

​Overview

​Core Concepts

​Circuit Graph

​Public Interface Boundaries

​Path Finding API

​graph.paths(start, end, max_depth=10)

​Path Objects

​Path Validation Methods

​Basic Validation

​Sequential Pattern Matching

​Design Principles

​Datasheet Requirements Translation

​Public Interface Paradigm

​Validation Strategies

​path.matches() API Reference

​Syntax

​Sequential Processing Model

​Built-in Matcher Functions

​Custom Matcher Functions

​Module System

​Module Definition

​Module Instantiation

Specification

Overview

Table of Contents

Evaluation Model

Files as Modules

Load Resolution

Default Package Aliases

Custom Package Aliases

Core Types

Net

Symbol

Component

Interface

Basic Syntax

Field Types

Interface Instantiation

Examples

Promotion Semantics

Post-Initialization Callbacks

Module

TestBench

PhysicalRange

PhysicalRangeType

Built-in Functions

moved(old_path, new_path)

io(name, type, checks=None, default=None, optional=False)

config(name, type, default=None, convert=None, optional=False)

File(path)

Path(path, allow_not_exist=False)

error(msg)

check(condition, msg)

add_property(name, value)

builtin.physical_range(unit)

builtin.add_board_config(name, config, default=False)

builtin.add_electrical_check(name, check_fn, inputs=None)

Board Configuration Types

Board(name, layout_path, config=None, layers=None, layout_hints=None, default=False)

TestBench(name, module, checks)

Circuit Graph Analysis & Path Validation

Overview

Core Concepts

Circuit Graph

Public Interface Boundaries

Path Finding API

graph.paths(start, end, max_depth=10)

Path Objects

Path Validation Methods

Basic Validation

Sequential Pattern Matching

Design Principles

Datasheet Requirements Translation

Public Interface Paradigm

Validation Strategies

path.matches() API Reference

Syntax

Sequential Processing Model

Built-in Matcher Functions

Custom Matcher Functions

Module System

Module Definition

Module Instantiation