****************** What is Muscat ****************** Muscat was primarily designed as a basic set of tools to work on meshes in the context of finite element computations. The main functionalities of the library include: * IO support: A set of classes that enable reading and writing meshes (as well as solution fields) from/to a wide variety of file formats. Muscat does not have its own file format because existing formats already provide most, if not all, of the required functionalities. * Mesh manipulation: Algorithms to filter, define, extract, and manipulate meshes in various ways. * Fields manipulation: Finite element fields can be defined using different types of interpolation (P0/P1/P2), either across the entire mesh or only in specific zones, as well as at integration points. These classes have overloaded operators to facilitate the computation of relevant quantities. * Integration: Algorithms for the integration of weak formulations (tangent matrices, right-hand terms, and integrals over specific sections of a mesh). * Field transfer: Various Algorithms to transfer fields from one mesh to another. * Finite element solver: Leveraging the aforementioned tools, Muscat provides a basic finite element solver for solving generic partial differential equations on unstructured meshes. ********************* Installing Muscat ********************* Conda ----- If you use conda, you can install Muscat from the conda-forge channels [#anacondaurl]_. 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. 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 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 gitlab.com [#gitlaburlpublic]_: .. 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 GPU, 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 . -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/src/:MUSCAT_REPOSITORY/src/`` folders to the ``PYTHONPATH`` environment variables (more information on [#pythonpathdoc]_). **Make sure ``MUSCAT_REPOSITORY/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 *************** Asking for Help *************** Questions can be submitted using the Issues system of Gitlab [#gitlaburlpublicissues]_. Bugs should ideally be reported with a *minimal non working example* to make debugging easier for the developers. ************************** Contributing to Muscat ************************** If you want to contribute some code you must: * clone the master branch of Muscat from [#gitlaburlpublic]_ * create a development branch * modify/create changes, commit changes * compile Muscat * test your branch (see section :ref:`fordevs`) * accept the Contribution Agreement (see section :ref:`license`) * push your branch to Gitlab * create a merge request ************ 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| +----------------+------------+-------+---+-----+---+--------------------+----------------------------------------------------+ |TBB |>=v2021.11.0|\* |\* | | |\* | For the compilation and runtime of field transfer | +----------------+------------+-------+---+-----+---+--------------------+----------------------------------------------------+ |kokkos |>=v4.5.01 |\* |\* | | |\* | https://github.com/kokkos/kokkos | +----------------+------------+-------+---+-----+---+--------------------+----------------------------------------------------+ |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)| +------+-------+-------+---+-----+---+-------------------------------------------------+ .. rubric:: Footnotes .. [#gitlaburlpublic] https://gitlab.com/drti/muscat .. [#gitlaburlpublicissues] https://gitlab.com/drti/muscat/-/issues .. [#anacondaurl] https://anaconda.org/ .. [#scikitwindows] https://github.com/xmlyqing00/Cholmod-Scikit-Sparse-Windows .. [#eigenurl] http://eigen.tuxfamily.org .. [#pythonpathdoc] `https://docs.python.org/3/using/cmdline.html\#envvar-PYTHONPATH `_