Debugging AMICI

This document contains some information on how to debug any issues in AMICI, in particular for C++ Python extensions.

Caveman debugging / printf-debugging

The simplest approach may often be adding some print-statements to the code, as this does not require any special tools.

Note that after each change of the C++ files, the AMICI extension as well as the model extension (if any model functions are called), need to be recompiled. The simplest and safest approach would be re-installation of the amici package and re-import of the model. As this can be very time-consuming, the following shortcut is possible, assuming you are using a development installation (pip install -e ...):

# rebuild the amici base extension, from within the amici root directory
# (note that this only recompiles the amici source files, NOT third-party
# dependencies such as sundials):
cd python/sdist/
python build_ext --build-lib .

# rebuild the model, from within the model package directory:
python build_ext --force --build-lib .

Note: Be careful when working interactively, Python may not pick up any changes in already imported modules. The safest is to start a new Python process after any changes.

Using a proper debugger

Debugging with with [gdb]( is most convenient with a minimal reproducible example that is directly invoked from gdb. For example:

# start gdb
gdb --args python -m pytest ../tests/

# inside gdb, set a meaningful breakpoint and launch:
break amici::runAmiciSimulation
# ... (see one of the many gdb tutorials)

Alternative, gdb can attach to a running process by passing the --pid argument.

For many users, it may be more convenient to use gdb via some graphical user interface as provided by various C++ IDEs.


For better debugging experience, but at the cost of runtime performance, consider building the amici and model extension with environment variable ENABLE_AMICI_DEBUGGING=TRUE. This will include debugging symbols and disable compiler optimizations.