Network simulation

Header: mockturtle/algorithms/simulation.hpp

Examples

Simulate a Boolean input assignment.

aig_network aig = ...;

std::vector<bool> assignment( aig.num_pis() );
assignment[0] = true;
assignment[1] = false;
assignment[2] = false;
...

default_simulator<bool> sim( assignment );
const auto values = simulate<bool>( aig, sim );

aig.foreach_po( [&]( auto const&, auto i ) {
  std::cout << fmt::format( "output {} has simulation value {}\n", i, values[i] );
} );

Complete simulation with truth tables.

aig_network aig = ...;

default_simulator<kitty::dynamic_truth_table> sim( aig.num_pis() );
const auto tts = simulate<kitty::dynamic_truth_table>( aig, sim );

aig.foreach_po( [&]( auto const&, auto i ) {
  std::cout << fmt::format( "truth table of output {} is {}\n", i, kitty::to_hex( tts[i] ) );
} );

Simulate values for all nodes.

aig_network aig = ...;

default_simulator<kitty::dynamic_truth_table> sim( aig.num_pis() );
const auto tts = simulate_nodes<kitty::dynamic_truth_table>( aig, sim );

aig.foreach_node( [&]( auto const& n, auto i ) {
  std::cout << fmt::format( "truth table of node {} is {}\n", i, kitty::to_hex( tts[n] ) );
} );

template<class SimulationType, class Ntk, class Simulator = default_simulator<SimulationType>> std::vector<SimulationType> mockturtle::simulate(Ntk const &ntk, Simulator const &sim = Simulator())

Simulates a network with a generic simulator.

This is a generic simulation algorithm that can simulate arbitrary values. In order to that, the network needs to implement the compute method for SimulationType and one must pass an instance of a Simulator that implements the three methods:

SimulationType compute_constant(bool)
SimulationType compute_pi(index)
SimulationType compute_not(SimulationType const&)

The method compute_constant returns a simulation value for a constant value. The method compute_pi returns a simulation value for a primary input based on its index, and compute_not to invert a simulation value.

This method returns a vector that maps each primary output (ordered by position) to it’s simulation value (taking possible complemented attributes into account).

Required network functions:

foreach_po
is_complemented
compute<SimulationType>

Parameters:

ntk – Network
sim – Simulator, which implements the simulator interface

template<class SimulationType, class Ntk, class Simulator = default_simulator<SimulationType>> node_map<SimulationType, Ntk> mockturtle::simulate_nodes(Ntk const &ntk, Simulator const &sim = Simulator())

Simulates a network with a generic simulator.

This is a generic simulation algorithm that can simulate arbitrary values. In order to that, the network needs to implement the compute method for SimulationType and one must pass an instance of a Simulator that implements the three methods:

SimulationType compute_constant(bool)
SimulationType compute_pi(index)
SimulationType compute_not(SimulationType const&)

The method compute_constant returns a simulation value for a constant value. The method compute_pi returns a simulation value for a primary input based on its index, and compute_not to invert a simulation value.

This method returns a map that maps each node to its computed simulation value.

Required network functions:

foreach_po
get_constant
constant_value
get_node
foreach_pi
foreach_gate
fanin_size
num_pos
compute<SimulationType>

Parameters:

ntk – Network
sim – Simulator, which implements the simulator interface

template<class SimulationType, class Ntk, class Simulator = default_simulator<SimulationType>> void mockturtle::simulate_nodes(Ntk const &ntk, unordered_node_map<SimulationType, Ntk> &node_to_value, Simulator const &sim = Simulator())

Simulates a network with a generic simulator.

This is a generic simulation algorithm that can simulate arbitrary values. In order to that, the network needs to implement the compute method for SimulationType and one must pass an instance of a Simulator that implements the three methods:

SimulationType compute_constant(bool)
SimulationType compute_pi(index)
SimulationType compute_not(SimulationType const&)

The method compute_constant returns a simulation value for a constant value. The method compute_pi returns a simulation value for a primary input based on its index, and compute_not to invert a simulation value.

This method returns a map that maps each node to its computed simulation value.

Required network functions:

foreach_po
get_constant
constant_value
get_node
foreach_pi
foreach_gate
fanin_size
num_pos
compute<SimulationType>

Parameters:

ntk – Network
node_to_value – A map from nodes to values
sim – Simulator, which implements the simulator interface

Simulators

The following simulators are implemented:

