protocircuit

draft.md

Proto-Language Specification for Textual Circuit Description

1. Overview

This document specifies a simple textual format for describing electronic circuits, primarily focusing on small-signal models, basic connections, and simple sources. The goal is to provide a human-readable way to represent circuit topology and components connecting different nodes. It is not intended to be a fully-featured netlist language like SPICE but serves as a clear communication tool.

2. Syntax

• Nodes:
  • Represent abstract points or nets of equal potential.
  • Represented by names enclosed in parentheses: (node_name).
  • Node names are typically alphanumeric strings.
  • Device terminals can be treated as nodes using dot notation: (Device.Terminal), e.g., (M1.G), (M2.S). These represent the specific connection point at that terminal.
  • Special predefined node: (GND) represents the global ground or zero-potential reference. Other common nodes like (VDD) might be used by convention for supply rails.
• Components:
  • Represented by alphanumeric names: Component_Name, e.g., Cf, Cfb, rds1, CL, R1, M1.
  • Component values or parameters are not typically specified directly in the connection string but assumed to be known from context or comments.
• Sources (Independent Voltage):
  • Represented by alphanumeric names (like components) followed by a polarity indicator: SourceName (Polarity).
  • Polarity:
    • (-+): Indicates the negative terminal is towards the element preceding it in the -- chain, and the positive terminal is towards the element following it.
    • (+-): Indicates the positive terminal is towards the element preceding it, and the negative terminal is towards the element following it.
  • Sources are placed within series connection paths using the -- operator.
  • Example: (GND) -- Vin (-+) -- R1 (Voltage source Vin connected between GND and R1, with its positive terminal connected to R1).
  • Example: (N1) -- Vbias (+-) -- (N2) (Voltage source Vbias connected between N1 and N2, with its positive terminal connected to N1).
• Series Connections (--):
  • The double hyphen -- indicates a series connection between nodes, components, and sources.
  • It signifies that the listed elements form a continuous path.
  • Format: element1 -- element2 -- element3 ... where element can be a (node), a component, or a source (polarity).
  • Nodes between components/sources are optional. If a node is not explicitly written between two components/sources connected by --, an implicit, unnamed node exists between them.
    • R1 -- C1 is topologically equivalent to R1 -- (internal_node) -- C1.
  • Crucially, -- builds series paths. It connects through components/sources or links them to nodes. For a direct, zero-impedance connection between two named nodes (often making them aliases), use the : operator.
  • Example: (Vin) -- R1 -- (M1.G) (Node Vin connected through R1 to node M1.G)
  • Example: (Vs) -- Cs -- (GND) (Component Cs connected between node Vs and node GND)
  • Example: (GND) -- Vin (-+) -- R1 -- C1 -- (M1.G) (Source Vin in series with R1 and C1, between GND and M1.G. Implicit nodes exist between Vin/R1 and R1/C1).
  • Example: Rin -- (M1.G) (Component Rin connected to node M1.G. The other end of Rin connects to an implicit node).
• Direct Node Assignment (:):
  • The colon : indicates a direct, zero-impedance assignment, signifying that a specific device terminal is connected to a named node (or vice-versa), or that two named nodes are identical. They become electrically the same point.
  • Format is flexible: (NodeName):(Device.Terminal), (Device.Terminal):(NodeName), or (NodeA):(NodeB). All mean the items are directly connected/aliased.
  • This is typically used for connecting device terminals directly to input signals, output ports, supply rails, ground, or defining aliases.
  • Example: (Vin):(M1.G) (The node Vin is directly connected to terminal M1.G).
  • Example: (M1.D):(VDD) (The terminal M1.D is directly connected to the node VDD).
  • Example: (Vout):(M2.D) (The node Vout is directly connected to terminal M2.D).
  • Example: (M1.S):(GND) (The terminal M1.S is directly connected to the node GND).
  • Example: (SignalIn):(Net3) (Node SignalIn and Node Net3 are the same net).
• Parallel Connections ([] with ||):
  • Components connected in parallel between two points (nodes or component terminals) are enclosed in square brackets [] and separated by the double pipe ||.
  • The block represents the equivalent impedance connected between the flanking connection points.
  • Format: point_A -- [ element1 || element2 || ... ] -- point_B (where point_A and point_B can be nodes or implicit connection points in a chain).
  • Example: (Vout) -- [ R2 || CL ] -- (GND) (Resistor R2 and Capacitor CL are in parallel between node Vout and node GND).
  • Example: (M1.D) -- [ rds1 || Cgd1 ] -- (M1.G) (Resistor rds1 and Capacitor Cgd1 are in parallel between the Drain and Gate terminals of M1).
• Controlled Sources (within Parallel Blocks []):
  • Voltage-controlled current sources (VCCS) are represented within parallel blocks [].
  • Format: gain*control_variable (->) or gain*control_variable (<-)
  • gain: The transconductance or gain factor (e.g., gm1).
  • control_variable: The controlling voltage (e.g., vgs1, Vx). This variable must be defined or identifiable from the circuit context (often via comments or node definitions).
  • (->): Indicates current flows from the point preceding the [] block to the point following the [] block.
  • (<-): Indicates current flows from the point following the [] block to the point preceding the [] block.
  • Example: (Vd) -- [ gm*Vgs (->) || gds ] -- (Vs) - Current gm*Vgs flows from node Vd to node Vs.
