Extending technology mapping and rewriting (#623)

* Adding emap and dependencies

* Adding tests cases, minor fixes

* Adding tests for struct library

* Adding don't care computation in mapping

* Adding don't cares in rewriting

* Improving efficiency in mapping and rewriting with DC

* Fixing bugs in emap, adding multioutput network representation and writer for emap, adding an adder extraction algorithm, adding new standard cell view for multioutput gates, adding utils to decompose multioutput cells into single output for verification reasons, and adding test cases

* Bug fix: possible delay increase when partially-dangling multi-output cells are deselected

* Finishing the support for white_boxes cloning in emap, solving incompatibility between klut_network and choice_view, adding tests for emap with white_boxes

* Adding documentation, changing name of map_adders to extract_adders

* Solving compilation issues, clang formatting, and updating workflows

* Updating block clone_node and relative test

* Changelog update

* Fixes in struct library

* Fixing conversion uint64 into uint32

* Fixing bugs in cuts (possible buffer overflow) and in struct_library

* Date update in emap file

.github/workflows/linux.yml

@@ -99,9 +99,9 @@ jobs:
       run: |
         cd build
         ./test/run_tests "~[quality]"
-  build-clang12:
+  build-clang13:
     runs-on: ubuntu-latest
-    name: Clang 12
+    name: Clang 13
 
     steps:
     - uses: actions/checkout@v1
@@ -111,7 +111,7 @@ jobs:
       run: |
         mkdir build
         cd build
-        cmake -DCMAKE_CXX_COMPILER=clang++-12 -DMOCKTURTLE_TEST=ON ..
+        cmake -DCMAKE_CXX_COMPILER=clang++-13 -DMOCKTURTLE_TEST=ON ..
         make run_tests
     - name: Run tests
       run: |

docs/algorithms/extract_adders.rst

@@ -0,0 +1,6 @@
+Extract adders
+--------------
+
+**Header:** ``mockturtle/algorithms/extract_adders.hpp``
+
+.. doxygenfunction:: mockturtle::extract_adders

docs/algorithms/index_information.rst

@@ -9,4 +9,5 @@ Network information extraction
    dont_cares
    cut_enumeration
    reconv_cut
-   extract_linear
+   extract_linear
+   extract_adders

docs/algorithms/mapper.rst

@@ -98,6 +98,26 @@ database of structures:
    ps.required_time = std::numeric_limits<double>::max();
    sequential<mig_network> res = map( aig, exact_lib, ps );
 
+The newest version of `map` for graph mapping or rewriting can
+leverage satisfiability don't cares:
+
+.. code-block:: c++
+
+   aig_network aig = ...;
+
+   /* load the npn database in the library and compute don't care classes */
+   mig_npn_resynthesis resyn{ true };
+   exact_library_params lps;
+   lps.compute_dc_classes = true;
+   exact_library<mig_network, mig_npn_resynthesis> exact_lib( resyn, lps );
+
+   /* perform area-oriented rewriting */
+   map_params ps;
+   ps.skip_delay_round = true;
+   ps.required_time = std::numeric_limits<double>::max();
+   ps.use_dont_cares = true;
+   mig_network res = map( aig, exact_lib, ps );
+
 As a default setting, cut enumeration minimizes the truth tables.
 This helps improving the results but slows down the computation.
 We suggest to keep it always true. Anyhow, for a faster mapping,
@@ -117,3 +137,79 @@ To increase this limit, change `max_cut_num` in `fast_network_cuts`.
 
 .. doxygenfunction:: mockturtle::map(Ntk const&, tech_library<NInputs, Configuration> const&, map_params const&, map_stats*)
 .. doxygenfunction:: mockturtle::map(Ntk&, exact_library<NtkDest, RewritingFn, NInputs> const&, map_params const&, map_stats*)
+
+
+
+Extended technology mapping
+---------------------------
+
+**Header:** ``mockturtle/algorithms/experimental/emap.hpp``
+
+The command `emap` stands for extended mapper. The current version
+supports up to 2-output gates, such as full adders and half adders,
+and it provides a 2x speedup in mapping time compared to command `map`
+for similar or better quality. Similarly, to `map`, the implementation
+is independent of the underlying graph representation. Moreover, `emap`
+supports "don't touch" white boxes.
+
+The following example shows how to perform delay-oriented technology mapping
+from an and-inverter graph using the default settings:
+
+.. code-block:: c++
+
+   aig_network aig = ...;
+
+   /* read cell library in genlib format */
+   std::vector<gate> gates;
+   std::ifstream in( ... );
+   lorina::read_genlib( in, genlib_reader( gates ) )
+   tech_library tech_lib( gates );
+
+   /* perform technology mapping */
+   binding_view<klut_network> res = emap( aig, tech_lib );
+
+The mapped network is returned as a `binding_view` that extends a k-LUT network.
+Each k-LUT abstracts a cell and the view contains the binding information.
+
+The next example performs area-oriented graph mapping using multi-output cells:
+
+.. code-block:: c++
+
+   aig_network aig = ...;
+
+   /* read cell library in genlib format */
+   std::vector<gate> gates;
+   std::ifstream in( ... );
+   lorina::read_genlib( in, genlib_reader( gates ) )
+   tech_library tech_lib( gates );
+
+   /* perform technology mapping */
+   emap_params ps;
+   ps.area_oriented_mapping = true;
+   ps.map_multioutput = true;
+   cell_view<block_network> res = emap_block( aig, tech_lib, ps );
+
+In this case, `emap_block` is used to return a `block_network`, which can respresent multi-output
+cells as single nodes. Alternatively, also `emap` can be used but multi-output cells
+would be reporesented by single-output nodes.
+
+The maximum number of cuts stored for each node is limited to 32.
+To increase this limit, change `max_cut_num` in `emap`.
+
+For further details and usage scenarios of `emap`, such as white boxes, please check the
+related tests.
+
+**Parameters and statistics**
+
+.. doxygenstruct:: mockturtle::emap_params
+   :members:
+
+.. doxygenstruct:: mockturtle::emap_stats
+   :members:
+
+**Algorithm**
+
+.. doxygenfunction:: mockturtle::emap(Ntk const&, tech_library<NInputs, Configuration> const&, emap_params const&, emap_stats*)
+.. doxygenfunction:: mockturtle::emap_block(Ntk const&, tech_library<NInputs, Configuration> const&, emap_params const&, emap_stats*)
+.. doxygenfunction:: mockturtle::emap_node_map(Ntk const&, tech_library<NInputs, Configuration> const&, emap_params const&, emap_stats*)
+.. doxygenfunction:: mockturtle::emap_load_mapping(Ntk&)

docs/algorithms/rewrite.rst

@@ -12,14 +12,11 @@ networks.  In this case the maximum number of variables for a node function is
    /* derive some MIG */
    mig_network mig = ...;
 
-   /* node resynthesis */
-   mig_npn_resynthesis resyn;
+   /* rewrite */
+   mig_npn_resynthesis resyn{ true };
    exact_library_params eps;
    eps.np_classification = false;
-   exact_library<xag_network, decltype( resyn )> exact_lib( resyn, eps );
-
-   /* rewrite */
-   rewrite( mig, exact_lib );
+   exact_library<mig_network, decltype( resyn )> exact_lib( resyn, eps );
 
 It is possible to change the cost function of nodes in rewrite.  Here is
 an example, in which the cost function only accounts for AND gates in a network,
@@ -42,6 +39,25 @@ which corresponds to the multiplicative complexity of a function.
    exact_library<xag_network, decltype( resyn )> exact_lib( resyn, eps );
    rewrite<decltype( Ntk ), decltype( exact_lib ), mc_cost>( ntk, exact_lib );
 
+Rewrite supports also satisfiability don't cares:
+
+.. code-block:: c++
+
+   /* derive some MIG */
+   mig_network mig = ...;
+
+   /* rewrite */
+   mig_npn_resynthesis resyn{ true };
+   exact_library_params eps;
+   eps.np_classification = false;
+   eps.compute_dc_classes = true;
+   exact_library<mig_network, decltype( resyn )> exact_lib( resyn, eps );
+
+   /* rewrite */
+   rewrite_params ps;
+   ps.use_dont_cares = true;
+   rewrite( mig, exact_lib, ps );
+
 Parameters and statistics
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/changelog.rst

@@ -16,6 +16,7 @@ v0.4 (not yet released)
     - Generic network implementation with additional node types (`generic_network`) `#594 <https://github.com/lsils/mockturtle/pull/594>`_
     - Adding `substitute_node_no_restrash` to `aig_network`, `xag_network`, `mig_network`, `xmg_network`, and `fanout_view` to substitute nodes without structural hashing and simplifications `#616 <https://github.com/lsils/mockturtle/pull/616>`_
     - Adding `replace_in_node_no_restrash` to `aig_network`, `xag_network`, `mig_network`, and `xmg_network` to replace a fanin without structural hashing and simplifications `#616 <https://github.com/lsils/mockturtle/pull/616>`_
+    - Adding a new network type to represent multi-output gates (`block_network`) `#623 <https://github.com/lsils/mockturtle/pull/623>`_
 * Algorithms:
     - AIG balancing (`aig_balance`) `#580 <https://github.com/lsils/mockturtle/pull/580>`_
     - Cost-generic resubstitution (`cost_generic_resub`) `#554 <https://github.com/lsils/mockturtle/pull/554>`_
@@ -33,6 +34,9 @@ v0.4 (not yet released)
     - Extensions and fixes in refactoring (`refactoring`) `#607 <https://github.com/lsils/mockturtle/pull/607>`_
     - Improving LUT mapping, changing its interface, and integrating SOP/ESOP balancing (`lut_map`) `#616 <https://github.com/lsils/mockturtle/pull/616>`_
     - Adding LUT-based SOP and ESOP balancing (`sop_balancing`, `esop_balancing`) `#616 <https://github.com/lsils/mockturtle/pull/616>`_
+    - Adding a new technology mapper supporting multi-output cells (`emap`) `#623 <https://github.com/lsils/mockturtle/pull/623>`_
+    - Adding circuit extraction of half and full adders (`extract_adders`) `#623 <https://github.com/lsils/mockturtle/pull/623>`_
+    - Adding don't care support in rewriting (`map`, `rewrite`) `#623 <https://github.com/lsils/mockturtle/pull/623>`_
 * I/O:
     - Write gates to GENLIB file (`write_genlib`) `#606 <https://github.com/lsils/mockturtle/pull/606>`_
 * Views:
@@ -42,11 +46,16 @@ v0.4 (not yet released)
     - Choice view for management of equivalent classes (`choice_view`) `#594 <https://github.com/lsils/mockturtle/pull/594>`_
     - Deterministic randomization option in topological sorting (`topo_view`) `#594 <https://github.com/lsils/mockturtle/pull/594>`_
     - Fixing MFFC view (`mffc_view`) `#607 <https://github.com/lsils/mockturtle/pull/607>`_
+    - Adding a view to represent standard cells including the multi-output ones (`cell_view`) `#623 <https://github.com/lsils/mockturtle/pull/623>`_
+    - Adding a view to mark nodes as don't touch elements (`dont_touch_view`) `#623 <https://github.com/lsils/mockturtle/pull/623>`_
 * Properties:
     - Cost functions based on the factored form literals count (`factored_literal_cost`) `#579 <https://github.com/lsils/mockturtle/pull/579>`_
 * Utils:
     - Add recursive cost function class to customize cost in resubstitution algorithm (`recursive_cost_function`) `#554 <https://github.com/lsils/mockturtle/pull/554>`_
     - Sum-of-products factoring utilities `#579 <https://github.com/lsils/mockturtle/pull/579>`_
+    - Adding utils to perform pattern matching and derive patterns from standard cells (`struct_library`) `#623 <https://github.com/lsils/mockturtle/pull/623>`_
+    - Adding Boolean matching for multi-output cells (`tech_library`) `#623 <https://github.com/lsils/mockturtle/pull/623>`_
+    - Adding Boolean matching with don't cares for databases (`exact_library`) `#623 <https://github.com/lsils/mockturtle/pull/623>`_
 
 v0.3 (July 12, 2022)
 --------------------

docs/implementations.rst

@@ -270,6 +270,32 @@ All network implementations are located in `mockturtle/networks/`:
 Supplementary network types
 ---------------------------
 
+Block Network
+~~~~~~~~~~~~~
+
+**Header:** ``mockturtle/networks/block.hpp``
+
+This header file defines a data structure of type `block_network`, which is primarily designed to
+represent both single-output and multi-output nodes.
+This data structure provides additional methods to create multi-output nodes and access
+the individual pins.
+
+Additional interfaces provided by this network type include:
+
+.. doxygenfunction:: mockturtle::block_network::is_multioutput
+.. doxygenfunction:: mockturtle::block_network::create_ha
+.. doxygenfunction:: mockturtle::block_network::create_hai
+.. doxygenfunction:: mockturtle::block_network::create_fa
+.. doxygenfunction:: mockturtle::block_network::create_fai
+.. doxygenfunction:: mockturtle::block_network::num_outputs
+.. doxygenfunction:: mockturtle::block_network::incr_fanout_size_pin
+.. doxygenfunction:: mockturtle::block_network::decr_fanout_size_pin
+.. doxygenfunction:: mockturtle::block_network::fanout_size_pin
+.. doxygenfunction:: mockturtle::block_network::node_function_pin
+.. doxygenfunction:: mockturtle::block_network::get_output_pin
+.. doxygenfunction:: mockturtle::block_network::next_output_pin
+
+
 Cover Network
 ~~~~~~~~~~~~~
 
@@ -334,3 +360,27 @@ Specific for `buffered_crossed_klut_network`:
 **Simulation of buffered networks**
 
 .. doxygenfunction:: mockturtle::simulate_buffered
+
+
+Generic Network
+~~~~~~~~~~~~~~~
+
+**Header:** ``mockturtle/networks/generic.hpp``
+
+This header file defines a data structure of type `generic_network`, which is primarily designed to
+represent different node types, such as white and black boxes, registers, input or output box pins.
+This data represent all the elements as nodes, including POs.
+
+Additional interfaces provided by this network type include:
+
+.. doxygenfunction:: mockturtle::generic_network::is_node
+.. doxygenfunction:: mockturtle::generic_network::is_register
+.. doxygenfunction:: mockturtle::generic_network::is_box_input
+.. doxygenfunction:: mockturtle::generic_network::is_box_output
+.. doxygenfunction:: mockturtle::generic_network::create_box_input
+.. doxygenfunction:: mockturtle::generic_network::create_box_output
+.. doxygenfunction:: mockturtle::generic_network::create_register
+.. doxygenfunction:: mockturtle::generic_network::foreach_register
+.. doxygenfunction:: mockturtle::generic_network::clear_values2
+.. doxygenfunction:: mockturtle::generic_network::value2
+.. doxygenfunction:: mockturtle::generic_network::set_value2

docs/utils/util_data_structures.rst

@@ -54,7 +54,7 @@ validity tags to trade efficiency with memory.
 
 .. doxygenfunction:: mockturtle::initialize_copy_network
 
-Tech Library
+Tech library
 ~~~~~~~~~~~~
 
 **Header:** ``mockturtle/utils/tech_library.hpp``
@@ -72,7 +72,7 @@ Tech Library
 
 .. _exact_library:
 
-Exact Library
+Exact library
 ~~~~~~~~~~~~~
 
 **Header:** ``mockturtle/utils/tech_library.hpp``
@@ -101,6 +101,22 @@ Supergates utils
 .. doxygenclass:: mockturtle::super_utils
    :members:
 
+Struct library
+~~~~~~~~~~~~~~
+
+**Header:** ``mockturtle/utils/struct_library.hpp``
+
+.. doc_overview_table:: classmockturtle_1_1struct__library
+   :column: Method
+
+   get_struct_library
+   get_pattern_id
+   get_supergates_pattern
+   print_and_table
+
+.. doxygenclass:: mockturtle::struct_library
+   :members:
+
 Cuts
 ~~~~
 

docs/views.rst

@@ -84,14 +84,22 @@ algorithm.  Several views are implemented in mockturtle.
 .. doxygenclass:: mockturtle::window_view
    :members:
 
-`binding_view`: Add bindings to a technology library
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+`binding_view`: Add bindings from a technology library
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 **Header:** ``mockturtle/views/binding_view.hpp``
 
 .. doxygenclass:: mockturtle::binding_view
    :members:
 
+`cell_view`: Add cell mappings from a technology library
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Header:** ``mockturtle/views/cell_view.hpp``
+
+.. doxygenclass:: mockturtle::cell_view
+   :members:
+
 `names_view`: Assign names to signals and outputs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -108,6 +116,14 @@ algorithm.  Several views are implemented in mockturtle.
 .. doxygenclass:: mockturtle::names_view
    :members:
 
+`dont_touch_view`: Mark nodes as "don't touch"
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Header:** ``mockturtle/views/dont_touch_view.hpp``
+
+.. doxygenclass:: mockturtle::dont_touch_view
+   :members:
+
 `cnf_view`: Creates a CNF while creating a network
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~