Circuitjs

CircuitJS1's circuit format

A circuit is one plain-text file. Each line is either the options header, one element, one scope, or one slider. That is the whole format. CircuitJS1 reads it with a tokenizer that splits on spaces and gives up on a line it cannot make sense of, so a wrong field is a missing element, not an error message — which is why verdict.py exists.

$ 1 0.000005 10.20027730826997 50 5 43 5e-11
v 176 224 176 112 0 1 40 5 0 0 0.5
r 176 112 336 112 0 1000
c 336 112 336 224 0 0.00001 0
w 176 224 336 224 0
g 176 224 176 256 0
o 2 64 0 2 5 0.0125

That is a working RC low-pass: a 5 V sine into 1 kΩ, across 10 µF, with the capacitor on the scope. Everything else is more of the same.

The $ options header

One line, first, always.

$ <flags> <maxTimeStep> <iterations> <currentSpeed> <voltageRange> [<powerBrightness> <minTimeStep>]

iterations is the dial that makes a circuit watchable. Slow it down (2) for something that should visibly blink; leave it (10) for a waveform on a scope.

Element lines

<code> <x1> <y1> <x2> <y2> <flags> [values…]

Everything after flags belongs to that element and differs per code. Coordinates are integers on a 16-px grid — CircuitJS1 snaps to it, and two ends that are not on it will not meet.

Elements connect only by sharing a coordinate. There are no net names and no explicit connections: two posts at exactly the same (x, y) are the same node. Crossing wires that do not share an endpoint do not touch. w is an ideal wire and exists purely to move a node somewhere else on the canvas.

Where an element's posts are

The ones you will actually write

Waveforms for v and R: 0 DC, 1 sine, 2 square, 3 triangle, 4 sawtooth, 5 pulse, 6 noise. frequency is in hertz, maxVoltage is the amplitude, bias the offset, phaseShift radians, dutyCycle a fraction. A 5 V DC supply is v x1 y1 x2 y2 0 0 40 5 0 0 0.5 — the 40 is a leftover frequency that DC ignores. Post 0 is (x1,y1), the negative end; post 1 is the positive end. Look at the examples before inventing a value.

Placing an op-amp, a transistor or a chip

Their pins are not at the line's own ends, so writing the wires around them by hand is the one place this format bites. Two that are worth knowing exactly, both drawn left to right at the default size:

• Op-amp a x1 y1 x2 y2 flags [maxOut minOut gbw v0 v1 gain] — inputs at (x1, y1−16) and (x1, y1+16), output at (x2, y2). With flags 0 the upper input is the inverting (−) one; flags 1 swaps them. See examples/amp-invert.txt (flags 0) and examples/amp-noninvert.txt.
• Transistor t x1 y1 x2 y2 flags type vbe vbc beta [model] — type is 1 for NPN and -1 for PNP. Base at (x1, y1); for an NPN with flags 0, collector at (x2, y2−16) and emitter at (x2, y2+16). flags 1 flips them, and PNP swaps them. beta is usually 100. See examples/npn.txt.

For anything with a body — the 555 (165), counters, gates, flip-flops, transformers, pots — do not compute the pins. Copy the whole block, chip line and surrounding wires together, out of an example, and if you need it somewhere else add the same offset to every coordinate in the block. The verdict will tell you the ends that stopped meeting. template/circuit.txt is exactly this: the 555 and its wires lifted unchanged out of examples/555square.txt, with an LED branch added on the output node.

Scope lines: o

A scope is what makes the pane worth looking at. Put at least one on every circuit.

o <element> <speed> <value> <flags> <scaleV> <scaleA> [position]

