circuit directive

The circuit directive generates electric circuit diagrams as inline SVG from a simple topology description. You describe the circuit as nested series(...) / parallel(...) expressions, and the directive renders it using LaTeX circuitikz.

Basic usage

A simple series circuit with a battery and two resistors:

:::{circuit}
width: 40%
circuit: series(U, R1, R2)
:::

Syntax overview

:::{circuit}
component: V1, battery, 12 V
component: R1, resistor, 1 kΩ
component: L1, lamp

circuit: series(V1, R1, parallel(L1, R2))
width: 80%
layout: loop
:::

Component declaration

Components are declared with repeated component: (or comp:) lines:

component: ID, type, value, label

• ID — a unique identifier (e.g. R1, V1, L1)

• type — component type (see table below)

• value — optional display value (e.g. 1 kΩ, 12 V)

• label — optional custom label (defaults to TeX-ified ID, e.g. R1 → \(R_1\))

If a component is referenced in circuit: but not explicitly declared, its type is inferred from the ID prefix.

Component types

Type keyword	Rendered as
resistor, r, res	Resistor
var_resistor, pot, potmeter	Variable resistor
battery, source, dc, vsource	Battery / voltage source
lamp, bulb	Lamp
led	LED
diode	Diode
wire	Plain wire (default)

ID prefix auto-detection

Prefix	Inferred type
R	resistor
RV	var_resistor
V, U	battery
L	lamp
D, LED	led

Topology expression

The circuit: line uses nested function calls:

• series(A, B, C) — components in series

• parallel(A, B, C) — components in parallel

• Arguments can be component IDs or nested series(...)/parallel(...) groups

Options

Option	Meaning	Default
width	CSS width	—
align	left, center, or right	center
layout	ladder or loop	ladder
flow	Direction of current flow: right, left, up, down	right
unit	Scale factor (float)	1.2
style	european or american (circuitikz)	european
backend	circuitikz or schemdraw	circuitikz
symbols	iec or ieee (schemdraw only)	iec
branch	Parallel branch placement: auto, up, down, both	auto
junctions	Show junction dots: true/false	true
fontsize	Font size for labels	—
class	Extra CSS classes	—
name	Stable anchor / reference name	—
alt	Alt text for accessibility	—
nocache	Force regeneration	—
debug	Keep debug output	—

Examples

Series with parallel branch

:::{circuit}
width: 40%
fontsize: 18
flow: right
layout: loop
unit: 0.5
circuit: series(U, R1, parallel(R2, R3))
:::

Parallel first, then series

:::{circuit}
width: 40%
fontsize: 18
flow: right
layout: loop
unit: 0.5
circuit: series(U, parallel(R1, R2), R3)
:::

Deeply nested parallel-series

:::{circuit}
width: 40%
fontsize: 18
flow: right
layout: loop
unit: 0.5
circuit: series(U, parallel(R1, R2, series(R3, R4)))
nocache:
:::

Tips

• Components not declared with component: but referenced in circuit: are auto-detected from their ID prefix.

• Labels default to TeX formatting: R1 → \(R_1\), RV12 → \(RV_{12}\).

• The circuitikz backend requires a working LaTeX installation with the circuitikz package.

• Use layout: loop for perimeter-style layouts (current flows around a loop) and layout: ladder for ladder-style layouts.

Source

src/munchboka_edutools/directives/circuit.py