logicsim

Create and simulate digital circuits with Rust abstractions!

In logicsim you use a GateGraphBuilder to create and connect logic gates, conceptually the logic gates are represented as nodes in a graph with dependency edges to other nodes.

Inputs are represented by constants([ON], [OFF]) and levers.

Outputs are represented by OutputHandles which allow you to query the state of gates and are created by [GateGraphBuilder::output].

Once the graph is initialized, it transforms into an [InitializedGateGraph] which cannot be modified. The initialization process optimizes the gate graph so that expressive abstractions that potentially generate lots of constants or useless gates can be used without fear. All constants and dead gates will be optimized away and the remaining graph simplified very aggressively.

Zero overhead abstractions!

Examples

Simple gates. ```rust let mut g = GateGraphBuilder::new();

// Providing each gate with a string name allows for some very neat debugging. // If you don't want them affecting performance, you can disable feature "debuggates", // all of the strings will be optimized away. let or = g.or2(ON, OFF, "or"); let oroutput = g.output1(or, "or_output");

let and = g.and2(ON, OFF, "and"); let andoutput = g.output1(and, "andoutput");

let ig = &g.init();

// b0() accesses the 0th bit of the output. // Outputs can have as many bits as you want // and be accessed with methods like u8(), char() or i128(). asserteq!(oroutput.b0(ig), true); asserteq!(andoutput.b0(ig), false); ```

Levers! ```rust let l1 = g.lever("l1"); let l2 = g.lever("l2");

let or = g.or2(l1.bit(), l2.bit(), "or"); let oroutput = g.output1(or, "oroutput");

let and = g.and2(l1.bit(), l2.bit(), "and"); let andoutput = g.output1(and, "andoutput");

let ig = &mut g.init();

asserteq!(oroutput.b0(ig), false); asserteq!(andoutput.b0(ig), false);

// _stable means that the graph will run until gate states have stopped changing. // This might not be what you want if you have a circuit that never stabilizes, // like 3 not gates connected in a circle! // See [InitializedGateGraph::rununtilstable]. ig.flipleverstable(l1); asserteq!(oroutput.b0(ig), true); asserteq!(andoutput.b0(ig), false);

ig.flipleverstable(l2); asserteq!(oroutput.b0(ig), true); asserteq!(andoutput.b0(ig), true); ```

SR Latch! ```rust let r = g.lever("l1"); let s = g.lever("l2");

let q = g.nor2(r.bit(), OFF, "q"); let nq = g.nor2(s.bit(), q, "nq");

let qoutput = g.output1(q, "q"); let nqoutput = g.output1(nq, "nq");

// d1() replaces the dependency at index 1 with nq. // We used OFF as a placeholder above. g.d1(q, nq);

let ig = &mut g.init(); // With latches, the initial state should be treated as undefined, // so remember to always reset your latches at the beginning of the simulation. ig.pulseleverstable(r); asserteq!(qoutput.b0(ig), false); asserteq!(nqoutput.b0(ig), true);

ig.pulseleverstable(s); asserteq!(qoutput.b0(ig), true); asserteq!(nqoutput.b0(ig), false);

ig.pulseleverstable(r); asserteq!(qoutput.b0(ig), false); asserteq!(nqoutput.b0(ig), true); ```

The 8 bit computer

In the examples folder you'll find a very simple 8 bit computer, it's a great showcase of what you can achieve by using Rust's constructs to create modular circuit abstractions.

You can play with it in only 3 shell commands! (Assuming you have cargo installed). sh git clone https://github.com/raycar5/logicsim cd logicsim cargo run --release --example computer greeter

Built in circuits

The circuits module features a lot of useful pre-built generic components like:

and many more!

Debugging

Currently there are 2 debugging tools:

Probes

Calling GateGraphBuilder::probe allows you to create probes, which will print the value of all of the bits provided along with their name whenever any of the bits change state within a tick.

Example:

```rust let mut g = GateGraphBuilder::new();

let l1 = g.lever("l1"); let l2 = g.lever("l2");

let or = g.xor2(l1.bit(), l2.bit(), "or"); let xor = g.xor2(l1.bit(), l2.bit(), "xor"); g.probe(&[or,xor],"orxor"); let xoroutput = g.output1(xor, "xor_output");

let ig = &mut g.init(); asserteq!(xoroutput.b0(ig), false);

ig.setleverstable(l1); asserteq!(xoroutput.b0(ig), true);

ig.setleverstable(l2); asserteq!(xoroutput.b0(ig), false);

ig.resetleverstable(l1); asserteq!(xoroutput.b0(ig), true);

ig.resetleverstable(l2); asserteq!(xoroutput.b0(ig), false); In the terminal you'll see: sh orxor: 3 orxor: 1 orxor: 3 orxor: 0 ```

.dot files

Using the method InitializedGateGraph::dump_dot you can generate .dot files which can be viewed in many different graph viewers. I recommend gephi, many others can't handle the size of the graphs generated by logicsim.

For example here is the graph representation of the 8 bit computer:

If we zoom in a bit we can see each node is labeled with it's name which can help debug really weird bugs.

Next steps

License: MIT