Models

Data models for the Initial Sizing module (Layer 3).

All structures are plain dataclasses — they carry no logic and can be freely inspected or passed between pipeline stages.

exception circuitgenome.sizer.shared.models.UnsupportedTechError[source]

Bases: ValueError

Raised when a technology cannot be sized by the requested method.

Currently raised when a PTM/SPICE-model node has no gm/Id LUT: such nodes must use the gm/Id pipeline, and the analytical (Level-1) sizer is not a valid fallback for them.

class circuitgenome.sizer.shared.models.MosfetParams(mu_cox, vth, lam)[source]

Bases: object

CMOS process parameters for one device polarity.

Parameters:

  • mu_cox (float) – Process transconductance parameter µ·Cox in A/V².

  • vth (float) – Threshold voltage in V (positive for NMOS, negative for PMOS).

  • lam (float) – Channel-length modulation coefficient λ in 1/V (always positive).

mu_cox: float
vth: float
lam: float
class circuitgenome.sizer.shared.models.GridSpec(min, max, step)[source]

Bases: object

Discrete geometry or capacitance grid.

Parameters:

  • min (float) – Minimum value (µm for W/L, pF for cap).

  • max (float) – Maximum value.

  • step (float) – Discretisation step.

min: float
max: float
step: float
class circuitgenome.sizer.shared.models.SpiceLib(file, corner='typical', design=None, corners=<factory>)[source]

Bases: object

A foundry PDK referenced via .lib corner sections (e.g. GF180MCU).

Unlike spice_model (a flat .include of .model nmos/pmos cards, as with PTM), a PDK selects a process corner with .lib "<file>" <corner> and its devices are subcircuits (instantiated with X), so a TechParams carrying a SpiceLib also carries a device_map.

Parameters:

  • file (str) – Resolved path to the corner library (sm141064.ngspice).

  • corner (str) – Default/nominal corner used for sizing characterisation.

  • design (str | None) – Optional resolved path to a global settings file to .include before the corner .lib (design.ngspice).

  • corners (list[str]) – Corners to re-measure for the CLI verification table.

file: str
corner: str = 'typical'
design: str | None = None
corners: list[str]
class circuitgenome.sizer.shared.models.TechParams(name, nmos, pmos, width, length, cap, spice_model=None, gmid_lut=None, spice_lib=None, device_map=None)[source]

Bases: object

Process technology parameters loaded from a YAML config file.

Parameters:

  • name (str) – Technology identifier (e.g. "generic_parameterized").

  • nmos (MosfetParams) – NMOS Shichman-Hodges parameters.

  • pmos (MosfetParams) – PMOS Shichman-Hodges parameters.

  • width (GridSpec) – Transistor width grid in µm.

  • length (GridSpec) – Transistor length grid in µm.

  • cap (GridSpec) – Compensation capacitor grid in pF.

  • spice_model (str | None) – Optional path (relative to the config dir, or absolute) to a SPICE .model card whose nmos/pmos models match the netlist (e.g. a BSIM4 .pm file). When None, the SPICE-verification path synthesises a Level-1 model from mu_cox/vth/lam.

  • gmid_lut (str | None) – Optional path (relative to the config dir, or absolute) to a committed gm/Id lookup table (*_gmid.npz from tools/extract_tech.py --gm-id). When present, sizing uses the procedural gm/Id path instead of the Level-1 analytical sizer.

  • spice_lib (SpiceLib | None) – Optional SpiceLib for a corner-based foundry PDK. Mutually exclusive with spice_model.

  • device_map (dict[str, str] | None) – Optional mapping from the generic device type ("nmos"/"pmos") to the PDK subcircuit name (e.g. "nmos_3p3"). Present iff the SPICE deck must instantiate subcircuits (X) instead of .model MOSFETs (M).

name: str
nmos: MosfetParams
pmos: MosfetParams
width: GridSpec
length: GridSpec
cap: GridSpec
spice_model: str | None = None
gmid_lut: str | None = None
spice_lib: SpiceLib | None = None
device_map: dict[str, str] | None = None
class circuitgenome.sizer.shared.models.SizingSpec(vdd, vss, ibias, cl, second_stage_current_ratio=2.0, third_stage_current_ratio=5.0, gain_min_db=None, gbw_min_hz=None, phase_margin_min_deg=None, slew_rate_min_vps=None, power_max_w=None, output_swing_max_v=None, output_swing_min_v=None, cmrr_min_db=None, psrr_min_db=None)[source]

Bases: object

Performance specification for initial sizing.

All performance bounds are optional — None means unconstrained.

