From 9d50a48e60ae41a049d62d8dfc11cb50652cd6a0 Mon Sep 17 00:00:00 2001 From: spefk Date: Mon, 10 Mar 2025 22:57:48 +0300 Subject: [PATCH 1/2] snapshot --- .gitignore | 2 + BENCHMARKING.md | 0 CMakeLists.txt | 4 +- Makefile | 34 ------ README.md | 161 ++------------------------- app/{simplify.cpp => simplifier.cpp} | 0 tools/table_3_finalizer.py | 4 +- 7 files changed, 18 insertions(+), 187 deletions(-) create mode 100644 BENCHMARKING.md delete mode 100644 Makefile rename app/{simplify.cpp => simplifier.cpp} (100%) diff --git a/.gitignore b/.gitignore index 809fc50..0935132 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,8 @@ ### TMP files .tmp .TMP +_tmp +_TMP experiment_table_* light_review_* diff --git a/BENCHMARKING.md b/BENCHMARKING.md new file mode 100644 index 0000000..e69de29 diff --git a/CMakeLists.txt b/CMakeLists.txt index 48f05f9..eb5badc 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -78,7 +78,7 @@ endif() # ===================================== SIMPLIFY ==================================== # -add_executable(simplify app/simplify.cpp) -target_link_libraries(simplify argparse) +add_executable(simplifier app/simplifier.cpp) +target_link_libraries(simplifier argparse) # *********************************************************************************** # diff --git a/Makefile b/Makefile deleted file mode 100644 index d9275a0..0000000 --- a/Makefile +++ /dev/null @@ -1,34 +0,0 @@ -all: - # zip for the paper shold include: - # - main artifacts, including source code - # - README: - # - link to an artifact - # - additional requirements - # - usage instruction - # - usage on results reproduction - # - LICENSE - mkdir -p build/simplify/simplify/ - # Copy main files to build an artifact - rsync -rv --exclude='*.o' --exclude='*.*.d' app/ build/simplify/simplify/app - rsync -rv --exclude='*.o' --exclude='*.*.d' benchmark/ build/simplify/simplify/benchmark - rsync -rv --exclude='*.o' --exclude='*.*.d' databases/ build/simplify/simplify/databases - rsync -rv --exclude='*.o' --exclude='*.*.d' src/ build/simplify/simplify/src - rsync -rv --exclude='*.o' --exclude='*.*.d' tests/ build/simplify/simplify/tests - rsync -rv --exclude='*.o' --exclude='*.*.d' third_party/ build/simplify/simplify/third_party - rsync -rv --exclude='*.pyc' --exclude='*.pyo' --exclude='__pycache__' --exclude='.env' tools/ build/simplify/simplify/tools - cp .clang-format build/simplify/simplify/.clang-format - cp .clang-tidy build/simplify/simplify/.clang-tidy - cp CMakeLists.txt build/simplify/simplify/CMakeLists.txt - cp LICENSE build/simplify/simplify/LICENSE - cp README.md build/simplify/simplify/README.md - - cd build/simplify/; zip -r simplify.zip simplify - -.PHONY: rebuild -rebuild: - $(MAKE) clean - $(MAKE) all - -clean: - rm -rf build/simplify/simplify/ - rm -f build/simplify/simplify.zip diff --git a/README.md b/README.md index c9e1709..bfcbd3a 100644 --- a/README.md +++ b/README.md @@ -1,134 +1,31 @@ -# Simplify: a New Tool for Boolean Circuit Simplification - - -## Abstract +# Simplifier: a New Tool for Boolean Circuit Simplification The Boolean circuit simplification problem involves finding a smaller circuit that computes the same function as a given Boolean circuit. This problem is closely related to several key areas with both theoretical and practical applications, such as logic synthesis, satisfiability, and verification. -In the paper, we introduce a new tool for simplifying Boolean circuits. The tool optimizes -subcircuits with three inputs and at most three outputs, seeking to improve each one. It is -designed as a low-effort method that runs in just a few seconds for circuits of reasonable -size. This efficiency is achieved by combining two key strategies. First, the tool utilizes -a precomputed database of optimized circuits, generated with SAT solvers after carefully -clustering Boolean functions with three inputs and up to three outputs. Second, we demonstrate -that it is sufficient to check a linear number of subcircuits, relative to the size of the -original circuit. This allows a single iteration of the tool to be executed in linear time. - -This artifact contains the paper and the tool together with detailed instructions on how to -run the tool and reproduce the results from the paper. - -The tool was evaluated on a wide range of Boolean circuits, including both industrial and -hand-crafted examples, in two popular bases: AIG and BENCH. For AIG circuits, after -applying the state-of-the-art ABC framework, the tool achieved an additional 4% average -reduction in size. For BENCH circuits, the tool reduced their size by an average of 30%. - -We pretend to achieve Functional, Reusable, and Available badges. - -The Simplify tool is available both at GitHub repository https://github.com/SPbSAT/circuitsat_tool, -and at Zenodo: [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.13987644.svg)](https://doi.org/10.5281/zenodo.13987644) - -The Simplify tool is ready to be used on the **TACAS 2023 Artifact Evaluation Virtual Machine** -https://zenodo.org/records/7113223 (for more details see sections **Environment configuration** and **Technical info**). -It requires no additional proprietary software, or specific hardware (any moderately modern computer should do). - -The rest of this README contains following sections: - -1. **Early light review** section provides a guideline on performing a **light review** of a tool. -2. **Environment configuration** section contains instructions on installation of requirements. -3. **Usage instruction** section contains instructions on how Simplify tool can be used. -4. **Main results reproduction** provides guidelines on how experiment results presented in the -paper can be reproduced. -5. **Technical info** provides some specific technical details, irrelevant for the paper, but - still giving additional information on the tool itself. - -Each guideline section provides two paths: "all-in-one" command to complete section -and "step-by-step" guide to allow one to evaluate process in details. Note that instructions -in this README are given for the default Ubuntu shell and may not work in other environment. - - -## Early light review - -Partial results suitable for light review can be produced in following steps: - -1. Configure environment using "all-in-one" command (note that C++ sources may take quite a long time to compile): - - ```sh - # ABC tool - (cd third_party/abc/ && make ABC_USE_NO_READLINE=1) - # The simplify tool - cmake -B build/ -DCMAKE_BUILD_TYPE=RELEASE - cmake --build build/ --config RELEASE - # Install python dependencies globally - pip3 install tools/dependencies/* - ``` - -2. The Table 3 is quite easily reproducible, so if there is a need to check - that tool works at all, one can execute following command (which is a copy - of command in relevant section below): - - ```sh - mkdir experiment_table_3 - tar -xvf ./benchmark/representative_benchmarks.tar.xz -C ./experiment_table_3/ - python3.10 tools/cli abc-resyn2 -i experiment_table_3/benchmarks/ -o experiment_table_3/benchmarks_r/ -a third_party/abc/abc -n 1 -s experiment_table_3/r_results.csv - ./build/simplify -i experiment_table_3/benchmarks_r/resyn2_1/ -o experiment_table_3/benchmarks_rs/ -s experiment_table_3/rs_result.csv --basis AIG --databases databases/ - python3.10 tools/cli collect-sizes-aig -i experiment_table_3/benchmarks -s experiment_table_3/benchmark_sizes.csv - python3.10 tools/cli collect-sizes-aig -i experiment_table_3/benchmarks_r/resyn2_1 -s experiment_table_3/benchmark_r_sizes.csv - python3.10 tools/cli collect-sizes-aig -i experiment_table_3/benchmarks_rs -s experiment_table_3/benchmark_rs_sizes.csv - python3.10 tools/cli table-3-finalizer -e experiment_table_3/ - ``` - -3. The Table 4 allows one to select an arbitrary subset of classes to reproduce - results, for example following commands should give results in appropriate time: - - ```sh - mkdir light_review_table_4 - tar -xvf ./benchmark/bench_for_stat.tar.xz -C ./light_review_table_4/ - ./build/simplify -i light_review_table_4/benchmarks/php/ -o light_review_table_4/benchmarks_s/php/ -s light_review_table_4/php_result.csv --basis BENCH --databases databases/ - ./build/simplify -i light_review_table_4/benchmarks/mult_miter/ -o light_review_table_4/benchmarks_s/mult_miter/ -s light_review_table_4/mult_miter_result.csv --basis BENCH --databases databases/ - python3.10 tools/cli table-4-finalizer -e light_review_table_4/ - ``` - - -## Environment configuration - -Before conducting any executions of the tool, it is necessary -to perform a mandatory environment configuration. The tool -itself requires only to be compiled, whilst experiments -framework requires access to the ABC tool executable and -python environment for the utility scripts. - -As a result of configuration steps of this section one should have: +This repository contains source files for ``simplifier``, a tool for boolean circuit simplification. -- Installed additional Ubuntu dependencies; -- Installed `python` packages. -- Compiled `simplify` executable located at `build/simplify`; -- Compiled `ABC` executable located at `third_party/abc/abc`; +## Building -In the other sections of this README it will be assumed, that all shell commands are executed -in the environment with python dependencies, with `abc` and `simplify` executables available at -the paths specified above. - -### All-in-one command +Simplify tool can be compiled using `cmake` tool and a standard `C++` compiler +supporing C++20 standard (`gcc` should do). To build ``simplifier`` binary execute +following steps: ```sh -# ABC tool -(cd third_party/abc/ && make ABC_USE_NO_READLINE=1) -# The simplify tool cmake -B build/ -DCMAKE_BUILD_TYPE=RELEASE cmake --build build/ --config RELEASE -# Install python dependencies globally -pip3 install tools/dependencies/* ``` -### Step-by-step guide +As a result ``simplifier`` binary will be built. To get info on how +``simplifier`` should be used execute resulting binary with following +command: -#### Simplify compilation (C++) +```sh +build/simplify --help +``` -Simplify tool can be compiled using `cmake` tool and a standard `C++` compiler -(`gcc` should do). To build `simplify` binary execute following steps: 1. Compile `cmake` project using command: ```sh @@ -142,40 +39,6 @@ Simplify tool can be compiled using `cmake` tool and a standard `C++` compiler (Note that in `Release` build wast amount of logs is disabled. If one need more logs, `DEBUG` compilation type may be useful.) -As a result ``simplify`` binary will be built. To get info on how ``simplify`` should be used -execute resulting binary with following command: - -```sh -build/simplify --help -``` - -#### ABC compilation - -ABC synthesis tool (and patricullary its `resyn2` command) is a state-of-art framework for circuit -synthesis. It is used in the paper as a baseline solution for a circuit simplification, which allows -one to access contribution and novelty of the Simplify tool. - -For convenience and reproducibility, specific revision of the ABC synthesis tool is vendored -in the `third_party/` directory. To compile it, one need to execute following command: -```sh -(cd third_party/abc/ && make ABC_USE_NO_READLINE=1) -``` - -(see. original repository for details https://github.com/berkeley-abc/abc). - -#### Python dependencies - -Python 3.10 is available in the provided virtual machine and is used -for the scripts located in the `tools/` directory. - -To install additional python dependencies globally execute: - -```sh -pip3 install tools/dependencies/* -``` - -Now you should be able to run CLI of tools. Try to use `python3.10 tools/cli --help` -to get more info on the available CLI commands. ## Usage instruction diff --git a/app/simplify.cpp b/app/simplifier.cpp similarity index 100% rename from app/simplify.cpp rename to app/simplifier.cpp diff --git a/tools/table_3_finalizer.py b/tools/table_3_finalizer.py index 0bcc296..25d1ffd 100644 --- a/tools/table_3_finalizer.py +++ b/tools/table_3_finalizer.py @@ -23,7 +23,7 @@ def table_3_finalizer( ): """ Finalizes statistics collected during "Table 3. Comparison of circuit sizes and - running times between resyn2 and resyn2+simplify" described in the README. + running times between resyn2 and resyn2+Simplifier" described in the README. Note that some paths are hardcoded by intention because this script purpose is solely to finalize a specific experiment (as result, it expects specific files to be @@ -56,7 +56,7 @@ def table_3_finalizer( rs_result = pd.read_csv(experiment_dir_path / "rs_result.csv", delimiter=',') rs_result['circuit_name'] = rs_result['File path'].map(lambda x: x.rsplit('/')[-1]) - rs_result = rs_result.rename(columns={"Simplify time": "time_s"}) + rs_result = rs_result.rename(columns={"Simplifier time": "time_s"}) rs_result = rs_result[['circuit_name', 'time_s', 'Reduced subcircuits by iter']] rs_result['circuit_name'] = rs_result[['circuit_name']].map( From 3cdbda69151a036d5dd8ccdddc738f2338162425 Mon Sep 17 00:00:00 2001 From: spefk Date: Mon, 10 Mar 2025 22:58:07 +0300 Subject: [PATCH 2/2] snapshot --- BENCHMARKING.md | 421 +++++++++++++++++++++++++++++++++++++ README.md | 313 +++------------------------ app/simplifier.cpp | 14 +- tools/table_2_finalizer.py | 6 +- 4 files changed, 465 insertions(+), 289 deletions(-) diff --git a/BENCHMARKING.md b/BENCHMARKING.md index e69de29..dcbd308 100644 --- a/BENCHMARKING.md +++ b/BENCHMARKING.md @@ -0,0 +1,421 @@ +# Simplifier Benchmarking + +This README contains information about how one can conduct tool benchmarking of the tool. +It it divided into the following sections: + +1. **Easy review** section provides a guideline on performing a **light review** of a tool. +2. **Environment configuration** section contains instructions on installation of requirements. +3. **Usage instruction** section contains instructions on how Simplifier tool can be used. +4. **Main results reproduction** provides guidelines on how experiment results presented in the +related paper can be reproduced. +5. **Technical info** provides some specific technical details, irrelevant for the paper, but + still giving additional information on the tool itself. + +Each guideline section provides two paths: "all-in-one" command to complete section +and "step-by-step" guide to allow one to evaluate process in details. Note that instructions +in this README are given for the default Ubuntu shell and may not work in other environment. + +## Easy review + +Partial results suitable for easy review can be produced by the following steps: + +1. Configure environment using "all-in-one" command (note that C++ sources may take quite a long time to compile): + + ```sh + # ABC tool + (cd third_party/abc/ && make ABC_USE_NO_READLINE=1) + # The simplifier tool + cmake -B build/ -DCMAKE_BUILD_TYPE=RELEASE + cmake --build build/ --config RELEASE + # Install python dependencies globally + pip3 install tools/dependencies/* + ``` + +2. The Table 3 is quite easily reproducible, so if there is a need to check + that tool works at all, one can execute following command (which is a copy + of command in relevant section below): + + ```sh + mkdir experiment_table_3 + tar -xvf ./benchmark/representative_benchmarks.tar.xz -C ./experiment_table_3/ + python3.10 tools/cli abc-resyn2 -i experiment_table_3/benchmarks/ -o experiment_table_3/benchmarks_r/ -a third_party/abc/abc -n 1 -s experiment_table_3/r_results.csv + ./build/simplifier -i experiment_table_3/benchmarks_r/resyn2_1/ -o experiment_table_3/benchmarks_rs/ -s experiment_table_3/rs_result.csv --basis AIG --databases databases/ + python3.10 tools/cli collect-sizes-aig -i experiment_table_3/benchmarks -s experiment_table_3/benchmark_sizes.csv + python3.10 tools/cli collect-sizes-aig -i experiment_table_3/benchmarks_r/resyn2_1 -s experiment_table_3/benchmark_r_sizes.csv + python3.10 tools/cli collect-sizes-aig -i experiment_table_3/benchmarks_rs -s experiment_table_3/benchmark_rs_sizes.csv + python3.10 tools/cli table-3-finalizer -e experiment_table_3/ + ``` + +3. The Table 4 allows one to select an arbitrary subset of classes to reproduce + results, for example following commands should give results in appropriate time: + + ```sh + mkdir light_review_table_4 + tar -xvf ./benchmark/bench_for_stat.tar.xz -C ./light_review_table_4/ + ./build/simplifier -i light_review_table_4/benchmarks/php/ -o light_review_table_4/benchmarks_s/php/ -s light_review_table_4/php_result.csv --basis BENCH --databases databases/ + ./build/simplifier -i light_review_table_4/benchmarks/mult_miter/ -o light_review_table_4/benchmarks_s/mult_miter/ -s light_review_table_4/mult_miter_result.csv --basis BENCH --databases databases/ + python3.10 tools/cli table-4-finalizer -e light_review_table_4/ + ``` + +## Environment configuration + +Before conducting any executions of the tool, it is necessary +to perform a mandatory environment configuration. The tool +itself requires only to be compiled, whilst experiments +framework requires access to the ABC tool executable and +python environment for the utility scripts. + +As a result of configuration steps of this section one should have: + +- Installed additional Ubuntu dependencies; +- Installed `python` packages. +- Compiled `simplifier` executable located at `build/simplifier`; +- Compiled `ABC` executable located at `third_party/abc/abc`; + +In the other sections of this README it will be assumed, that all shell commands are executed +in the environment with python dependencies, with `abc` and `simplifier` executables available at +the paths specified above. + +### All-in-one command + +```sh +# ABC tool +(cd third_party/abc/ && make ABC_USE_NO_READLINE=1) +# The simplifier tool +cmake -B build/ -DCMAKE_BUILD_TYPE=RELEASE +cmake --build build/ --config RELEASE +# Install python dependencies globally +pip3 install tools/dependencies/* +``` + +### Step-by-step guide + +#### Simplifier compilation (C++) + +Simplifier tool can be compiled using `cmake` tool and a standard `C++` compiler +(`gcc` should do). To build `simplifier` binary execute following steps: + +1. Compile `cmake` project using command: + ```sh + cmake -B build/ -DCMAKE_BUILD_TYPE=RELEASE + ``` +2. Build `simplifier` tool executable using command: + ```sh + cmake --build build/ --config RELEASE + ``` + +(Note that in `Release` build wast amount of logs is disabled. +If one need more logs, `DEBUG` compilation type may be useful.) + +As a result ``simplifier`` binary will be built. To get info on how ``simplifier`` should be used +execute resulting binary with following command: + +```sh +build/simplifier --help +``` + +#### ABC compilation + +ABC synthesis tool (and patricullary its `resyn2` command) is a state-of-art framework for circuit +synthesis. It is used in the paper as a baseline solution for a circuit simplification, which allows +one to access contribution and novelty of the Simplifier tool. + +For convenience and reproducibility, specific revision of the ABC synthesis tool is vendored +in the `third_party/` directory. To compile it, one need to execute following command: +```sh +(cd third_party/abc/ && make ABC_USE_NO_READLINE=1) +``` + +(see. original repository for details https://github.com/berkeley-abc/abc). + +#### Python dependencies + +Python 3.10 is available in the provided virtual machine and is used +for the scripts located in the `tools/` directory. + +To install additional python dependencies globally execute: + +```sh +pip3 install tools/dependencies/* +``` + +Now you should be able to run CLI of tools. Try to use `python3.10 tools/cli --help` +to get more info on the available CLI commands. + + +## Usage instruction + +The Simplifier tool provides simplification of boolean circuits provided in +one of two bases: `AIG` or `BENCH`. To run simplification one should provide +an `--input-path` and `--output` parameters: first is a path to the directory +with boolean circuits, and second is a path where simplified circuits are to +be stored. Both input and output paths should be directories. Program will +take attempt to read all files in input directory as `.bench` circuits. Each +circuit then will be processed by the tool distinctly. + +Required basis of input circuits should be specified manually using a `--basis` +parameter. It will serve as a hint for the tool, which will help it to choose +suitable algorithm. + +One also should provide a path to the directory with databases containing +(nearly) optimal circuits with three inputs and three outputs by providing +a `--databases` parameter. Note that databases are available at `databases/` +project's root directory, which is a default value for `--databases`. + +To store statistics of the simplification process one may additionally specify +a `--statistics` parameter, which is a path to location where a `*.csv` file +with gathered statistics is to be stored. Note that resulting csv file will use +a `,` character as a delimiter, whilst `;` character may be a valid item value. + +Example usage command: + +```sh +./build/simplifier -i input_circuit/ -o result_circuits/ -s statistics.csv +``` + + +## Main results reproduction + +This section contains guidelines on experiments reproduction, provided in the related paper. +This section provide following set of information: + +1. Name of a subsection represents a name of the corresponding table in the paper; +2. Both "all-in-one" command to run, and a "step-by-step" guide on how results are computed; +3. Description of resulting artifacts and their mappings to results in the paper. + +All instructions presented below carry results of main intermediate steps. To validate +correctness any stage of simplification, one may use utility CLI command `check-equiv`: + +```sh +python3.10 tools/cli check-equiv --help +``` + +#### Statistics descriptions + +Statistics is written in `.csv` files with `,` delimiter. Note that in some data `;` is used in a value part. + +Circuit sizes for `AIG` based tables are given as number of `AND` gates, while for the +`BENCH` based tables size is represented by total number of gates excluding `INPUT`gates. + +Final steps of main results reproduction guidelines print main results to the `stdout` +and save results a file which name pattern is `final_results*.csv` + + +### Table 1. Distribution of classes and functions by circuit size. + +Table 1 humbly represents a distribution of circuit sizes, contained in the database of (nearly) +optimal circuits. This database contains all possible circuits on three inputs and three outputs, +and their particular counts can be reproduced by executing a specialized tool and are not part of +the main statistical result of the paper. + +### Table 2. Comparison of several runs of resyn2 against several runs of resyn2 followed by a run of the Simplifier. + +Note: we are aware that first to columns of sub-table 2 of the Table 2 in the paper are interchanged, +and we apologize for that. We have observed it only after paper deadline passed, and we are intended +to fix it when paper is accepted for publication. + +#### All-in-one command + +```sh +mkdir experiment_table_2 +tar -xvf ./benchmark/all_sets_under_50000_for_stat.tar.xz -C ./experiment_table_2/ +python3.10 tools/cli abc-resyn2 -i experiment_table_2/benchmarks/ -o experiment_table_2/benchmarks_r/ -a third_party/abc/abc -n 2 -n 3 -n 6 -s experiment_table_2/r_results.csv +./build/simplifier -i experiment_table_2/benchmarks_r/resyn2_2/ -o experiment_table_2/benchmarks_r2_s/ -s experiment_table_2/r2_s_result.csv --basis AIG --databases databases/ +./build/simplifier -i experiment_table_2/benchmarks_r/resyn2_6/ -o experiment_table_2/benchmarks_r6_s/ -s experiment_table_2/r6_s_result.csv --basis AIG --databases databases/ +python3.10 tools/cli collect-sizes-aig -i experiment_table_2/benchmarks -s experiment_table_2/benchmark_sizes.csv +python3.10 tools/cli collect-sizes-aig -i experiment_table_2/benchmarks_r/resyn2_3 -s experiment_table_2/benchmark_r3_sizes.csv +python3.10 tools/cli collect-sizes-aig -i experiment_table_2/benchmarks_r/resyn2_6 -s experiment_table_2/benchmark_r6_sizes.csv +python3.10 tools/cli collect-sizes-aig -i experiment_table_2/benchmarks_r2_s -s experiment_table_2/benchmark_r2_s_sizes.csv +python3.10 tools/cli collect-sizes-aig -i experiment_table_2/benchmarks_r6_s -s experiment_table_2/benchmark_r6_s_sizes.csv +python3.10 tools/cli table-2-finalizer -e experiment_table_2/ +``` + +#### Step-by-step guide: + +1. Make clean experiment directory: + +```sh +mkdir experiment_table_2 +``` + +2. Extract `benchmark/all_sets_under_50000_for_stat.tar.xz` to the created directory: + +```sh +tar -xvf ./benchmark/all_sets_under_50000_for_stat.tar.xz -C ./experiment_table_2/ +``` + +3. Run `ABC` `resyn2` on the extracted benchmarks using provided CLI command: + +```sh +python3.10 tools/cli abc-resyn2 -i experiment_table_2/benchmarks/ -o experiment_table_2/benchmarks_r/ -a third_party/abc/abc -n 2 -n 3 -n 6 -s experiment_table_2/r_results.csv +``` + +4. Run `simplifier` tool on several configurations of resulting circuits: + +```sh +./build/simplifier -i experiment_table_2/benchmarks_r/resyn2_2/ -o experiment_table_2/benchmarks_r2_s/ -s experiment_table_2/r2_s_result.csv --basis AIG --databases databases/ +./build/simplifier -i experiment_table_2/benchmarks_r/resyn2_6/ -o experiment_table_2/benchmarks_r6_s/ -s experiment_table_2/r6_s_result.csv --basis AIG --databases databases/ +``` + +5. Collect statistics + +```sh +python3.10 tools/cli collect-sizes-aig -i experiment_table_2/benchmarks -s experiment_table_2/benchmark_sizes.csv +python3.10 tools/cli collect-sizes-aig -i experiment_table_2/benchmarks_r/resyn2_3 -s experiment_table_2/benchmark_r3_sizes.csv +python3.10 tools/cli collect-sizes-aig -i experiment_table_2/benchmarks_r/resyn2_6 -s experiment_table_2/benchmark_r6_sizes.csv +python3.10 tools/cli collect-sizes-aig -i experiment_table_2/benchmarks_r2_s -s experiment_table_2/benchmark_r2_s_sizes.csv +python3.10 tools/cli collect-sizes-aig -i experiment_table_2/benchmarks_r6_s -s experiment_table_2/benchmark_r6_s_sizes.csv +``` + +6. Build final paper-ready statistics + +```sh +python3.10 tools/cli table-2-finalizer -e experiment_table_2/ +``` + +After all commands completed, results are located as follows: + +1. `final_results_1.csv` and `final_results_2.csv` which contains final results as it is presented in the paper, + in first part and a second part of a table respectfully. +2. `r_results.csv` contains statistics on `resyn2` running. +3. `rX_s_result.csv` contains results of `simplifier` evaluation on the relevant scenario `X` (note that sizes in it are calculated as for BENCH basis). +4. `benchmark_*_sizes.csv` contains sizes (measured as number of AND gates) of circuits on different simplification stages. + +### Table 3. Comparison of circuit sizes and running times between resyn2 and resyn2+simplifier + +#### All-in-one command + +```sh +mkdir experiment_table_3 +tar -xvf ./benchmark/representative_benchmarks.tar.xz -C ./experiment_table_3/ +python3.10 tools/cli abc-resyn2 -i experiment_table_3/benchmarks/ -o experiment_table_3/benchmarks_r/ -a third_party/abc/abc -n 1 -s experiment_table_3/r_results.csv +./build/simplifier -i experiment_table_3/benchmarks_r/resyn2_1/ -o experiment_table_3/benchmarks_rs/ -s experiment_table_3/rs_result.csv --basis AIG --databases databases/ +python3.10 tools/cli collect-sizes-aig -i experiment_table_3/benchmarks -s experiment_table_3/benchmark_sizes.csv +python3.10 tools/cli collect-sizes-aig -i experiment_table_3/benchmarks_r/resyn2_1 -s experiment_table_3/benchmark_r_sizes.csv +python3.10 tools/cli collect-sizes-aig -i experiment_table_3/benchmarks_rs -s experiment_table_3/benchmark_rs_sizes.csv +python3.10 tools/cli table-3-finalizer -e experiment_table_3/ +``` + +#### Step-by-step guide + +1. Make clean experiment directory: + +```sh +mkdir experiment_table_3 +``` + +2. Extract `benchmark/representative_benchmarks.tar.xz` to the created directory: + +```sh +tar -xvf ./benchmark/representative_benchmarks.tar.xz -C ./experiment_table_3/ +``` + +3. Run `ABC` `resyn2` on the extracted benchmarks using provided CLI command: + +```sh +python3.10 tools/cli abc-resyn2 -i experiment_table_3/benchmarks/ -o experiment_table_3/benchmarks_r/ -a third_party/abc/abc -n 1 -s experiment_table_3/r_results.csv +``` + +4. Run `simplifier` tool on resulting circuits: + +```sh +./build/simplifier -i experiment_table_3/benchmarks_r/resyn2_1/ -o experiment_table_3/benchmarks_rs/ -s experiment_table_3/rs_result.csv --basis AIG --databases databases/ +``` + +5. Collect benchmark sizes + +```sh +python3.10 tools/cli collect-sizes-aig -i experiment_table_3/benchmarks -s experiment_table_3/benchmark_sizes.csv +python3.10 tools/cli collect-sizes-aig -i experiment_table_3/benchmarks_r/resyn2_1 -s experiment_table_3/benchmark_r_sizes.csv +python3.10 tools/cli collect-sizes-aig -i experiment_table_3/benchmarks_rs -s experiment_table_3/benchmark_rs_sizes.csv +``` + +6. Build final paper-ready statistics + +```sh +python3.10 tools/cli table-3-finalizer -e experiment_table_3/ +``` + +After all commands completed, results are located as follows: + +1. `final_results.csv` contains final result as it is presented in the paper. +2. `r_results.csv` contains statistics on `resyn2` execution. +3. `rs_result.csv` contains results of `simplifier` evaluation (note that sizes in it are calculated as for BENCH basis). +4. `benchmark_sizes.csv` contains information about original circuit sizes. +5. `benchmark_r_sizes.csv` contains information about circuit after `resyn2`. +6. `benchmark_rs_sizes.csv` contains information about circuit after `simplifier`. + +### Table 4. Simplification statistics for various classes of circuits in the BENCH basis. + +#### All-in-one command + +Warning: this command may take extremely long time (several hours on modern computer) to be +executed sequentially, so `simplifier` executions are parallelized by default. If hardware is +unsuitable for such bends of fate, one can either endure and run the sequential test, or run +benchmarking on only a part of classes, picked randomly and unbiased. Yet, some classes may +take up to nearly two hours to be simplified, so proceed with awareness of it. + +```sh +mkdir experiment_table_4 +tar -xvf ./benchmark/bench_for_stat.tar.xz -C ./experiment_table_4/ +./build/simplifier -i experiment_table_4/benchmarks/factorization/ -o experiment_table_4/benchmarks_s/factorization/ -s experiment_table_4/factorization_result.csv --basis BENCH --databases databases/ & +./build/simplifier -i experiment_table_4/benchmarks/ecp/ -o experiment_table_4/benchmarks_s/ecp/ -s experiment_table_4/ecp_result.csv --basis BENCH --databases databases/ & +./build/simplifier -i experiment_table_4/benchmarks/clique/ -o experiment_table_4/benchmarks_s/clique/ -s experiment_table_4/clique_result.csv --basis BENCH --databases databases/ & +./build/simplifier -i experiment_table_4/benchmarks/php/ -o experiment_table_4/benchmarks_s/php/ -s experiment_table_4/php_result.csv --basis BENCH --databases databases/ & +./build/simplifier -i experiment_table_4/benchmarks/I99T/ -o experiment_table_4/benchmarks_s/I99T/ -s experiment_table_4/I99T_result.csv --basis BENCH --databases databases/ & +./build/simplifier -i experiment_table_4/benchmarks/BristolFashion/ -o experiment_table_4/benchmarks_s/BristolFashion/ -s experiment_table_4/BristolFashion_result.csv --basis BENCH --databases databases/ & +./build/simplifier -i experiment_table_4/benchmarks/miter_sum/ -o experiment_table_4/benchmarks_s/miter_sum/ -s experiment_table_4/miter_sum_result.csv --basis BENCH --databases databases/ & +./build/simplifier -i experiment_table_4/benchmarks/miter_thr2/ -o experiment_table_4/benchmarks_s/miter_thr2/ -s experiment_table_4/miter_thr2_result.csv --basis BENCH --databases databases/ & +./build/simplifier -i experiment_table_4/benchmarks/miter_transalg_sort/ -o experiment_table_4/benchmarks_s/miter_transalg_sort/ -s experiment_table_4/miter_transalg_sort_result.csv --basis BENCH --databases databases/ & +./build/simplifier -i experiment_table_4/benchmarks/mult_miter/ -o experiment_table_4/benchmarks_s/mult_miter/ -s experiment_table_4/mult_miter_result.csv --basis BENCH --databases databases/ & +wait +python3.10 tools/cli table-4-finalizer -e experiment_table_4/ +``` + +#### Step-by-step guide + +1. Make clean experiment directory: + +```sh +mkdir experiment_table_4 +``` + +2. Extract `benchmark/bench_for_stat.tar.xz` to the created directory: + +```sh +tar -xvf ./benchmark/bench_for_stat.tar.xz -C ./experiment_table_4/ +``` + +3. Run `simplifier` tool on resulting circuits: + +Warning: this command may take extremely long time (several hours on modern computer) to be +executed sequentially, so `simplifier` executions are parallelized by default. If hardware is +unsuitable for such bends of fate, one can either endure and run the sequential test, or run +benchmarking on only a part of classes, picked randomly and unbiased. Yet, some classes may +take up to nearly two hours to be simplified, so proceed with awareness of it. + +```sh +./build/simplifier -i experiment_table_4/benchmarks/factorization/ -o experiment_table_4/benchmarks_s/factorization/ -s experiment_table_4/factorization_result.csv --basis BENCH --databases databases/ & +./build/simplifier -i experiment_table_4/benchmarks/ecp/ -o experiment_table_4/benchmarks_s/ecp/ -s experiment_table_4/ecp_result.csv --basis BENCH --databases databases/ & +./build/simplifier -i experiment_table_4/benchmarks/clique/ -o experiment_table_4/benchmarks_s/clique/ -s experiment_table_4/clique_result.csv --basis BENCH --databases databases/ & +./build/simplifier -i experiment_table_4/benchmarks/php/ -o experiment_table_4/benchmarks_s/php/ -s experiment_table_4/php_result.csv --basis BENCH --databases databases/ & +./build/simplifier -i experiment_table_4/benchmarks/I99T/ -o experiment_table_4/benchmarks_s/I99T/ -s experiment_table_4/I99T_result.csv --basis BENCH --databases databases/ & +./build/simplifier -i experiment_table_4/benchmarks/BristolFashion/ -o experiment_table_4/benchmarks_s/BristolFashion/ -s experiment_table_4/BristolFashion_result.csv --basis BENCH --databases databases/ & +./build/simplifier -i experiment_table_4/benchmarks/miter_sum/ -o experiment_table_4/benchmarks_s/miter_sum/ -s experiment_table_4/miter_sum_result.csv --basis BENCH --databases databases/ & +./build/simplifier -i experiment_table_4/benchmarks/miter_thr2/ -o experiment_table_4/benchmarks_s/miter_thr2/ -s experiment_table_4/miter_thr2_result.csv --basis BENCH --databases databases/ & +./build/simplifier -i experiment_table_4/benchmarks/miter_transalg_sort/ -o experiment_table_4/benchmarks_s/miter_transalg_sort/ -s experiment_table_4/miter_transalg_sort_result.csv --basis BENCH --databases databases/ & +./build/simplifier -i experiment_table_4/benchmarks/mult_miter/ -o experiment_table_4/benchmarks_s/mult_miter/ -s experiment_table_4/mult_miter_result.csv --basis BENCH --databases databases/ & +wait +``` + +6. Build final paper-ready statistics + +```sh +python3.10 tools/cli table-4-finalizer -e experiment_table_4/ +``` + +After all commands completed, results are located as follows: + +1. `final_results.csv` contains final result as it is presented in the paper. +2. `_result.csv` contains results of `simplifier` evaluation to the circuits of `class` +(note that sizes in it are calculated as for BENCH basis). diff --git a/README.md b/README.md index bfcbd3a..b6f9bab 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ This repository contains source files for ``simplifier``, a tool for boolean cir ## Building -Simplify tool can be compiled using `cmake` tool and a standard `C++` compiler +Simplifier tool can be compiled using `cmake` tool and a standard `C++` compiler supporing C++20 standard (`gcc` should do). To build ``simplifier`` binary execute following steps: @@ -18,340 +18,95 @@ cmake -B build/ -DCMAKE_BUILD_TYPE=RELEASE cmake --build build/ --config RELEASE ``` +(Note that in `Release` build wast amount of logs is disabled. +If one need more logs, `DEBUG` compilation type may be useful.) + As a result ``simplifier`` binary will be built. To get info on how ``simplifier`` should be used execute resulting binary with following command: ```sh -build/simplify --help +build/simplifier --help ``` - -1. Compile `cmake` project using command: - ```sh - cmake -B build/ -DCMAKE_BUILD_TYPE=RELEASE - ``` -2. Build `simplify` tool executable using command: - ```sh - cmake --build build/ --config RELEASE - ``` - -(Note that in `Release` build wast amount of logs is disabled. -If one need more logs, `DEBUG` compilation type may be useful.) - - - ## Usage instruction -The Simplify tool provides simplification of boolean circuits provided in +The Simplifier tool performs simplification of boolean circuits provided in one of two bases: `AIG` or `BENCH`. To run simplification one should provide an `--input-path` and `--output` parameters: first is a path to the directory with boolean circuits, and second is a path where simplified circuits are to -be stored. Both input and output paths should be directories. Program will -take attempt to read all files in input directory as `.bench` circuits. Each -circuit then will be processed by the tool distinctly. +be stored. Both input and output paths should be directories. The tool will +take an attempt to read all files in input directory as `.bench` circuits. +Each circuit will be processed by the tool distinctly. Required basis of input circuits should be specified manually using a `--basis` parameter. It will serve as a hint for the tool, which will help it to choose -suitable algorithm. +suitable simplification algorithms. One also should provide a path to the directory with databases containing (nearly) optimal circuits with three inputs and three outputs by providing -a `--databases` parameter. Note that databases are available at `databases/` -project's root directory, which is a default value for `--databases`. +a `--databases` parameter. Note that databases are available in `databases/` +directory located at the repository root, which is a default value for `--databases`. To store statistics of the simplification process one may additionally specify a `--statistics` parameter, which is a path to location where a `*.csv` file -with gathered statistics is to be stored. Note that resulting csv file will use +with gathered statistics should be dumped. Note that resulting csv file will use a `,` character as a delimiter, whilst `;` character may be a valid item value. Example usage command: ```sh -./build/simplify -i input_circuit/ -o result_circuits/ -s statistics.csv -``` - - -## Main results reproduction - -Experiments reproduction guidelines in this section provide following set of information: - -1. Name of a subsection represents a name of the corresponding table in the paper; -2. Both "all-in-one" command to run, and a "step-by-step" guide on how results are computed; -3. Description of resulting artifacts and their mappings to results in the paper. - -All instructions presented below carry results of main intermediate steps. To validate -correctness any stage of simplification, one may use utility CLI command `check-equiv`: - -```sh -python3.10 tools/cli check-equiv --help +./build/simplifier -i input_circuit/ -o result_circuits/ -s statistics.csv ``` -#### Statistics descriptions +### Statistics format descriptions -Statistics is written in `.csv` files with `,` delimiter. Note that in some data `;` is used in a value part. +Statistics is written in `.csv` files with `,` delimiter. Note that in some +values character `;` is used as internal value separator. Circuit sizes for `AIG` based tables are given as number of `AND` gates, while for the `BENCH` based tables size is represented by total number of gates excluding `INPUT`gates. -Final steps of main results reproduction guidelines print main results to the `stdout` -and save results a file which name pattern is `final_results*.csv` - - -### Table 1. Distribution of classes and functions by circuit size. - -Table 1 humbly represents a distribution of circuit sizes, contained in the database of (nearly) -optimal circuits. This database contains all possible circuits on three inputs and three outputs, -and their particular counts can be reproduced by executing a specialized tool and are not part of -the main statistical result of the paper. - -### Table 2. Comparison of several runs of resyn2 against several runs of resyn2 followed by a run of simplify. - -Note: we are aware that first to columns of sub-table 2 of the Table 2 in the paper are interchanged, -and we apologize for that. We have observed it only after paper deadline passed, and we are intended -to fix it when paper is accepted for publication. - -#### All-in-one command - -```sh -mkdir experiment_table_2 -tar -xvf ./benchmark/all_sets_under_50000_for_stat.tar.xz -C ./experiment_table_2/ -python3.10 tools/cli abc-resyn2 -i experiment_table_2/benchmarks/ -o experiment_table_2/benchmarks_r/ -a third_party/abc/abc -n 2 -n 3 -n 6 -s experiment_table_2/r_results.csv -./build/simplify -i experiment_table_2/benchmarks_r/resyn2_2/ -o experiment_table_2/benchmarks_r2_s/ -s experiment_table_2/r2_s_result.csv --basis AIG --databases databases/ -./build/simplify -i experiment_table_2/benchmarks_r/resyn2_6/ -o experiment_table_2/benchmarks_r6_s/ -s experiment_table_2/r6_s_result.csv --basis AIG --databases databases/ -python3.10 tools/cli collect-sizes-aig -i experiment_table_2/benchmarks -s experiment_table_2/benchmark_sizes.csv -python3.10 tools/cli collect-sizes-aig -i experiment_table_2/benchmarks_r/resyn2_3 -s experiment_table_2/benchmark_r3_sizes.csv -python3.10 tools/cli collect-sizes-aig -i experiment_table_2/benchmarks_r/resyn2_6 -s experiment_table_2/benchmark_r6_sizes.csv -python3.10 tools/cli collect-sizes-aig -i experiment_table_2/benchmarks_r2_s -s experiment_table_2/benchmark_r2_s_sizes.csv -python3.10 tools/cli collect-sizes-aig -i experiment_table_2/benchmarks_r6_s -s experiment_table_2/benchmark_r6_s_sizes.csv -python3.10 tools/cli table-2-finalizer -e experiment_table_2/ -``` - -#### Step-by-step guide: - -1. Make clean experiment directory: - -```sh -mkdir experiment_table_2 -``` - -2. Extract `benchmark/all_sets_under_50000_for_stat.tar.xz` to the created directory: - -```sh -tar -xvf ./benchmark/all_sets_under_50000_for_stat.tar.xz -C ./experiment_table_2/ -``` - -3. Run `ABC` `resyn2` on the extracted benchmarks using provided CLI command: - -```sh -python3.10 tools/cli abc-resyn2 -i experiment_table_2/benchmarks/ -o experiment_table_2/benchmarks_r/ -a third_party/abc/abc -n 2 -n 3 -n 6 -s experiment_table_2/r_results.csv -``` - -4. Run `simplify` tool on several configurations of resulting circuits: - -```sh -./build/simplify -i experiment_table_2/benchmarks_r/resyn2_2/ -o experiment_table_2/benchmarks_r2_s/ -s experiment_table_2/r2_s_result.csv --basis AIG --databases databases/ -./build/simplify -i experiment_table_2/benchmarks_r/resyn2_6/ -o experiment_table_2/benchmarks_r6_s/ -s experiment_table_2/r6_s_result.csv --basis AIG --databases databases/ -``` - -5. Collect statistics - -```sh -python3.10 tools/cli collect-sizes-aig -i experiment_table_2/benchmarks -s experiment_table_2/benchmark_sizes.csv -python3.10 tools/cli collect-sizes-aig -i experiment_table_2/benchmarks_r/resyn2_3 -s experiment_table_2/benchmark_r3_sizes.csv -python3.10 tools/cli collect-sizes-aig -i experiment_table_2/benchmarks_r/resyn2_6 -s experiment_table_2/benchmark_r6_sizes.csv -python3.10 tools/cli collect-sizes-aig -i experiment_table_2/benchmarks_r2_s -s experiment_table_2/benchmark_r2_s_sizes.csv -python3.10 tools/cli collect-sizes-aig -i experiment_table_2/benchmarks_r6_s -s experiment_table_2/benchmark_r6_s_sizes.csv -``` - -6. Build final paper-ready statistics - -```sh -python3.10 tools/cli table-2-finalizer -e experiment_table_2/ -``` - -After all commands completed, results are located as follows: - -1. `final_results_1.csv` and `final_results_2.csv` which contains final results as it is presented in the paper, - in first part and a second part of a table respectfully. -2. `r_results.csv` contains statistics on `resyn2` running. -3. `rX_s_result.csv` contains results of `simplify` evaluation on the relevant scenario `X` (note that sizes in it are calculated as for BENCH basis). -4. `benchmark_*_sizes.csv` contains sizes (measured as number of AND gates) of circuits on different simplification stages. - -### Table 3. Comparison of circuit sizes and running times between resyn2 and resyn2+simplify - -#### All-in-one command - -```sh -mkdir experiment_table_3 -tar -xvf ./benchmark/representative_benchmarks.tar.xz -C ./experiment_table_3/ -python3.10 tools/cli abc-resyn2 -i experiment_table_3/benchmarks/ -o experiment_table_3/benchmarks_r/ -a third_party/abc/abc -n 1 -s experiment_table_3/r_results.csv -./build/simplify -i experiment_table_3/benchmarks_r/resyn2_1/ -o experiment_table_3/benchmarks_rs/ -s experiment_table_3/rs_result.csv --basis AIG --databases databases/ -python3.10 tools/cli collect-sizes-aig -i experiment_table_3/benchmarks -s experiment_table_3/benchmark_sizes.csv -python3.10 tools/cli collect-sizes-aig -i experiment_table_3/benchmarks_r/resyn2_1 -s experiment_table_3/benchmark_r_sizes.csv -python3.10 tools/cli collect-sizes-aig -i experiment_table_3/benchmarks_rs -s experiment_table_3/benchmark_rs_sizes.csv -python3.10 tools/cli table-3-finalizer -e experiment_table_3/ -``` - -#### Step-by-step guide - -1. Make clean experiment directory: - -```sh -mkdir experiment_table_3 -``` - -2. Extract `benchmark/representative_benchmarks.tar.xz` to the created directory: - -```sh -tar -xvf ./benchmark/representative_benchmarks.tar.xz -C ./experiment_table_3/ -``` - -3. Run `ABC` `resyn2` on the extracted benchmarks using provided CLI command: - -```sh -python3.10 tools/cli abc-resyn2 -i experiment_table_3/benchmarks/ -o experiment_table_3/benchmarks_r/ -a third_party/abc/abc -n 1 -s experiment_table_3/r_results.csv -``` - -4. Run `simplify` tool on resulting circuits: - -```sh -./build/simplify -i experiment_table_3/benchmarks_r/resyn2_1/ -o experiment_table_3/benchmarks_rs/ -s experiment_table_3/rs_result.csv --basis AIG --databases databases/ -``` - -5. Collect benchmark sizes - -```sh -python3.10 tools/cli collect-sizes-aig -i experiment_table_3/benchmarks -s experiment_table_3/benchmark_sizes.csv -python3.10 tools/cli collect-sizes-aig -i experiment_table_3/benchmarks_r/resyn2_1 -s experiment_table_3/benchmark_r_sizes.csv -python3.10 tools/cli collect-sizes-aig -i experiment_table_3/benchmarks_rs -s experiment_table_3/benchmark_rs_sizes.csv -``` - -6. Build final paper-ready statistics - -```sh -python3.10 tools/cli table-3-finalizer -e experiment_table_3/ -``` - -After all commands completed, results are located as follows: - -1. `final_results.csv` contains final result as it is presented in the paper. -2. `r_results.csv` contains statistics on `resyn2` execution. -3. `rs_result.csv` contains results of `simplify` evaluation (note that sizes in it are calculated as for BENCH basis). -4. `benchmark_sizes.csv` contains information about original circuit sizes. -5. `benchmark_r_sizes.csv` contains information about circuit after `resyn2`. -6. `benchmark_rs_sizes.csv` contains information about circuit after `simplify`. - -### Table 4. Simplification statistics for various classes of circuits in the BENCH basis. - -#### All-in-one command - -Warning: this command may take extremely long time (several hours on modern computer) to be -executed sequentially, so `simplify` executions are parallelized by default. If hardware is -unsuitable for such bends of fate, one can either endure and run the sequential test, or run -benchmarking on only a part of classes, picked randomly and unbiased. Yet, some classes may -take up to nearly two hours to be simplified, so proceed with awareness of it. - -```sh -mkdir experiment_table_4 -tar -xvf ./benchmark/bench_for_stat.tar.xz -C ./experiment_table_4/ -./build/simplify -i experiment_table_4/benchmarks/factorization/ -o experiment_table_4/benchmarks_s/factorization/ -s experiment_table_4/factorization_result.csv --basis BENCH --databases databases/ & -./build/simplify -i experiment_table_4/benchmarks/ecp/ -o experiment_table_4/benchmarks_s/ecp/ -s experiment_table_4/ecp_result.csv --basis BENCH --databases databases/ & -./build/simplify -i experiment_table_4/benchmarks/clique/ -o experiment_table_4/benchmarks_s/clique/ -s experiment_table_4/clique_result.csv --basis BENCH --databases databases/ & -./build/simplify -i experiment_table_4/benchmarks/php/ -o experiment_table_4/benchmarks_s/php/ -s experiment_table_4/php_result.csv --basis BENCH --databases databases/ & -./build/simplify -i experiment_table_4/benchmarks/I99T/ -o experiment_table_4/benchmarks_s/I99T/ -s experiment_table_4/I99T_result.csv --basis BENCH --databases databases/ & -./build/simplify -i experiment_table_4/benchmarks/BristolFashion/ -o experiment_table_4/benchmarks_s/BristolFashion/ -s experiment_table_4/BristolFashion_result.csv --basis BENCH --databases databases/ & -./build/simplify -i experiment_table_4/benchmarks/miter_sum/ -o experiment_table_4/benchmarks_s/miter_sum/ -s experiment_table_4/miter_sum_result.csv --basis BENCH --databases databases/ & -./build/simplify -i experiment_table_4/benchmarks/miter_thr2/ -o experiment_table_4/benchmarks_s/miter_thr2/ -s experiment_table_4/miter_thr2_result.csv --basis BENCH --databases databases/ & -./build/simplify -i experiment_table_4/benchmarks/miter_transalg_sort/ -o experiment_table_4/benchmarks_s/miter_transalg_sort/ -s experiment_table_4/miter_transalg_sort_result.csv --basis BENCH --databases databases/ & -./build/simplify -i experiment_table_4/benchmarks/mult_miter/ -o experiment_table_4/benchmarks_s/mult_miter/ -s experiment_table_4/mult_miter_result.csv --basis BENCH --databases databases/ & -wait -python3.10 tools/cli table-4-finalizer -e experiment_table_4/ -``` - -#### Step-by-step guide - -1. Make clean experiment directory: - -```sh -mkdir experiment_table_4 -``` - -2. Extract `benchmark/bench_for_stat.tar.xz` to the created directory: - -```sh -tar -xvf ./benchmark/bench_for_stat.tar.xz -C ./experiment_table_4/ -``` - -3. Run `simplify` tool on resulting circuits: - -Warning: this command may take extremely long time (several hours on modern computer) to be -executed sequentially, so `simplify` executions are parallelized by default. If hardware is -unsuitable for such bends of fate, one can either endure and run the sequential test, or run -benchmarking on only a part of classes, picked randomly and unbiased. Yet, some classes may -take up to nearly two hours to be simplified, so proceed with awareness of it. - -```sh -./build/simplify -i experiment_table_4/benchmarks/factorization/ -o experiment_table_4/benchmarks_s/factorization/ -s experiment_table_4/factorization_result.csv --basis BENCH --databases databases/ & -./build/simplify -i experiment_table_4/benchmarks/ecp/ -o experiment_table_4/benchmarks_s/ecp/ -s experiment_table_4/ecp_result.csv --basis BENCH --databases databases/ & -./build/simplify -i experiment_table_4/benchmarks/clique/ -o experiment_table_4/benchmarks_s/clique/ -s experiment_table_4/clique_result.csv --basis BENCH --databases databases/ & -./build/simplify -i experiment_table_4/benchmarks/php/ -o experiment_table_4/benchmarks_s/php/ -s experiment_table_4/php_result.csv --basis BENCH --databases databases/ & -./build/simplify -i experiment_table_4/benchmarks/I99T/ -o experiment_table_4/benchmarks_s/I99T/ -s experiment_table_4/I99T_result.csv --basis BENCH --databases databases/ & -./build/simplify -i experiment_table_4/benchmarks/BristolFashion/ -o experiment_table_4/benchmarks_s/BristolFashion/ -s experiment_table_4/BristolFashion_result.csv --basis BENCH --databases databases/ & -./build/simplify -i experiment_table_4/benchmarks/miter_sum/ -o experiment_table_4/benchmarks_s/miter_sum/ -s experiment_table_4/miter_sum_result.csv --basis BENCH --databases databases/ & -./build/simplify -i experiment_table_4/benchmarks/miter_thr2/ -o experiment_table_4/benchmarks_s/miter_thr2/ -s experiment_table_4/miter_thr2_result.csv --basis BENCH --databases databases/ & -./build/simplify -i experiment_table_4/benchmarks/miter_transalg_sort/ -o experiment_table_4/benchmarks_s/miter_transalg_sort/ -s experiment_table_4/miter_transalg_sort_result.csv --basis BENCH --databases databases/ & -./build/simplify -i experiment_table_4/benchmarks/mult_miter/ -o experiment_table_4/benchmarks_s/mult_miter/ -s experiment_table_4/mult_miter_result.csv --basis BENCH --databases databases/ & -wait -``` - -6. Build final paper-ready statistics - -```sh -python3.10 tools/cli table-4-finalizer -e experiment_table_4/ -``` - -After all commands completed, results are located as follows: - -1. `final_results.csv` contains final result as it is presented in the paper. -2. `_result.csv` contains results of `simplify` evaluation to the circuits of `class` -(note that sizes in it are calculated as for BENCH basis). +## Benchmarking +A detailed step-by-step guide on the tool benchmarking is located in the +[BENCHMARKING.md](./BENCHMARKING.md) file. This guide contains steps to reproduce +results, presented in the related paper. ## Technical info ### Code structure -Main `simplify` directory contains following directories: +Main `simplifier` directory contains following directories: -- `app/` directory contains compilable `simplify.cpp` file, which contains an entry-point (`main`). +- `app/` directory contains compilable `simplifier.cpp` file, which contains an entry-point (`main`). - `benchmarks/` directory contains `tar` archives with boolean circuit benchmarks used for experiments. - `databases/` directory contains databases of the (nearly) optimal small circuits for BENCH and AIG bases. - `src/` directory implements main tool functionalities, and organized as a header-only library. - `tests/` directory implements unit tests for the main functionalities of the tool. - `third_party/` directory contains third-party libraries, used either for the tool itself (`argparse`), code quality checks (`GTest`), or for the experiments conduction (`ABC`). Those libraries are vendored - with the artifact for the completeness and reproducibility. -- `tools/` directory contains CLI utilities useful for experiments and are to be run within + within this repository for the completeness and reproducibility. +- `tools/` directory contains CLI utilities useful for experiments, which are to be run within right `python 3.10` environment. ### Platform -Simplify is written using `C++20`, was developed and tested on the `Ubuntu OS` +Simplifier is written using `C++20`, was developed and tested on the `Ubuntu OS` equipped with `gcc x86-64` compiler, but should not cause any problems on other common Linux distributions. -Experiment environment of a tool includes additional dependencies such as -`ABC tool` and `python 3.10` environment. - ### Dependencies -Simplify tool utilizes external library [argparse](https://github.com/p-ranav/argparse/tree/v2.9) +Simplifier tool utilizes external library [argparse](https://github.com/p-ranav/argparse/tree/v2.9) to ease CLI arguments parsing and usage. Also test framework [GoogleTest](https://github.com/google/googletest) is used to run unit tests which cover main functionalities of the tool. -To make this artifact whole, `argparse` and `gtest` repository snapshots are vendored -alongside it and are presented in the `third_party/` directory. +To make this repository whole, `argparse` and `gtest` repository are vendored as submodules +and are presented in the `third_party/` directory. + +Experiment environment of a tool includes additional dependencies such as +`ABC tool` and `python 3.10` environment. ### Code quality @@ -367,5 +122,5 @@ for equivalence to the original circuits. #### Static code analysis `clang-format` and `clang-tidy` are used for maintaining code quality. -Note that both of them are used as a part of `CI` flow in the linked -GitHub repository, and their execution may be checked there. +Note that both of them are used as a part of `CI` flow, and their execution +may be checked there. diff --git a/app/simplifier.cpp b/app/simplifier.cpp index 284c3c3..5cc06ad 100644 --- a/app/simplifier.cpp +++ b/app/simplifier.cpp @@ -120,7 +120,7 @@ std::optional openFileStat(argparse::ArgumentParser const& progra { std::ofstream statistics_stream(*output_file); statistics_stream << std::setprecision(3) << std::fixed; - statistics_stream << "File path,Gates before,Gates after,Simplify time"; + statistics_stream << "File path,Gates before,Gates after,Simplificaton time"; // The following statistics is currently supported only for AIG basis. if (basis == AIG_BASIS) @@ -219,7 +219,7 @@ void dumpStatistics( * @param logger Logger instance. * @param statistics_stream stream for statistics dumping (if provided). */ -void simplify( +void simplifier( std::string const& instance_path, argparse::ArgumentParser const& program, csat::Logger& logger, @@ -308,10 +308,10 @@ void loadDatabases(argparse::ArgumentParser const& program, csat::Logger const& */ int main(int argn, char** argv) { - csat::Logger logger("Simplify"); + csat::Logger logger("Simplifier"); // Set up argument parser. - argparse::ArgumentParser program("simplify", "0.1"); + argparse::ArgumentParser program("simplifier", "0.1"); program.add_argument("-i", "--input-path").help("directory with input .BENCH files"); program.add_argument("-o", "--output").help("path to resulting directory"); program.add_argument("-s", "--statistics").metavar("FILE").help("path to file for statistics writing"); @@ -321,7 +321,7 @@ int main(int argn, char** argv) .help("Path to a directory with databases."); program.add_description( - "The Simplify tool provides simplification of boolean circuits provided in\n" + "The Simplifier tool provides simplification of boolean circuits provided in\n" "one of two bases: `AIG` or `BENCH`. To run simplification one should provide\n" "an `--input-path` and `--output` parameters: first is a path to the directory\n" "with boolean circuits, and second is a path where simplified circuits are to\n" @@ -345,7 +345,7 @@ int main(int argn, char** argv) "\n" "Example usage command:\n" "\n" - " ./build/simplify -i input_circuit/ -o result_circuits/ -s statistics.csv\n" + " ./build/simplifier -i input_circuit/ -o result_circuits/ -s statistics.csv\n" ""); // Parse provided program arguments. @@ -379,7 +379,7 @@ int main(int argn, char** argv) std::string path = instance_path.path().string(); logger.info("Processing benchmark ", path, "."); - simplify(path, program, logger, statistics_stream); + simplifier(path, program, logger, statistics_stream); } return 0; diff --git a/tools/table_2_finalizer.py b/tools/table_2_finalizer.py index d894797..83953c9 100644 --- a/tools/table_2_finalizer.py +++ b/tools/table_2_finalizer.py @@ -23,7 +23,7 @@ def table_2_finalizer( ): """ Finalizes statistics collected during "Table 2. Comparison of several runs of resyn2 - against several runs of resyn2 followed by a run of simplify." described in the + against several runs of resyn2 followed by a run of Simplifier." described in the README. Note that some paths are hardcoded by intention because this script purpose is @@ -62,7 +62,7 @@ def table_2_finalizer( r6_s_result = pd.read_csv(experiment_dir_path / "r6_s_result.csv", delimiter=',') r6_s_result = r6_s_result.rename( - columns={'File path': 'circuit_name', 'Simplify time': 'time_r6_s'} + columns={'File path': 'circuit_name', 'Simplifier time': 'time_r6_s'} ) r6_s_result = r6_s_result[['circuit_name', 'time_r6_s']] r6_s_result['circuit_name'] = r6_s_result['circuit_name'].apply( @@ -71,7 +71,7 @@ def table_2_finalizer( r2_s_result = pd.read_csv(experiment_dir_path / "r2_s_result.csv", delimiter=',') r2_s_result = r2_s_result.rename( - columns={'File path': 'circuit_name', 'Simplify time': 'time_r2_s'} + columns={'File path': 'circuit_name', 'Simplifier time': 'time_r2_s'} ) r2_s_result = r2_s_result[['circuit_name', 'time_r2_s']] r2_s_result['circuit_name'] = r2_s_result['circuit_name'].apply(