Installing Muscat¶

Conda¶

If you use conda, you can install Muscat from the conda-forge channel.

A good practice is to use a separate environment rather than modifying the base environment:

conda create -n my-env
conda activate my-env

The actual install command is:

conda install -c conda-forge muscat

The Conda-Forge packages of Muscat are split in 4 packages :

Muscat-core: Muscat package with the mandatory dependencies.
Muscat-extensions: a meta package with the extra dependencies to enable all functionalities of Muscat.
Muscat: this meta package install Muscat-core and Muscat-extensions to have a full installation in one shot.
Muscat-devenv: is a meta package with the dependencies necessarily for the development, debugging, compilation and documentation generation.

PIP¶

PyPI support is available, but it is currently experimental. For the most stable installation path, prefer the Conda packages above.

Manual Installation (from Sources) for Developers¶

In the case you want the latest developer version, make changes to Muscat or contribute new features, an installation from sources is mandatory. The sources can be downloaded from https://gitlab.com/drti/muscat:

git clone https://gitlab.com/drti/muscat.git

Inside the repository folder, you must compile the C++ extensions to have the optimized algorithms available:

If your hardware architecture includes a GPU, please refer to section Parallel Computations

Compilation¶

You will need CMake version greater than 3.28, and a compiler supporting C++17. An out-of-source build is required by the Muscat CMake project.

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

If you already tried to compile in the source directory, you may already have a file CMakeCache.txt and folders build and CMakeFiles. You should remove the in-source CMakeCache.txt and CMakeFiles entries first.

Compilation with Kokkos, Kokkos-Kernels and ArborX¶

Muscat uses Kokkos for selected native algorithms. The optional Pacman bridge also relies on a compatible Kokkos ecosystem. When compiling the full stack from sources, build and install the projects in the following order:

Kokkos
Kokkos-Kernels
ArborX
Pacman
Muscat

The examples below install each dependency in a local $HOME/local prefix. Adjust the versions, compilers and installation paths to your machine. The same Kokkos backend options must be used consistently across Kokkos, Kokkos-Kernels, ArborX, Pacman and Muscat.

Of course you are free to build your stack with any tool (spack for example).

CPU/OpenMP stack¶

export PREFIX=$HOME/local/muscat-stack-openmp
export KOKKOS_PREFIX=$PREFIX/kokkos
export KOKKOS_KERNELS_PREFIX=$PREFIX/kokkos-kernels
export ARBORX_PREFIX=$PREFIX/arborx
export PACMAN_PREFIX=$PREFIX/pacman

git clone https://github.com/kokkos/kokkos.git
cmake -S kokkos -B build-kokkos \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=$KOKKOS_PREFIX \
    -DKokkos_ENABLE_SERIAL=ON \
    -DKokkos_ENABLE_OPENMP=ON
cmake --build build-kokkos --parallel
cmake --install build-kokkos

git clone https://github.com/kokkos/kokkos-kernels.git
cmake -S kokkos-kernels -B build-kokkos-kernels \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=$KOKKOS_KERNELS_PREFIX \
    -DCMAKE_PREFIX_PATH=$KOKKOS_PREFIX
cmake --build build-kokkos-kernels --parallel
cmake --install build-kokkos-kernels

git clone https://github.com/arborx/ArborX.git
cmake -S ArborX -B build-arborx \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=$ARBORX_PREFIX \
    -DCMAKE_PREFIX_PATH="$KOKKOS_PREFIX;$KOKKOS_KERNELS_PREFIX"
cmake --build build-arborx --parallel
cmake --install build-arborx

git clone https://gitlab.com/drti/pacman.git pacman
cmake -S pacman -B build-pacman \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=$PACMAN_PREFIX \
    -DCMAKE_PREFIX_PATH="$KOKKOS_PREFIX;$KOKKOS_KERNELS_PREFIX;$ARBORX_PREFIX;$CONDA_PREFIX"
cmake --build build-pacman --parallel
cmake --install build-pacman

git clone https://gitlab.com/drti/muscat.git
cmake -S muscat -B build-muscat \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_PREFIX_PATH="$KOKKOS_PREFIX;$KOKKOS_KERNELS_PREFIX;$ARBORX_PREFIX;$PACMAN_PREFIX;$CONDA_PREFIX" \
    -DMuscat_ENABLE_OPENMP=ON
cmake --build build-muscat --parallel

CUDA stack¶

For NVIDIA GPUs, compile all Kokkos-dependent projects with CUDA enabled and use the same GPU architecture for the full stack. Replace AMPERE80 by the Kokkos architecture option matching your hardware.

export PREFIX=$HOME/local/muscat-stack-cuda
export KOKKOS_PREFIX=$PREFIX/kokkos
export KOKKOS_KERNELS_PREFIX=$PREFIX/kokkos-kernels
export ARBORX_PREFIX=$PREFIX/arborx
export PACMAN_PREFIX=$PREFIX/pacman

git clone https://github.com/kokkos/kokkos.git
cmake -S kokkos -B build-kokkos \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=$KOKKOS_PREFIX \
    -DKokkos_ENABLE_SERIAL=ON \
    -DKokkos_ENABLE_CUDA=ON \
    -DKokkos_ARCH_AMPERE80=ON
cmake --build build-kokkos --parallel
cmake --install build-kokkos

git clone https://github.com/kokkos/kokkos-kernels.git
cmake -S kokkos-kernels -B build-kokkos-kernels \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=$KOKKOS_KERNELS_PREFIX \
    -DCMAKE_PREFIX_PATH=$KOKKOS_PREFIX
cmake --build build-kokkos-kernels --parallel
cmake --install build-kokkos-kernels

