From 44d1b69c5210097a2c17e4d7fe6d58f02cb2d101 Mon Sep 17 00:00:00 2001 From: panhongyang Date: Tue, 28 Feb 2023 20:04:23 +0800 Subject: [PATCH] docs --- abc | 1 - docs/balance.rst | 9 ++++++++ docs/cec.rst | 11 ++++++++++ docs/create_graph.rst | 32 +++++++++++++++++++++++++++ docs/load.rst | 5 ++++- docs/lut_mapping.rst | 16 ++++++++++++++ docs/lutmap.rst | 17 +++++++++++++++ docs/read.rst | 11 ++++++++++ docs/reduction.rst | 15 +++++++++++++ docs/refactor.rst | 9 ++++++++ docs/resub.rst | 14 ++++++++++++ docs/resyn.rst | 12 +++++++++++ docs/rewrite.rst | 12 +++++++++++ docs/sim.rst | 23 ++++++++++++++++++++ docs/techmap.rst | 20 +++++++++++++++++ docs/write.rst | 50 +++++++++++++++++++++++++++++++++++++++++++ 16 files changed, 255 insertions(+), 2 deletions(-) delete mode 160000 abc diff --git a/abc b/abc deleted file mode 160000 index 581c58b..0000000 --- a/abc +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 581c58b9c48772b549dc921fd7c854484470ed8c diff --git a/docs/balance.rst b/docs/balance.rst index e69de29..c2409aa 100644 --- a/docs/balance.rst +++ b/docs/balance.rst @@ -0,0 +1,9 @@ +Balance +============= + +**Header:** ``mockturtle/algorithms/balancing.hpp`` + +Balancing of a logic network + +This function implements a dynamic-programming and cut-enumeration based balancing algorithm. +It returns a new network of the same type and performs generic balancing by providing a rebalancing function. \ No newline at end of file diff --git a/docs/cec.rst b/docs/cec.rst index e69de29..d1c202e 100644 --- a/docs/cec.rst +++ b/docs/cec.rst @@ -0,0 +1,11 @@ +Cec +============= + +**Header:** ``mockturtle/algorithms/equivalence_checking.hpp`` + +Combinational equivalence checking. + +This function expects as input a miter circuit that can be generated, e.g., with the function miter. +It returns an optional which is nullopt, if no solution can be found, this happens when a resource limit is set using the function parameters. +Otherwise it returns true, if the miter is equivalent or false, if the miter is not equivalent. +In the latter case the counter example is written to the statistics pointer as a std::vector following the same order as the primary inputs. \ No newline at end of file diff --git a/docs/create_graph.rst b/docs/create_graph.rst index e69de29..74e8ce8 100644 --- a/docs/create_graph.rst +++ b/docs/create_graph.rst @@ -0,0 +1,32 @@ +Create_graph +============= + +**Header:** ``mockturtle/algorithms/klut_to_graph.hpp`` + +This header file implements utility functions to convert a :math:`k`-LUT network into a +homogeneous graph network, such as AIG, XAG, MIG or XMG. It wraps around three node resynthesis strategies for the user. + +First the function attempts a Disjoint Support Decomposition (DSD), branching the network into subnetworks. +As soon as DSD can no longer be done, there are two possibilities depending on the dimensionality of the subnetwork to be resynthesized. +On the one hand, if the size of the associated support is lower or equal than 4, the solution can be recovered by exploiting the mapping of the subnetwork to its NPN-class. +On the other hand, if the support size is higher than 4, A Shannon decomposition is performed, branching the network in further subnetworks with reduced support. +Finally, once the threshold value of 4 is reached, the NPN mapping completes the graph definition. + +There is an out-of-place version, and an in-place version of the function. + +The following example shows how to convert a :math:`k`-LUT network into an AIG, a XAG, a MIG and a XMG. + +.. code-block:: c++ + + /* derive some k-LUT */ + const klut_network klut = ...; + + /* out-of-place version */ + aig_network aig = convert_klut_to_graph( klut ); + xag_network xag = convert_klut_to_graph( klut ); + + /* in-place version */ + mig_network mig; + xmg_network xmg; + convert_klut_to_graph( mig, klut ); + convert_klut_to_graph( xmg, klut ); \ No newline at end of file diff --git a/docs/load.rst b/docs/load.rst index 39b959f..ed577b4 100644 --- a/docs/load.rst +++ b/docs/load.rst @@ -2,4 +2,7 @@ Load ============= The header ```` implements methods to load -a hexdecimal string represented truth table. \ No newline at end of file +a hexdecimal string represented truth table. + +It implements a dynamic truth table by the header ````. +A dynamic truth table can be initialized with a number of variables that is computed at runtime. \ No newline at end of file diff --git a/docs/lut_mapping.rst b/docs/lut_mapping.rst index e69de29..3c41894 100644 --- a/docs/lut_mapping.rst +++ b/docs/lut_mapping.rst @@ -0,0 +1,16 @@ +Lut_mapping +============= + +**Header:** ``mockturtle/algorithms/collapse_mapped.hpp`` + +Collapse mapped network into k-LUT network. + +Collapses a mapped network into a k-LUT network. In the mapped network each cell is represented in terms of a collection of nodes from the subject graph. This method creates a new network in which each cell is represented by a single node. + +This function performs some optimizations with respect to possible output complementations in the subject graph: + +If an output driver is only used in positive form, nothing changes + +If an output driver is only used in complemented form, the cell function of the node is negated. + +If an output driver is used in both forms, two nodes will be created for the mapped node. \ No newline at end of file diff --git a/docs/lutmap.rst b/docs/lutmap.rst index e69de29..e4689ee 100644 --- a/docs/lutmap.rst +++ b/docs/lutmap.rst @@ -0,0 +1,17 @@ +Lutmap +============= + +**Header:** ``mockturtle/algorithms/lut_mapper.hpp`` + +LUT mapping with cut size :math:`k` partitions a logic network into mapped +nodes and unmapped nodes, where a mapped node :math:`n` is assigned some cut +:math:`(n, L)` such that the following conditions hold: i) each node that +drives a primary output is mapped, and ii) each leaf in the cut of a mapped +node is either a primary input or also mapped. This ensures that the mapping +covers the whole logic network. LUT mapping aims to find a good mapping with +respect to a cost function, e.g., a short critical path in the mapping or a +small number of mapped nodes. The LUT mapping algorithm can assign a weight +to a cut for alternative cost functions. + +This implementation offers delay- or area-oriented mapping. The mapper can be +configured using many options. \ No newline at end of file diff --git a/docs/read.rst b/docs/read.rst index e69de29..816ba0e 100644 --- a/docs/read.rst +++ b/docs/read.rst @@ -0,0 +1,11 @@ +Read +============= + +The phyLS implements several reader callbacks that can be used with the lorina_ library. +The header ``mockturtle/io/_reader.hpp`` implements the reader callback ``_reader``. + +Example: +:: + read_aiger xxx.aig; // read an aiger as input + +.. _lorina: https://github.com/hriener/lorina diff --git a/docs/reduction.rst b/docs/reduction.rst index e69de29..c5c0ef7 100644 --- a/docs/reduction.rst +++ b/docs/reduction.rst @@ -0,0 +1,15 @@ +Reduction +============= + +**Header:** ``mockturtle/algorithms/functional_reduction.hpp`` + +The following example shows how to perform functional reduction +to remove constant nodes and functionally equivalent nodes in +the network. + +.. code-block:: c++ + + /* derive some AIG */ + aig_network aig = ...; + + functional_reduction( aig ); \ No newline at end of file diff --git a/docs/refactor.rst b/docs/refactor.rst index e69de29..93f1019 100644 --- a/docs/refactor.rst +++ b/docs/refactor.rst @@ -0,0 +1,9 @@ +Refactor +============= + +**Header:** ``mockturtle/algorithms/refactoring.hpp`` + +It is possible to change the cost function of nodes in refactoring. Here is +an example, in which the cost function does not account for XOR gates in a network. +This may be helpful in logic synthesis addressing cryptography applications where +XOR gates are considered "for free". \ No newline at end of file diff --git a/docs/resub.rst b/docs/resub.rst index e69de29..787d16c 100644 --- a/docs/resub.rst +++ b/docs/resub.rst @@ -0,0 +1,14 @@ +Resub +============= + +**Header:** ``mockturtle/algorithms/resubstitution.hpp`` + +Several resubstitution algorithms are implemented and can be called directly, including: + +- ``default_resubstitution`` does functional reduction within a window. + +- ``aig_resubstitution``, ``mig_resubstitution`` and ``xmg_resubstitution`` do window-based resubstitution in the corresponding network types. + +- ``resubstitution_minmc_withDC`` minimizes multiplicative complexity in XAGs with window-based resubstitution. + +- ``sim_resubstitution`` does simulation-guided resubstitution in AIGs or XAGs. \ No newline at end of file diff --git a/docs/resyn.rst b/docs/resyn.rst index e69de29..de43f8f 100644 --- a/docs/resyn.rst +++ b/docs/resyn.rst @@ -0,0 +1,12 @@ +Resyn +============= + +**Headers:** ``mockturtle/algorithms/resyn_engines/mig_resyn.hpp``, ``mockturtle/algorithms/resyn_engines/xag_resyn.hpp`` + +The problem of *logic resynthesis* is defined as follows: + +Given a *target* function :math:`f` and a set of *divisor* functions :math:`g_1, ..., g_n`, find a *dependency function* :math:`h` such that :math:`f=h(g_1, ..., g_n)`. + +Specifically, the dependency function is represented by a *dependency circuit* of a certain network type and we aim at finding a small dependency circuit. +The logic resynthesis engines can be used in resubstitution to find the replacement for the root node. +Interfacing resubstitution functors (see :ref:`resubstitution_structure` of the resubstitution framework) are provided in ``mockturtle/algorithms/mig_resub.hpp`` and ``mockturtle/algorithms/sim_resub.hpp``. diff --git a/docs/rewrite.rst b/docs/rewrite.rst index e69de29..1d3a359 100644 --- a/docs/rewrite.rst +++ b/docs/rewrite.rst @@ -0,0 +1,12 @@ +Rewrite +============= + +**Header:** ``mockturtle/algorithms/mig_algebraic_rewriting.hpp`` + +**Header:** ``mockturtle/algorithms/xag_algebraic_rewriting.hpp`` + + +Majority algebraic depth rewriting. + +This algorithm tries to rewrite a network with majority gates for depth optimization using the associativity and distributivity rule in majority-of-3 logic. +It can be applied to networks other than MIGs, but only considers pairs of nodes which both implement the majority-of-3 function. \ No newline at end of file diff --git a/docs/sim.rst b/docs/sim.rst index e69de29..462cfcf 100644 --- a/docs/sim.rst +++ b/docs/sim.rst @@ -0,0 +1,23 @@ +Sim +============= + +**Header:** ``mockturtle/algorithms/simulation.hpp`` + +Simulates a network with a generic simulator. +This is a generic simulation algorithm that can simulate arbitrary values. + +The following simulators are implemented: + +* ``mockturtle::default_simulator``: This simulator simulates Boolean + values. A vector with assignments for each primary input must be passed to + the constructor. +* ``mockturtle::default_simulator>``: 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``: 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. \ No newline at end of file diff --git a/docs/techmap.rst b/docs/techmap.rst index e69de29..8522fa7 100644 --- a/docs/techmap.rst +++ b/docs/techmap.rst @@ -0,0 +1,20 @@ +Techmap +============= + +**Header:** ``mockturtle/algorithms/mapper.hpp`` + +A versatile mapper that supports technology mapping and graph mapping +(optimized network conversion). The mapper is independent of the +underlying graph representation. Hence, it supports generic subject +graph representations (e.g., AIG, and MIG) and a generic target +representation (e.g. cell library, XMG). The mapper aims at finding a +good mapping with respect to delay, area, and switching power. + +The mapper uses a library (hash table) to facilitate Boolean matching. +For technology mapping, it needs `tech_library` while for graph mapping +it needs `exact_library`. For technology mapping, the generation of both NP- and +P-configurations of gates are supported. Generally, it is convenient to use +NP-configurations for small or medium size cell libraries. For bigger libraries, +P-configurations should perform better. You can test both the configurations to +see which one has the best run time. For graph mapping, NPN classification +is used instead. \ No newline at end of file diff --git a/docs/write.rst b/docs/write.rst index e69de29..93b5e1d 100644 --- a/docs/write.rst +++ b/docs/write.rst @@ -0,0 +1,50 @@ +Write into file formats +----------------------- + +Write into AIGER files +~~~~~~~~~~~~~~~~~~~~~~ + +**Header:** ``mockturtle/io/write_aiger.hpp`` + +Writes a combinational AIG network in binary AIGER format into a file. + +This function should be only called on “clean” aig_networks. + +Write into BENCH files +~~~~~~~~~~~~~~~~~~~~~~ + +**Header:** ``mockturtle/io/write_bench.hpp`` + +Writes network in BENCH format into a file. + +Write into BLIF files +~~~~~~~~~~~~~~~~~~~~~~ + +**Header:** ``mockturtle/io/write_blif.hpp`` + +Writes network in BLIF format into a file. + +Write into structural Verilog files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Header:** ``mockturtle/io/write_verilog.hpp`` + +Writes network in structural Verilog format into a file. + +Write into DIMACS files (CNF) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Header:** ``mockturtle/io/write_cnf.hpp`` + +Writes network into CNF DIMACS format. + +It also adds unit clauses for the outputs. Therefore a satisfying solution is one that makes all outputs 1. + +.. _write_dot: + +Write into DOT files (Graphviz) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Header:** ``mockturtle/io/write_dot.hpp`` + +Writes network in DOT format into a file.