Installation¶

You can install smudgy in several ways. OpenMP support is optional but recommended for parallel performance. See the OpenMP Support section for details on how to setup OpenMP before installation.

Install from PyPI (recommended)

pip install smudgy

To build from source, clone the repository and install

git clone https://github.com/maurbe/smudgy.git
cd smudgy
pip install .

OpenMP Support¶

To enable parallelization, you must have OpenMP installed on your system before installing smudgy. If OpenMP is not found, smudgy will still work, but parallelization will be disabled. To install it, see instructions for your operating system below. If you are unsure whether OpenMP is installed correctly, download the src/omp_test.cpp file from the repository and test the OpenMP installation depending on your OS.

Linux

Most Linux distributions provide OpenMP support out of the box with the gcc compiler.

Install the required packages:

sudo apt-get update
sudo apt-get install -y libomp-dev

Test it:

g++ -fopenmp omp_test.cpp -o omp_test
./omp_test # should print "OpenMP available"

MacOS

Apple’s Clang compiler does not support OpenMP by default. To install it OpenMP, follow these steps.

First, install the Xcode Command Line Tools:

xcode-select --install

Then, install libomp via Homebrew:

brew update
brew install libomp

Then, export the necessary environment variables:

export OMP_PREFIX="$(brew --prefix libomp)"
export CPPFLAGS="-I${OMP_PREFIX}/include"
export LDFLAGS="-L${OMP_PREFIX}/lib"
export CFLAGS="-Xpreprocessor -fopenmp ${CPPFLAGS}"
export CXXFLAGS="-Xpreprocessor -fopenmp ${CPPFLAGS}"

Test it:

clang++ -Xpreprocessor -fopenmp omp_test.cpp \
    -I${OMP_PREFIX}/include \
    -L${OMP_PREFIX}/lib -lomp \
    -o omp_test
./omp_test # should print "OpenMP available"

Windows

Caution

Windows is currently not officially supported. However, the following instructions are provided for users who wish to attempt installation on Windows systems.

MSVC is recommended for Windows users as it already includes OpenMP. The build system will automatically enable OpenMP if available. Compile and test it:

cl /openmp omp_test.cpp
omp_test.exe # should print "OpenMP available"

Running the Test Suite¶

After installation, it is highly recommended to run the test suite to verify your installation and check OpenMP support.

Identify the smudgy installation directory and run pytest:

python -m pytest "$(python -c 'import smudgy, os; print(os.path.dirname(smudgy.__file__))')"

The tests will automatically check for OpenMP availability and skip parallelization tests if OpenMP is not enabled or detected. If you see tests being skipped due to missing OpenMP, revisit the OpenMP Support section to ensure your environment is set up correctly.

If you have any issues, please consult the documentation or open an issue on GitHub.