• Noise Sources (within Parallel Blocks []):
  • Noise current sources can be represented similarly to controlled sources but typically use a dedicated identifier.
  • Format: noise_id (->) or noise_id (<-)
  • Example: (M1.D) -- [ gm1*vgs1 (->) || rds1 || idn1 (->) ] -- (M1.S)
• Named Currents on Paths:
  • A named current flowing along a specific segment of a series path can be indicated directly on the path using the -- operator.
  • Format:
    • element1 -- ->CurrentName -- element2: Indicates CurrentName flows from element1 towards element2.
    • element1 -- <-CurrentName -- element2: Indicates CurrentName flows from element2 towards element1.
  • CurrentName is an alphanumeric identifier for the current.
  • This annotation describes the current flowing through the wire segment represented by the --.
  • Example: (VCC) -- ->I_supply -- R1 -- (NodeX) (Current I_supply flows from VCC through the connection to R1).
  • Example: (NodeA) -- <-I_return -- (GND) (Current I_return flows from GND towards NodeA along that connection).
• Comments:
  • Lines starting with a semicolon ; are treated as comments and ignored.
  • Comments can also be used to define relationships, e.g., ; vgs1 = (M1.G) - (M1.S)

3. Semantics

• Nodes ( ) represent points (nets) of equal potential. They are the fundamental connection points.
• The -- operator describes a series path connecting nodes, components, and voltage sources. Implicit nodes exist between adjacent components/sources if an explicit node () is omitted.
• The : operator establishes an identity or direct, zero-impedance connection between two nodes or between a node and a device terminal.
• The [] block aggregates parallel elements between the two flanking points in a path.
• Independent voltage sources Name (Polarity) insert a voltage difference within a series path.
• The direction (->) or (<-) for controlled and noise sources defines the direction of current flow relative to the points connected by the parallel block.
• The path current annotation -- ->Name -- or -- <-Name -- defines the named current and its direction along a specific segment of a series connection.

4. Examples

• RC Filter (Previous Example):

  ; RC Low-Pass Filter
  (Vin) -- R -- (Vout) -- C -- (GND)

• NMOS Characterization Circuit (Using New Current Syntax):

  ; NMOS Characterization Circuit
  ; Components: M1 (NMOS), VGS (VSource), VDS (VSource)
  ; Current: ID1 (Drain Current)
  
  (GND) -- VGS (-+) -- (M1.G)          ; VGS sets Gate voltage relative to GND
  (GND) -- VDS (-+) -- ->ID1 -- (M1.D)  ; VDS sets Drain voltage, ID1 flows VDS(+) -> M1.D
  (M1.S):(GND)                          ; Source terminal connected to GND
  (M1.B):(GND)                          ; Bulk terminal connected to GND (or Source)

• Amplifier with Input Source:

  ; Resistor R1, Nmos M1, Resistor R2, Capacitor CL, VoltageSource Vin
  (GND) -- Vin (-+) -- R1 -- (M1.G) ; Input voltage source Vin in series with R1 to Gate
  (M1.D):(VDD)                   ; Drain to VDD
  (M1.B):(GND)                   ; Bulk to GND
  (Vout):(M1.S)                   ; Output taken at Source
  (Vout) -- [ R2 || CL ] -- (GND) ; Load R2 parallel CL connected between Vout and GND

• Feedback Circuit:

  (Vin) -- Cf -- (Vx)            ; Cf connects Vin to Vx (implicit node before Cf)
  (Vx) -- Cfb -- (Vout)          ; Cfb connects Vx to Vout
  (Vout) -- [ gm1*Vx (->) || rds1 || rds2 || Cl ] -- (GND)
  ; Note: gm1, rds1, rds2, Cl are small-signal parameters/components
  ; Note: Vx is defined by the connection point between Cf and Cfb

• Cascode Amplifier Small-Signal Model (No Bulk, with Noise):

  ; Input Stage (M1)
  (GND) -- vin (-+) -- (M1.G)      ; Small-signal input source driving M1 Gate
  (M1.S):(GND)                    ; M1 Source to ground
  
  ; Path between M1.D and M1.S contains parallel elements
  (M1.D) -- [ gm1*vgs1 (->) || rds1 || idn1 (->) ] -- (M1.S)
  
  ; Cascode Stage (M2)
  (M2.G):(GND)                    ; M2 Gate AC grounded (Vbias is AC ground)
  (M2.S):(M1.D)                    ; Source of M2 connected directly to Drain of M1
  (M2.D) -- [ gm2*vgs2 (->) || rds2 || idn2 (->) ] -- (M2.S) ; Path M2.D to M2.S
  (vout):(M2.D)                    ; Output node connected directly to Drain of M2
  
  ; Load Capacitance
  (vout) -- CL -- (GND)
  
  ; Control voltage definitions (typically in comments)
  ; vgs1 = (M1.G) - (M1.S) = vin - (GND) = vin
  ; vgs2 = (M2.G) - (M2.S) = (GND) - (M1.D) = -(M1.D)