logic

A canvas environment holding a logic circuit the reader operates.

logicNode
On this page
A half adder: switches A and B, both on, feed an XOR gate to the sum lamp S and an AND gate to the carry lamp C; the wires at 1 and the carry lamp are lit.A half adder: switches A and B, both on, feed an XOR gate to the sum lamp S and an AND gate to the carry lamp C; the wires at 1 and the carry lamp are lit.

#Parts and wires

logic draws a digital circuit and runs it. A level starts at a switch or a clock, passes through gates, a mux or a flipflop, and ends at a lamp. A wire runs from one part's output to another's input, wire(from: #a; to: #g).

Warning
An alu is drawn for a datapath and computes nothing: its output is always unknown.

A part's body is its label. A gate's kind is its implicit attribute, and a gate is usually written with no label, gate#g:and{}.

Warning
A bare gate#g:and with neither body nor attributes does not parse as a part.

The circuit is laid out the way a flowchart is, from what connects to what, along direction, the implicit attribute: right unless written, so logic:down{…} runs top to bottom. A circuit too long for the environment wraps like lines of text, each line starting again at the beginning, never snaking back, so right and strictly-right draw alike. auto runs down or right, whichever draws the circuit larger.

Inputs land on a part's back, outputs leave its front, and an output fans out to every wire that leaves it, with a dot where a wire branches off. Wires carry no arrowhead. A wire that runs back against the flow, into a latch's other gate, loops round the parts between.

A full adder drawn left to right: switches A and B are on and C-in is off; two XOR gates make the sum S, two AND gates and an OR make the carry C-out. The wires carrying 1 are lit orange, and the lamp C-out is lit while S is not.A full adder drawn left to right: switches A and B are on and C-in is off; two XOR gates make the sum S, two AND gates and an OR make the carry C-out. The wires carrying 1 are lit orange, and the lamp C-out is lit while S is not.
logic{
    switch#a{$A$}(value: 1)
    switch#b{$B$}(value: 1)
    switch#cin{$C_{in}$}
    gate#x1:xor{}
    gate#x2:xor{}
    gate#a1:and{}
    gate#a2:and{}
    gate#carry:or{}
    lamp#s{$S$}
    lamp#cout{$C_{out}$}

    wire(from: #a; to: #x1)
    wire(from: #b; to: #x1)
    wire(from: #x1; to: #x2)
    wire(from: #cin; to: #x2)
    wire(from: #a; to: #a1)
    wire(from: #b; to: #a1)
    wire(from: #x1; to: #a2)
    wire(from: #cin; to: #a2)
    wire(from: #a1; to: #carry)
    wire(from: #a2; to: #carry)
    wire(from: #x2; to: #s)
    wire(from: #carry; to: #cout)
}

#Ports and wiring errors

A gate's inputs are interchangeable and have no names: every wire to a gate takes its next free input, and the layout places each where its source stands, so wires do not cross. The other parts' ports differ, and a wire names the one it means after the part's id: to: #m.select, from: #ff.qbar. Port names ignore case.

  • mux: data inputs d0 to d3 on its back, each numbered beside its wire; select (also s0) entering one side, and s1 the other. Two data inputs need one select line, three or four need both.
  • flipflop: inputs d and clock (also clk), outputs q and qbar (also q-bar, nq).
  • alu: inputs a and b either side of its notch, and op entering its side.

A wire that names no input takes the part's next free one: a mux's next data input, never a select line; a flip-flop's d, then clock; an alu's a, then b, so op is always named. A wire that names no output leaves by q on a flip-flop and by the one output on anything else.

A multiplexer whose select line enters its side and a D flip-flop marked D, CLK, Q and Q-bar, its Q-bar output looped back round into its own D.A multiplexer whose select line enters its side and a D flip-flop marked D, CLK, Q and Q-bar, its Q-bar output looped back round into its own D.
logic{
    switch#x{$x$}
    switch#y{$y$}(value: 1)
    switch#sel{Select}
    switch#clk{Clock}
    mux#m{}
    flipflop#ff{}(value: 0)
    lamp#out{Out}
    lamp#q{$Q$}

    wire(from: #x; to: #m)
    wire(from: #y; to: #m)
    wire(from: #sel; to: #m.select)
    wire(from: #m; to: #out)
    wire(from: #clk; to: #ff.clock)
    wire(from: #ff.qbar; to: #ff.d)
    wire(from: #ff.q; to: #q)
}

The compiler refuses a circuit that cannot be wired as written:

  • a wire end naming no part: 'wire.to' names '#z', but no part in this circuit declares that id
  • a wire out of a lamp, or into a switch or clock: A wire arrives at '#b', but a switch takes no input — it is where a level starts
  • a port the part does not have, or a named input on a gate: A gate's inputs have no names — write the wire to '#g', and it takes the next free input
  • two wires into one input: Two wires drive the same input of '#ff' (d) — an input takes one wire
  • a not with more than one input, and a mux with too many data inputs or too few select lines: '#m' has 3 data inputs, which need 2 select lines (s0, s1)

It warns where a part can never be known: No wire arrives at '#g', so its level is unknown, and '#ff' has no clock, so its output never changes.

#Levels and the gate delay

A level is 0, 1 or unknown. A wire at 1 is lit, thicker, in the environment's high hue (orange unless written); at 0 it is grey; unknown, it is grey and dashed. A switch is a toggle, its knob to the right and its track lit when it is on; a lamp is a crossed circle that glows when lit. A switch, clock and lamp write their level beneath their label, a question mark while it is unknown, so neither depends on colour alone.

Each gate answers a change one gate delay, 110 ms, after it, all gates at once, so a change is seen travelling through the circuit. An unknown spreads only as far as it must: an AND with a 0 among its inputs is 0 whatever the others are, and an OR with a 1 is 1.

Every part with an id publishes level, so {{#cout.level}} reads the carry in prose and follows it as the reader flips switches. While the level is unknown the value is absent.

Three frames of an SR latch, unknown at power-up, as a cue sets S: S still off, then S lit and the NOR gate it feeds settling from unknown to 0, then the other NOR gate lighting Q.Three frames of an SR latch, unknown at power-up, as a cue sets S: S still off, then S lit and the NOR gate it feeds settling from unknown to 0, then the other NOR gate lighting Q.
logic{
    switch#s{$S$}(value: 0 !cue.to{1}(at: 1 + 300ms))
    switch#r{$R$}
    gate#n1:nor{}
    gate#n2:nor{}
    lamp#q{$Q$}

    wire(from: #r; to: #n1)
    wire(from: #n2; to: #n1)
    wire(from: #s; to: #n2)
    wire(from: #n1; to: #n2)
    wire(from: #n1; to: #q)
}

#Switches, cues and the reader

The reader flips a switch by clicking it, or by focusing it and pressing Enter or Space. fixed keeps the reader's hands off a switch only the prose should move, and puts a padlock on its knob. A switch's value is where it starts, and a !cue.to on it flips it at a step, so the prose can say “now set S” and the circuit does:

switch#s{$S$}(value: 0 !cue.to{1}(at: 1) !cue.to{0}(at: 2))

Each step shows the author's state: the switches where the cues have put them, and anything that remembers in the state the cues so far have left it, replayed in the order they fired, whether the reader arrived by playing forward, stepping back or jumping. What the reader has done since, their flips and a clock's ticks, is dropped when the step changes and when a cue fires on the step.

A change a cue has just made on the step being read ripples from the state before it. A step reached by going back or by jumping lands settled, and a reader who has asked for less motion always sees the settled state.

#Circuits that remember

Gates whose outputs feed back into one another hold a state. A latch built from them powers up unknown, as a real one does, until something sets or resets it; a gate's value is the level its output starts at, for a latch that must power up in a known state. Changes the cues make at the same moment land together, so a latch released from both inputs at once can race. If its levels are still changing after 64 gate delays, they are shown unknown and the canvas says This circuit never settles, so the levels in its loop are unknown.

#Flip-flops and clocks

A flipflop takes the level at d on each rising edge of clock and holds it until the next; its value is the level q starts at, and without one q starts unknown. Power-up is not an edge.

A clock is a switch that flips itself: a square wave with period from one rising edge to the next, 1s unless written, ticking while the circuit is on screen. The reader pauses and restarts it by clicking it, and a paused clock shows ‖ beside its level. running starts or stops it from a cue.

Tip
For a clock the reader steps by hand, use a switch.
logic{
    clock#clk{Clock}(period: 2s)
    flipflop#ff{}(value: 0)
    lamp#q{$Q$}
    wire(from: #clk; to: #ff.clock)
    wire(from: #ff.qbar; to: #ff.d)
    wire(from: #ff.q; to: #q)
}

#Ready-built circuits

The circuits pack has standard circuits ready-built: half-adder, full-adder, the 4-bit ripple-adder, xor-from-nand, the 2-to-4 decoder, sr-latch, d-latch and the 3-bit ripple-counter. Each takes the ids of the parts that feed it, without #, and declares its results under the name it is given: a full adder named fa gives #fa-sum and #fa-carry.

@use:circuits

logic{
    switch#a{$A$}
    switch#b{$B$}
    switch#cin{$C_{in}$}
    circuits.full-adder(name: fa; a: a; b: b; carry-in: cin)
    lamp#s{$S$}
    lamp#cout{$C_{out}$}
    wire(from: #fa-sum; to: #s)
    wire(from: #fa-carry; to: #cout)
}

#focus, zoom and interactive

focus names a part for the camera to look at, and zoom multiplies over the fitted frame; omitted, the circuit fits the environment. Both are animatable with !cue.to. interactive hands the reader wheel-zoom and drag, with a double-click back to the authored frame; switches flip either way. continue: #id carries the reader's camera from an earlier logic environment, not the levels.


#Attributes

directionImplicit
Which way the signals run, inputs at the start and outputs at the end.
autodownuprightleftstrictly-downstrictly-upstrictly-rightstrictly-left
Can be written as shorthand: logic:value
Defaultright
title
The caption over the environment's top left.
high
The colour a 1 is drawn in.
paint
Defaultorange
focusAnimatable
The part the camera looks at.
logic-anchor
zoomAnimatable
A multiplier over the fitted frame.
interactive
Whether the reader can zoom, pan and reset the camera.
Defaultfalse
continue
An earlier logic environment whose reader camera this one starts from.

#Allowed content

#Allowed in

#Examples

Three frames of the first step: A off in a chain of two NOT gates, then a cue flips A on and the first gate answers, then the change has travelled a gate at a time to the lamp.Three frames of the first step: A off in a chain of two NOT gates, then a cue flips A on and the first gate answers, then the change has travelled a gate at a time to the lamp.
logic{
    switch#a{$A$}(value: 0 !cue.to{1}(at: 1 + 300ms))
    gate#n1:not{}
    gate#n2:not{}
    lamp#y{$Y$}
    wire(from: #a; to: #n1)
    wire(from: #n1; to: #n2)
    wire(from: #n2; to: #y)
}
An XOR built from four NAND gates with high set to blue: both switches on and their wires lit blue, and the output lamp dark.An XOR built from four NAND gates with high set to blue: both switches on and their wires lit blue, and the output lamp dark.
logic{
    switch#a{$A$}(value: 1)
    switch#b{$B$}(value: 1)
    gate#n1:nand{}
    gate#n2:nand{}
    gate#n3:nand{}
    gate#n4:nand{}
    lamp#y{$A \oplus B$}
    wire(from: #a; to: #n1)
    wire(from: #b; to: #n1)
    wire(from: #a; to: #n2)
    wire(from: #n1; to: #n2)
    wire(from: #n1; to: #n3)
    wire(from: #b; to: #n3)
    wire(from: #n2; to: #n4)
    wire(from: #n3; to: #n4)
    wire(from: #n4; to: #y)
}(
    high: blue
)

#Writing guidance

  • Selecting canvas content — A mark belongs on the canvas when seeing it changes what the reader understands, and the detail holds as a picture on its own.

Last updated