Writing Simulation Functions for Primitives

The simulate function for a primitive is called as a method on the instance which is being simulated. Therefore the input and output bits of a primitive can be accessed either through the instance's interface: self.interface.ports['I0'] or simply as an attribute: self.I0. Additionally any initialization parameters attached to the instance can be accessed through self.kwargs. The simulation function for a given primitive can be set via setting the simulate argument for DeclareCircuit or DefineCircuit.

The simulate function must accept 2 parameters besides self: the value store, which is an instance of the ValueStore class, and the state store which is simply a python dictionary.

The value_store parameter is used to get and set the simulated values of given bits in the circuit, with value_store.get_value(bit) and value_store.set_value(bit, newval) respectively.

get_value(bit) returns the current simulated value of bit. If bit is an ArrayType, get_value will return an array of bools for each Bit in the array, otherwise it will simply return a bool.

set_value(bit, newval) will set bit to a the given new value. newval must be a bool or an array of bools if bit is an array.

One implementation detail of the python simulator that needs to be considered is that stateful primitives may be executed before its inputs are initialized. Therefore in general any stateful primitive's simulation function can only access its inputs with get_value when the clock is toggled, otherwise the first execution of the simulation function could access an uninitialized value and the simulator will crash.

The state store parameter begins as an empty python dictionary when simulation starts. This means any simulation needs to check if the dictionary is empty and then initialize default state values when necessary. For example, a simulation function for a flip flop may need to store the previous state of the clock in the state store, and needs to initialize the previous clock value to low when the dictionary is empty.