==========================
Overview and main concepts
==========================

.. contents::
    :depth: 3
    :local:

The ``NonLinearEvolutionProblem`` class
=======================================

The main class of :code:`MFEM/MGIS` is called ``NonLinearEvolutionProblem``
and describes the evolution of the materials of the physical system of
interest over a single time step for a given phenomenon.

Currently :code:`MFEM/MGIS` provides built-in support for mechanics, heat
transfer, and micromorphic damage.

The following snippet declares a new nonlinear evolution problem:

.. code:: c++

   mfem_mgis::NonLinearEvolutionProblem problem(
       {{"MeshFileName", "fuel.msh"},
        {"FiniteElementFamily", "H1"},
        {"FiniteElementOrder", 6},
        {"UnknownsSize", 1},
        {"Hypothesis", "Tridimensional"},
        {"Parallel", true}});

As the unknown is scalar (according to the ``UnknownsSize`` parameter),
this problem can be used to describe heat transfer or micromorphic
damage, depending on the behaviour integrators declared, as explained in
the next section. The ``NonLinearEvolutionProblem`` class supports both
sequential and parallel computations and lets the user exploit a large
subset of ``MFEM`` abilities, including the use of finite elements of
arbitrary orders.

A staggered approach for multiphysics simulations can be set up by using
several instances of ``NonLinearEvolutionProblem``.

The ``PeriodicNonLinearEvolutionProblem`` class
-----------------------------------------------

:code:`MFEM/MGIS` provides a specialized version for the
``NonLinearEvolutionProblem`` for periodic computations named
``PeriodicNonLinearEvolutionProblem``.

This class allows managing the evolutions of the macroscopic gradients
(strain in small strain analysis, deformation gradient in finite strain
analysis, temperature gradient in heat transfer analysis) and pass them
to the behaviour integrators.

Note about linear analyses
--------------------------

As implied by its name, the ``NonLinearEvolutionProblem`` is focused on
nonlinear resolutions. Linear analyses can still be performed by using
linear behaviours (generated by ``MFront``), but with a computational
overhead compared to linear analysis made with optimised kernels, such
as the elastic kernels provided natively by ``MFEM``.

In our experience, this overhead is limited and mostly comes from the
extra flexibility allowed by :code:`MFEM/MGIS`. For instance, ``MFEM``
elastic kernels assume that material properties (Young’s modulus,
Poisson’s ratio) are uniform on each material.

Behaviour integrators
=====================

:code:`MFEM/MGIS` allows the assignment of distinct behaviours to each
material. To achieve this, a special nonlinear formulation has been
implemented which delegates the computations of residual and jacobian
terms on each material to so-called behaviour integrators.

Behaviour integrators are associated with a physical phenomenon and a
modelling hypothesis (plane strain, plane stress).

The following snippet assigns the behaviour integrator named
``Mechanics`` to the material named ``beam`` to the mechanical non
linear evolution problem named ``Mechanics``:

.. code:: c++

   mechanics.addBehaviourIntegrator("Mechanics", "beam",
                                     "src/libBehaviour.so",
                                     "MicromorphicDamageI_SpectralSplit");

The behaviour ``MicromorphicDamageI_SpectralSplit`` is loaded from a
library named ``libBehaviour.so`` which shall have been generated using
``MFront`` before running the simulation. The behaviour integrator
``Mechanics`` supports arbitrary small strain and finite strain
behaviours.

Internally, the ``addBehaviourIntegrator`` method calls an abstract
factory which instanciates a ``BehaviourIntegrator`` dedicated to the
kind of behaviour selected by the user (small or finite strain) and the
modelling hypothesis declared by the problem (plane strain, plane
stress, tridimensional, etc.).

About the definition of material properties
-------------------------------------------

Behaviours may require the user to provide properties, such as the
Young’s modulus, Poisson’s ratio, etc.. In :code:`MFEM/MGIS`, those
properties can be uniform on the material or given by a partial
quadrature function. The latter case allows the properties to be defined
independently on each integration point, which is required if those
properties depend on local material properties or the local state of the
material (for instance, the local temperature).

User interface
==============

The :code:`MFEM/MGIS` library is written in ``C++17`` language.

As the application targets mechanical engineers, it provides a high
level of abstraction, focused on the physical aspects of the simulation
and hiding most numerical details by default.

The API is declarative and mostly based on data structures similar to a
``python`` dictionary, hence limiting direct usage of ``C++``. In
particular, such data structures are used to instantiate non linear
evolution problems, behaviour integrators, post-processings, and
boundary conditions.

.. note:: 

   This data structure can be read from a `JSON`-file allowing to create
   domain-specific applications.

Post-processings
================

Various post-processings are available. Here are some examples of
post-processings that were added to :code:`MFEM/MGIS`:

-  ``ComputeResultantForceOnBoundary``: Compute the resultant of the
   inner forces on a boundary.
-  ``ComputeMeanThermodynamicForcesValues``: Compute the macroscopic
   stress and strain for each material.
-  ``ParaviewExportIntegrationPointResultsAtNodes``: Paraview post
   processing files of partial quadrature functions, like the ones
   associated with the internal state variables.

See Section :ref:`mfem_mgis_post_processings` for a complete description.