****************** 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 --- The pip installation requires a local compilation, so you need to have a C++ (C++17 compatible) compiler installed locally on your system. Two C++ libraries, Eigen and boost, are needed during compilation (we onnly use the header only part of these libraries). Eigen can be found inside the pip package eignecy. To use this embedded version the MUSCAT_USE_EIGENCYEIGEN must be set to 1. The C++ boost library is not present in PyPi so a manual installation is required. To compile and install Muscat (version 2.3.0 in this case) with pip: .. code-block:: wget https://boostorg.jfrog.io/artifactory/main/release/1.82.0/source/boost_1_82_0.zip unzip boost_1_82_0.zip set MUSCAT_USE_EIGENCYEIGEN=1 set MUSCAT_EXTRA_INCLUDE_DIRS=%cd%\boost_1_82_0 pip install eigency mkl numpy sympy mkl-include cython wheel tbb-devel dill pip install Muscat@https://gitlab.com/drti/muscat/-/archive/2.3.0/muscat-2.3.0.tar.bz2 or for the latest master version: .. code-block:: wget https://boostorg.jfrog.io/artifactory/main/release/1.82.0/source/boost_1_82_0.zip unzip boost_1_82_0.zip set MUSCAT_USE_EIGENCYEIGEN=1 set MUSCAT_EXTRA_INCLUDE_DIRS=%cd%\boost_1_82_0 pip install eigency mkl numpy sympy mkl-include cython wheel tbb-devel dill pip install Muscat@git+https://gitlab.com/drti/muscat.git .. note:: On linux/OsX you must: - Change the `set` to `export` or `setenv` depending on your os/shell - Change the `%cd%` to `$PWD` depending on your os/shell The user can set the environment variable `PREFIX` to point to external libraries (like mkl and eigen header). For advanced configuration please refer to the setup.py file on the git repository. It is also a good practice to use a virtual environment when using pip. .. note:: We can not guarantee that every combination of operating system, Python version and packaging system works. Manual installation (from sources) for developers ------------------------------------------------- In the case you want to 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` .. code-block:: cmake . -B build make -j -C build Add the ``MUSCAT_REPOSITORY/build/src/:MUSCAT_REPOSITORY/src/`` folders to the ``PYTHONPATH`` environment variables (more information on [#pythonpathdoc]_). Or using pip for development: .. code-block:: pip install -e . The user can also install permanently using (Not recommended): .. code-block:: make -j -C install The documentation for Muscat can be compiled using sphinx: .. code-block:: make -j -C 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 AnisotropicMetricComput.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 | +----------------+------------+-------+---+-----+---+--------------------+----------------------------------------------------+ External Dependencies --------------------- +------+-------+-------+---+-----+---+-------------------------------------------------+ |Name |Version|Compile|Run|Debug|Doc|Notes | +======+=======+=======+===+=====+===+=================================================+ |cmake | >=3.22|(\*) | | |\* | for the cpp documentation generation | | | | | | | | (*) experimental cmake extensions compilation | +------+-------+-------+---+-----+---+-------------------------------------------------+ |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 `_