.. _install: ################# Installing Muscat ################# Conda ***** If you use conda, you can install Muscat CPU version from the `conda-forge channel `_. A good practice is to use a separate environment rather than modifying the base environment: .. code-block:: conda create -n my-env conda activate my-env The actual install command is: .. code-block:: 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. One may consider Muscat-devenv without Kokkos & ArborX packages that will be automatically fetched and configured auto-detecting your GPU hardware if an internet connection is available. PIP *** Pip installation is not available any more. The main reason is the increasing complexity of the building chain (kokkos and Cuda support). Manual Installation (from Sources) for advanced Users and 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 `_: .. code-block:: 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 Nvidia GPU, please refer to the developer section to build a Cuda-enabled Muscat version :ref:`cmake`. For Kokkos::Cuda backend use, please refer to section :ref:`parallel_computation` Compilation =========== You will need cmake version greater than 3.28, and a compiler supporting C++17. .. code-block:: cmake ./superbuild -B build make -j -C build If you already tried to compile, you may already have a file `CMakeCache.txt` and folders `build` and `CMakeFiles`. You should remove them first. Using it in Python ================== Add the ``MUSCAT_REPOSITORY/build/Muscat-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/Muscat-build/src/`` **is placed before** ``MUSCAT_REPOSITORY/src/`` The user can also install permanently using (Not recommended): .. code-block:: make -j -C install Building the Documentation ========================== The documentation for Muscat can be compiled using a python environment with the following packages: - sphinx - nbsphinx - jupyter - furo - doxygen - ninja .. code-block:: make -j -C build doc_html Requirements ************ Python Dependencies =================== Python minimal version: 3.9. Some features may be unavailable when optional packages are not installed. +----------------+-------+-------+-----+-----+----+---------------+---------------------+----------+-----------------+--------------------------------------------+ | | |Used during (Optional #)| Conda packages name |Notes | + + +-------+-----+-----+----+---------------+---------------------+----------+-----------------+ + |Module Name |Version|Compile|Run |Debug|Doc |Muscat-core |Muscat-extensions |Muscat |Muscat-devenv | | +================+=======+=======+=====+=====+====+===============+=====================+==========+=================+============================================+ |python | >=3.9 |\* |\* |\* |\* |\* | \* |\* |\* |Supported distributions are: conda-forge | +----------------+-------+-------+-----+-----+----+---------------+---------------------+----------+-----------------+--------------------------------------------+ |numpy | >=1.21|\* |\* | | |\* | \* |\* |\* |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 | >=2 |\* |\* | | |\* | \* |\* |\* |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 ================ +----------------+------------+-------+---+-----+---+--------------------+----------------------------------------------------+ | | |Used during |Conda packages name |Notes | + + +-------+---+-----+---+--------------------+ + |Name |Version |Compile|Run|Debug|Doc|Muscat-devenv | | +================+============+=======+===+=====+===+====================+====================================================+ |eigen | >=3.4 |\* | | | |\* | For compilation of the C++ extensions | +----------------+------------+-------+---+-----+---+--------------------+----------------------------------------------------+ |libboost-headers| >=1.8 2 |\* | | | |\* | For the compilation of the extension field transfer| +----------------+------------+-------+---+-----+---+--------------------+----------------------------------------------------+ |kokkos | =v4.7.01 |\* |\* | | |\* | https://github.com/kokkos/kokkos | +----------------+------------+-------+---+-----+---+--------------------+----------------------------------------------------+ |arborx | =v2.0.1 |\* |\* | | |\* | https://github.com/arborx/ArborX | +----------------+------------+-------+---+-----+---+--------------------+----------------------------------------------------+ |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)| +------+-------+-------+---+-----+---+-------------------------------------------------+