Analog-CIM-Sim

Yet another simulator for executing matrix-vector multiplications on analog computing-in-memory crossbars.

If you use the code of this repository, please consider citing the corresponding paper:

@misc{pelke2025optimizingbinaryternaryneural,
    title={{Optimizing Binary and Ternary Neural Network Inference on RRAM Crossbars using CIM-Explorer}},
    author={Rebecca Pelke and José Cubero-Cascante and Nils Bosbach and Niklas Degener and Florian Idrizi
    and Lennart M. Reimann and Jan Moritz Joseph and Rainer Leupers},
    year={2025},
    eprint={2505.14303},
    archivePrefix={arXiv},
    primaryClass={cs.ET},
    url={https://arxiv.org/abs/2505.14303},
}

This simulator is used by CIM-E, a design space exploration tool for neural networks.

The simulator implements several crossbar non-idealities. Not every non-ideality is available for every mapping. The table below tracks which simulation detail is implemented for which crossbar configuration.

Setting digital_only: true bypasses the analog crossbar model completely, so none of the effects below are applied.

All three ADC models are implemented for every mapping type. Which one is valid for a given mapping mode follows from the mapping itself and is checked when the config is loaded, i.e. an invalid combination aborts with an error message: mappings that accumulate a signed column current (the differential ones) require SYM_RANGE_ADC, mappings whose column current is positive-only (I_UINT_W_OFFS, BNN_III, BNN_IV, BNN_V, TNN_IV, TNN_V) require POS_RANGE_ONLY_ADC. INF_ADC models an ideal ADC without quantization and clipping and is always allowed.

To build the project, you will require:

• cmake >= 3.15
• python3 (dev version for pybind11). The build is tested with Python 3.12.
• oneAPI Threading Building Blocks (oneTBB). On Debian-based distributions, sudo apt install libtbb-dev (it may be called tbb-devel on other Linux distributions). For more details see this website.

Clone the repository including submodules:

git clone --recursive git@github.com:rpelke/analog-cim-sim.git

Create a virtual environment and install the build requirements:

python3 -m venv .venv
source .venv/bin/activate
pip3 install -r requirements.txt

Run the build script provided in scripts/build_acs.sh. The script builds Debug by default. Pass -t (or --type) to select Release, RelWithDebInfo or MinSizeRel. -h lists the options.

./scripts/build_acs.sh              # Debug (default)
./scripts/build_acs.sh -t Release   # Release

Execute the tests:

python3 -m unittest discover -s int-bindings/test -p '*_test.py'

This section covers the devcontainer, the manual build, debugging and linting.

Reopen the folder in the devcontainer, the devcontainer.json will automatically build the container. All requirements listed above are already installed in it, as are the linting tools.

Building works exactly as described above:

# Source the virtual environment first
source .venv/bin/activate

./scripts/build_acs.sh              # Debug (default)
./scripts/build_acs.sh -t Release   # Release

Build and install the project manually (replace the placeholders):

export PY_PACKAGE_DIR=<directory containing 'site-packages'> # i.e. .venv/lib/python<python-version>

mkdir -p build/release/build && cd build/release/build
cmake \
    -DCMAKE_BUILD_TYPE=Release \
    -DPY_INSTALL_PATH=${PY_PACKAGE_DIR}/site-packages \
    -DCMAKE_PREFIX_PATH=${PY_PACKAGE_DIR}/pybind11/share/cmake/pybind11 \
    -DCMAKE_INSTALL_PREFIX=../ \
    -DLIB_TESTS=ON \
    -DBUILD_LIB_CB_EMU=ON \
    -DBUILD_LIB_ACS_PY=ON \
    -DBUILD_LIB_ACS_CORE=ON \
    ../../../cpp

make -j `nproc`
make install

This will build all available targets in release mode with support for unittests.

Build project with additional debug output:

cmake -DDEBUG_MODE=ON ...

Build the project with support for coverage:

cmake -DCMAKE_BUILD_TYPE=Debug -DLIB_TESTS=ON -DCOVERAGE=ON ...

Use C++17 filesystem features for the unittests with old gcc versions (<9.1):

cmake -DUSE_STDCXXFS=ON ...

To detect segmentation faults in the C++ part, you can also run:

gdb --batch --ex="run" --ex="bt" --ex="quit" --args python3 -m unittest discover -s int-bindings/test -p '*_test.py'

To manually test the coverage (library was built with -DCOVERAGE=ON set):

cd build/debug/build
ctest -C . --output-on-failure
lcov --capture --directory . --output-file coverage_int.info --include '*cpp*' --exclude '*extern*' \
    --ignore-errors mismatch
genhtml coverage_int.info --output-directory coverage_int_html

--ignore-errors mismatch is required with lcov 2.x (the version shipped by Ubuntu 24.04). With lcov 1.x it can be omitted.

The line and function coverage should be displayed at the end of the genhtml command.

To test the linting locally, you need clang-format-18, shellcheck and shfmt. In the devcontainer, these and the Python packages below are already installed.

Install the required Python packages:

pip install -r util/requirements_style.txt

If the files are correctly formatted, the commands below will not produce any output.

Run:

./util/format_cpp.py
./util/format_py.py
./util/format_sh.py
pymarkdown scan README.md