• element is an index, counting only element lines, from 0. The commonest mistake in the whole format. Insert an element in the middle and every scope below it is watching the wrong thing — so append new elements at the end rather than inserting, or renumber every o and 38 line.
• speed — simulation steps per pixel column. 64 is a good default; larger sweeps slower.
• value — 0 voltage, 3 current, 7 power. For a transistor: 1 Ib, 2 Ic, 4 Vbe, 6 Vce.
• flags — 1 plot current, 2 plot voltage, 8 show frequency, 256 show minimum, 512 show the scale, 8192 auto-scale. 3 (both traces) is a good default.
• scaleV, scaleA — volts and amps per division.
• position — which stacked slot, from 0.

o 2 64 0 3 5 0.0125 reads: watch element 2, 64 steps per column, plot its voltage and current, 5 V and 12.5 mA per division. Files saved by the app itself set flag 4096 and write a longer, multi-plot form; both load, and the short one above is the one to write by hand.

Slider lines: 38

A knob in the app's right-hand column. The user turning it while the sim runs is most of the fun.

38 <element> F<flags> <editItem> <min> <max> <label> <step>

element is the same index as a scope's. editItem is which of that element's editable values the slider drives, from 0 — 0 is the primary one (a resistor's resistance, a capacitor's capacitance). F0 is plain, F2 logarithmic. Spaces in the label are written \s; step is 0 for a smooth knob. 38 0 F0 0 1 101 Resistance 0 puts a 1 Ω – 101 Ω knob on element 0. See examples/lrc.txt.

No -1 before the label. The app's own export writes a sharedWith field there, but the loader only reads it when the flags say the knob is shared (F1); after F0 or F2 the -1 becomes the knob's label and the pane shows a slider called "-1". The verdict warns about it.

Other line types

h a hint the app shows, ! a custom-logic model, . a composite-subcircuit model, 32 and 34 transistor and diode model definitions. Copy them when you copy a block; do not write them fresh.

Laying it out

The drawing is the explanation, so lay it out the way a schematic is read.

1. Signal flows left to right. Source on the left, load or output on the right.
2. Supplies at the top, ground at the bottom. Put the g at the lowest point of the circuit and run the return wire along the bottom.
3. Everything on the 16-px grid, and prefer multiples of 32 or 48 for the spacing between parallel branches — a two-terminal part wants about 64–160 px of room.
4. One axis at a time. Wires are horizontal or vertical; turn a corner with a second w rather than one diagonal.
5. Keep it around 500 × 400. The pane fits that without scrolling; the app centres what it gets.
6. Label the nodes that matter with x text, or use 207 labeled nodes instead of long wires across the canvas.
7. Leave the scope elements' indices alone — append, don't insert.

How to work

The pane is live: it re-imports circuit.txt on every save without reloading the app, keeping the simulation running. So save early and often, and let the user watch it grow.

1. Source and ground first. v (or R), g, and the return wire. Save. Run the verdict. The pane already shows something running.

2. Then the circuit proper, one branch at a time, saving after each. Two-terminal parts are the easy path; reach for a chip only when the circuit really is one.

3. Then a scope on the output node, and a slider on the value worth turning. Say in one line which knob you gave them.

4. Run the verdict after every save:

   python3 "$CIRCUITJS_TOOLCHAIN/verdict.py"            # circuit.txt
   python3 "$CIRCUITJS_TOOLCHAIN/verdict.py" other.txt
   

   Errors mean CircuitJS1 will drop a line: an unknown code, a truncated element, a scope pointing past the last element. Fix those. Warnings are usually real too — a floating end is a part that is not in the circuit, an off-grid coordinate is two ends that look joined and are not. An open_end info on a circuit that contains a chip or a transistor is expected: that end is a pin the checker cannot see.

5. Never write the XML dump. exportCircuit() in the app returns XML; this workspace is the text format, which the app still reads and a human can still edit.

When something does not work

Examples

examples/ holds eight of CircuitJS1's own circuits, unchanged (GPL-2.0, © Paul Falstad and Iain Sharp) — see examples/README.md for what each one is worth reading for. The installed app has all 373 in its Circuits menu; open one in the pane, poke at it, and copy the lines you want.