mockturtle::default_simulator<bool>: This simulator simulates Boolean values. A vector with assignments for each primary input must be passed to the constructor.
mockturtle::default_simulator<kitty::static_truth_table<NumVars>>: This simulator simulates truth tables. Each primary input is assigned the projection function according to the index. The number of variables must be known at compile time.
mockturtle::default_simulator<kitty::dynamic_truth_table>: This simulator simulates truth tables. Each primary input is assigned the projection function according to the index. The number of variables be passed to the constructor of the simulator.
mockturtle::partial_simulator: This simulator simulates partial truth tables, whose length is flexible and new simulation patterns can be added.

Partial simulation

With partial_simulator, adding new simulation patterns and re-simulation can be done. Incremental simulation is adopted, which speeds up simulation time by only re-simulating needed nodes and only re-computing the last block of partial_truth_table. Note that currently only AIG and XAG are supported.

Constructors

inline mockturtle::partial_simulator::partial_simulator(uint32_t num_pis, uint32_t num_patterns, std::default_random_engine::result_type seed = 1)

Create a partial_simulator with random simulation patterns.

Parameters:

num_pis – Number of primary inputs, which is the same as the length of a simulation pattern.
num_patterns – Number of initial random simulation patterns.

inline mockturtle::partial_simulator::partial_simulator(std::vector<kitty::partial_truth_table> const &initial_patterns)

Create a partial_simulator with given simulation patterns.

Parameters:: initial_patterns – Initial simulation patterns.

inline mockturtle::partial_simulator::partial_simulator(const std::string &filename, uint32_t length = 0u)

Create a partial_simulator with simulation patterns read from a file.

The simulation pattern file should contain num_pis lines of the same length. Each line is the simulation signature of a primary input, represented in hexadecimal.

Parameters:

filename – Name of the simulation pattern file.
length – Number of simulation patterns to keep. Should not be greater than 4 times the length of a line in the file. Setting this parameter to 0 means to keep all patterns in the file.

Interfaces

inline void mockturtle::partial_simulator::add_pattern(std::vector<bool> const &pattern)

Add a pattern (primary input assignment) into the pattern set.

Parameters:: pattern – The pattern. Length should be the same as number of PIs.

inline uint32_t mockturtle::partial_simulator::num_bits() const: Get the current number of simulation patterns.

inline std::vector<kitty::partial_truth_table> mockturtle::partial_simulator::get_patterns() const

Get the simulation patterns.

Returns:: A vector of num_pis() patterns stored in kitty::partial_truth_tables.

Simulation

template<class Ntk, class Simulator = partial_simulator, class Container = unordered_node_map<kitty::partial_truth_table, Ntk>> void mockturtle::simulate_nodes(Ntk const &ntk, Container &node_to_value, Simulator const &sim, bool simulate_whole_tt)

Simulates a network with partial_simulator (or bit_packed_simulator).

This is the specialization for partial_truth_table. This function simulates every node in the circuit.

Parameters:: simulate_whole_tt – When this parameter is true, it is assumed that node_to_value.has( n ) is false for every node. In contrast, when this parameter is false, only the last block of partial_truth_table will be re-computed, and it is assumed that node_to_value.has( n ) is true for every node.

template<class Ntk, class Simulator = partial_simulator, class Container = unordered_node_map<kitty::partial_truth_table, Ntk>> void mockturtle::simulate_node(Ntk const &ntk, typename Ntk::node const &n, Container &node_to_value, Simulator const &sim)

(Re-)simulate n and its transitive fanin cone.

Note that re-simulation (when node_to_value.has( n ) == true) is only done for the last block, no matter how many bits are used in this block. Hence, it is advised to call simulate_nodes with simulate_whole_tt = false whenever sim.num_bits() % 64 == 0.

Bit Packing

To reduce the size of simulation pattern set during pattern generation, bit_packed_simulator can be used instead of partial_simulator, which has additional interfaces to specify care bits in patterns and to perform bit packing.

class bit_packed_simulator : public mockturtle::partial_simulator

Simulates partial truth tables, and performs bit packing when requested.

This class has the same interfaces as partial_simulator, except that (1) care bits should be provided as the second argument of add_pattern; and (2) pack_bits can be called to reduce the size of pattern set.

inline void mockturtle::bit_packed_simulator::add_pattern(std::vector<bool> const &pattern, std::vector<bool> const &care_bits)

Add a pattern (primary input assignment) into the pattern set.

Parameters:

pattern – The pattern. Length should be the same as number of PIs.
care_bits – Care bits of the pattern. Length should be the same as pattern.

inline bool mockturtle::bit_packed_simulator::pack_bits()

Try to pack the newly added patterns (since the last call) into preceding patterns.

Returns:: true when some patterns are packed (so that update of simulated truth tables is needed)