Parameters:

  • vdd (float) – Positive supply voltage in V.

  • vss (float) – Negative supply voltage in V (0.0 for single supply).

  • ibias (float) – External input bias current in A.

  • cl (float) – Output load capacitance in F.

  • second_stage_current_ratio (float) – Second-stage quiescent current as a multiple of ibias (iDS_2 = ratio × ibias). Default 2.0.

  • gain_min_db (float | None) – Minimum open-loop DC gain in dB.

  • gbw_min_hz (float | None) – Minimum unity-gain bandwidth in Hz.

  • phase_margin_min_deg (float | None) – Minimum phase margin in degrees.

  • slew_rate_min_vps (float | None) – Minimum slew rate in V/s.

  • power_max_w (float | None) – Maximum total quiescent power in W.

  • output_swing_max_v (float | None) – Maximum output voltage in V (absolute, e.g. 4.6 for a 5V supply).

  • output_swing_min_v (float | None) – Minimum output voltage in V (absolute, e.g. 0.4).

  • cmrr_min_db (float | None) – Minimum CMRR in dB.

  • psrr_min_db (float | None) – Minimum PSRR in dB (positive supply, approximate).

  • third_stage_current_ratio (float)

vdd: float
vss: float
ibias: float
cl: float
second_stage_current_ratio: float = 2.0
third_stage_current_ratio: float = 5.0
gain_min_db: float | None = None
gbw_min_hz: float | None = None
phase_margin_min_deg: float | None = None
slew_rate_min_vps: float | None = None
power_max_w: float | None = None
output_swing_max_v: float | None = None
output_swing_min_v: float | None = None
cmrr_min_db: float | None = None
psrr_min_db: float | None = None
class circuitgenome.sizer.shared.models.TransistorSizing(ref, w_um, l_um, ids_a, vgs_v, vds_sat_v)[source]

Bases: object

Sizing result for a single transistor.

Parameters:

  • ref (str) – Device reference in the netlist (e.g. "m1_input_pair").

  • w_um (float) – Gate width in µm.

  • l_um (float) – Gate length in µm.

  • ids_a (float) – Quiescent drain-source current in A.

  • vgs_v (float) – Quiescent gate-source voltage in V.

  • vds_sat_v (float) – Minimum |VDS| for saturation in V.

ref: str
w_um: float
l_um: float
ids_a: float
vgs_v: float
vds_sat_v: float
class circuitgenome.sizer.shared.models.SizingResult(transistors, cc_pf, metrics, margins, solver_status, cc2_pf=None, warnings=<factory>, resistors=<factory>, transistor_intents=<factory>, bias_feasible=True)[source]

Bases: object

Output of size_circuit().

Parameters:

  • transistors (dict[str, TransistorSizing]) – Per-transistor sizing keyed by device reference.

  • cc_pf (float | None) – Compensation capacitor value in pF, or None for single-stage.

  • metrics (dict[str, float]) – Computed performance metrics, e.g. {"gain_db": 90.1, "gbw_hz": 3.0e6, ...}. Analytical (model-based, ngspice-free) estimate; for PTM the CLI measures and displays ngspice values (spice_sim.simulate_metrics) instead.

  • margins (dict[str, float]) – Safety margin for each constrained spec (actual/spec for min specs, spec/actual for max specs). Values > 1 mean spec is met.

  • solver_status (str) – OR-Tools CP-SAT status string: "OPTIMAL", "FEASIBLE", "INFEASIBLE", or "UNKNOWN".

  • warnings (list[str]) – Advisory messages, e.g. a likely --topology/netlist mismatch. Empty when the netlist cleanly matches the topology.

  • resistors (dict[str, float]) – Sized load-resistor values in ohms, keyed by device reference (e.g. {"r1_load": 1.06e5}). Empty when there are no sized resistors.

  • bias_feasible (bool) – False when the gm/Id DC operating-point check finds a current source that cannot stay saturated (e.g. a cascode tail with no headroom) — the assumed bias current won’t flow, so the frequency-domain metrics are optimistic. Always True for the Level-1 path.

  • transistor_intents (dict) – gm/Id path only — the resolved per-device design intent keyed by device reference (gmid.intent.TransistorIntent: the functional block, role, gm/Id region, L multiple and rationale). Empty for the Level-1 path.

  • cc2_pf (float | None)

transistors: dict[str, TransistorSizing]
cc_pf: float | None
metrics: dict[str, float]
margins: dict[str, float]
solver_status: str
cc2_pf: float | None = None
warnings: list[str]
resistors: dict[str, float]
transistor_intents: dict
bias_feasible: bool = True