***************
Getting Started
***************

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 (:class:`Muscat.IO` and :class:`Muscat.Bridges`): 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 (:class:`Muscat.MeshTools`): Algorithms to filter, define, extract, and manipulate meshes in various ways.
* Fields manipulation (:class:`Muscat.FE.Fields`): 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 (:class:`Muscat.FE.Integrators`): Algorithms for the integration of weak formulations (tangent matrices, right-hand terms, and integrals over specific sections of a mesh).
* Field transfer (:class:`Muscat.MeshTools.TransferBackEnds.FieldTransferOpPython`): Various Algorithms to transfer fields from one mesh to another.
* Finite element solver (:class:`Muscat.LinAlg`): Leveraging the aforementioned tools, Muscat provides a basic finite element solver for solving generic partial differential equations on unstructured meshes.

Install Muscat 
**************

The easy way, using conda:

.. code-block::

    conda install -c conda-forge muscat

For other installation methods see section :ref:`install`.

Your First Script
*****************

.. code-block::

    from Muscat.IO.VtkReader import VtkReader
    from Muscat.Bridges.CGNSBridge import MeshToCGNS
    from Muscat.IO.CGNSWriter import CGNSWriter

    # read a VTK mesh
    mesh = VtkReader('my_mesh.vtk').Read()

    # Treat your mesh with the many fonctionnalities provided by Muscat
    [...]

    # Convert it to CGNS format
    cgns_mesh = MeshToCGNS(mesh)

    # Or write it directly to disk in CGNS
    CGNSWriter().Write(cgns_mesh, 'processed_mesh.cgns')

You should definitely look at the :ref:`cheat-sheet`.

For more involved examples see section :ref:`exemples`.

You will also find deeper explanations of base principles behind Muscat in section :ref:`principles`.

Asking for Help
***************

Questions can be submitted using the `Issues system of Gitlab <https://gitlab.com/drti/muscat/-/issues>`_.

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 `https://gitlab.com/drti/muscat <https://gitlab.com/drti/muscat>`_
*  create a development branch
*  modify/create changes, commit changes
*  compile Muscat (see section :ref:`cmake`)
*  test your branch (see section :ref:`Tests <run_tests>`)
*  accept the Contribution Agreement (see sections :ref:`license` and :ref:`cla`)
*  push your branch to Gitlab
*  create a merge request

For more explanations read the section :ref:`Developer Documentation <fordevs>`

Citing Muscat
*************

Should you need to cite Muscat you may refer to the following papers:

::

  @inproceedings{bordeu:hal-04823002,
    TITLE = {{Muscat : Mesh manipulation and finite element engine for engineering and science}},
    AUTHOR = {Bordeu, Felipe and de Buhan, Maya and Cortial, Julien and Casenave, Fabien and Messahel, Ramzi},
    URL = {https://hal.science/hal-04823002},
    BOOKTITLE = {{16{\`e}me Colloque National en Calcul de Structures (CSMA 2024)}},
    ADDRESS = {Hy{\`e}res, France},
    ORGANIZATION = {{CNRS and CSMA and ENS Paris-Saclay and CentraleSup{\'e}lec}},
    HAL_LOCAL_REFERENCE = {538903},
    YEAR = {2024},
    MONTH = May,
    KEYWORDS = {Python ; C++ ; Mesh ; Fields ; Finite elements ; Pre ; Processing ; Post ; Treatment},
    PDF = {https://hal.science/hal-04823002v1/file/hal-04823002.pdf},
    HAL_ID = {hal-04823002},
    HAL_VERSION = {v1},
  }

  @article{Bordeu2023,
    doi = {10.21105/joss.05142},
    url = {https://doi.org/10.21105/joss.05142},
    year = {2023},
    publisher = {The Open Journal},
    volume = {8},
    number = {86},
    pages = {5142},
    author = {Felipe Bordeu and Fabien Casenave and Julien Cortial},
    title = {BasicTools: a numerical simulation toolbox},
    journal = {Journal of Open Source Software} }


.. _license:

Muscat License
**************

.. literalinclude:: ../LICENSE.txt

.. _cla:

External Contributions
**********************

For contribution the user must accept the Contribution Agreement. This means the user transfer the property of the contributed code to Safran.

.. literalinclude:: ../CONTRIBUTING.md