git clone https://github.com/arborx/ArborX.git
cmake -S ArborX -B build-arborx \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=$ARBORX_PREFIX \
    -DCMAKE_PREFIX_PATH="$KOKKOS_PREFIX;$KOKKOS_KERNELS_PREFIX"
cmake --build build-arborx --parallel
cmake --install build-arborx

git clone https://gitlab.com/drti/pacman.git pacman
cmake -S pacman -B build-pacman \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=$PACMAN_PREFIX \
    -DCMAKE_PREFIX_PATH="$KOKKOS_PREFIX;$KOKKOS_KERNELS_PREFIX;$ARBORX_PREFIX;$CONDA_PREFIX"
cmake --build build-pacman --parallel
cmake --install build-pacman

git clone https://gitlab.com/drti/muscat.git
cmake -S muscat -B build-muscat \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_PREFIX_PATH="$KOKKOS_PREFIX;$KOKKOS_KERNELS_PREFIX;$ARBORX_PREFIX;$PACMAN_PREFIX;$CONDA_PREFIX" \
    -DMuscat_ENABLE_CUDA=ON
cmake --build build-muscat --parallel

Note

The Pacman Python package is optional for Muscat itself, but it is required to use Pacman Interface. Build or install Pacman after ArborX and before running Pacman-based field transfers in Muscat. When building Pacman from source, pass the same CMAKE_PREFIX_PATH entries used above so that it finds the intended Kokkos, Kokkos-Kernels and ArborX installations. If Pacman is installed outside the active Python environment, also ensure that the installed pacman Python module is visible from Python, for example by setting PYTHONPATH accordingly.

Using it in Python¶

Add the MUSCAT_REPOSITORY/build/src/:MUSCAT_REPOSITORY/src/ folders to the PYTHONPATH environment variables (more information on https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH).

Warning

Make sure MUSCAT_REPOSITORY/build/src/ is placed before MUSCAT_REPOSITORY/src/

The user can also install permanently using (Not recommended):

cmake --install build

Building the Documentation¶

The documentation for Muscat can be compiled using a python environment with the following packages:

sphinx
nbsphinx
jupyter
furo
doxygen
ninja

cmake --build build --target doc_html --parallel

Requirements¶

Python Dependencies¶

Python minimal version: 3.9. Some features may be unavailable when optional packages are not installed.

Module Name	Version	Used during (Optional #)				Conda packages name				Notes
Module Name	Version	Compile	Run	Debug	Doc	Muscat-core	Muscat-extensions	Muscat	Muscat-devenv	Notes
python	>=3.10	*	*	*	*	*	*	*	*	Supported distributions are: conda-forge
numpy	>=2	*	*			*	*	*	*	array manipulation and linear algebra
scipy	>=1.12		*			*	*	*	*	sparse (coo_matrix), spatial (KDTree, delaunay, ConvexHull)
sympy		*	*			*	*	*	*	matrices, Symbols, lambdify, Derivative, symplify
cython		*				*	*	*	*	Compilation of c++ extensions
vtk			*	*			*	*	*	stlReader, MeshFieldOperations, ImplicitGeometryObjects, vtkBridge
eigency	>=3.4	*	*			*	*	*	*	Compilation and run of c++ extensions
mkl		*	*			*	*	*	*	Can be deactivated at compilation using the env variable : MUSCAT_USE_MKL = 0
mkl-include		*				*			*	Can be deactivated at compilation using the env variable : MUSCAT_USE_MKL = 0
psutil			#	*	*		*	*	*	memory usage and cpu_count()
dill			#	#	#	*		*	*	for faster Muscat start up (cache finite element shape function pointers)
scikit-sparse			#							Linear solver: Cholesky “cholesky”
pypardiso			#							Linear solver: mkl-Intel Pardiso
matplotlib			#	*			*	*	*	plot shape function for debugin
pyamg			#				*	*	*	linear solver: Algebraic Multigrid “AMG”
h5py			#				*	*	*	xdmf Reader/Writer
meshio			#				*	*	*	main usage in MeshIOBridge.py (derivated usage in Mesh File Converter)
sphinx					*				*	Documentation Generation
sphinx-rtd-theme					*				*	Documentation Generation
breathe					*				*	cmake documentation integration
setuptools-scm									*	Only during conda packaging
pyvista			#				*	*	*	pyvista bridge
networkx	>=3		*			*	*	*	*	only use in MeshGraphTools.py
mpi4py			#							only use in MPIInterface.py
pytest									*	To test Muscat in development face
pywin32			*	*		* (only Win)			* (only Win)	Correctly find exec on disk (only Win)
cvxpy			*				*			Only used in AnisotropicMetricComputation.py

C++ Dependencies¶

Name	Version	Used during				Conda packages name	Notes
Name	Version	Compile	Run	Debug	Doc	Muscat-devenv	Notes
eigen	>=3.4	*				*	For compilation of the C++ extensions
libboost-headers	>=1.8 2	*				*	For the compilation of the extension field transfer
kokkos	>=v4.4	*	*			*	https://github.com/kokkos/kokkos
kokkos-kernels		#	#				Required by external Pacman builds
arborx		#	#			*	Required by Pacman spatial-search routines
pybind11		#	#				Required by Pacman Python bindings
mmg	>=5.8	*	*			*	https://www.mmgtools.org/

External Dependencies¶

Name	Version	Compile	Run	Debug	Doc	Notes
cmake	>=3.22	(*)			*	for the cpp documentation generation
abaqus			#			odb reader. This feature is deprecated (only available on python 2.7, BasicTools 1.7.2)