Simulator Overview

Contributing Author @fpintos

General View

The simulation is composed of a collection of circuits, elements, nodes and wires.

• Each tab in the simulator is a circuit; you can add a circuit to another, in which case it is called a sub-circuit.
  • Sub-circuits allow you to build reusable pieces and hide complexity.
• Elements are the things you drag from the toolbox: inputs, outputs, gates, clocks, etc.
• Nodes are connection points, they are the green circles in the elements and the wires.
• Wires are the connections between one node and another.

Elements contains nodes and these nodes work either as input or output pins in their parent element. Input nodes will provide value TO the element; output nodes carry a value FROM its parent element to another. Two nodes are connected by a wire. Each node has a corresponding bitWidth, which dictates how many bits its value can carry - each bit would correspond to a single physical pin or wire in a real circuit.

CircuitElement

CircuitElement is the base class of all elements. Elements carry their associated state data and know how to draw, save and load themselves and how to calculate their next state.

Here are some methods to know if you plan on fixing elements or creating new ones:

• The constructor must take at least three parameters: x, y & scope; these are the position coordinates and an object that indicates which circuit the element belongs to - usually you just pass those to the base class.
• If the element has state that must be persisted it will receive them as additional constructor arguments.
• Nodes are created in the element's constructor as well. The element decides where the nodes are positioned in relationship to the center of the element.
• customSave must return an object with the nodes and the extra constructor parameters needed by the element; do not include the x/y/scope parameters in this save data as the base class takes care of it.
• newBitWidth is called when the user changes the bitWidth of the element. The element usually responds by changing the bitWidth of child nodes. To prevent bitWidth changes, set fixedBitWidth to true.
• isResolvable and resolve: these are called on every simulation cycle in order to compute the next state of the element. Elements can play nice by returning false in isResolvable if they can detect that they will not produce a change (to speed up the simulation). resolve must use the element's state and the value of its input pins to produce the next state and to update the value of its output nodes. Nodes that change value should be added to the simulationQueue, so they will be processes as well.
• customDraw: as the name implies, this is called to draw the element on a canvas. There is no DOM manipulation in the simulator area, it is all canvas. There are custom functions in the canvasApi.js file, which help deal with elements that are rotated and they also deal with zoom, so use them.

Scope

The scope object contains all elements, nodes and wires that make up a particular circuit, along with other fields needed to draw, manipulate and simulate the circuit.

Each instance of an element belongs to a scope, which is how circuits are known in the code.

A global variable, called globalScope contains the circuit that is currently selected. When elements are created, they attach themselves to this global scope.

One can argue that we should be calling these Circuit and currentCircuit instead of 'scope'. :-)

More Information

If you want to learn more about the elements, start with modules.js, sequential.js and logix.js.