Model and integral operators
============================

The class :cpp:class:`tamaas::Model` (and its counterpart :py:class:`Model <tamaas._tamaas.Model>`) is both a central class in Tamaas and one of the simplest. It mostly serves as holder for material properties, fields and integral operators, and apart from a linear elastic behavior does not perform any computation on its own.

Model types
-----------

:cpp:class:`tamaas::Model` has a concrete subclass :cpp:class:`tamaas::ModelTemplate` which implements the model function for a given :cpp:type:`tamaas::model_type`:

:cpp:enumerator:`tamaas::basic_2d`
     Model type used in normal frictionless contact: traction and displacement are 2D fields with only one component.

:cpp:enumerator:`tamaas::surface_2d`
     Model type used in frictional contact: traction and displacement are 2D fields with three components.

:cpp:enumerator:`tamaas::volume_2d`
     Model type used in elastoplastic contact: tractions are the same as with :cpp:enumerator:`tamaas::surface_2d` but the displacement is a 3D field.

The enumeration values suffixed with ``_1d`` are the one dimensional (line contact) counterparts of the above model types. The domain physical dimension and number of components are encoded in the class :cpp:class:`tamaas::model_type_traits`.

Model creation and basic functionality
--------------------------------------

The instanciation of a :py:class:`Model <tamaas._tamaas.Model>` is done with the :py:class:`ModelFactory <tamaas._tamaas.ModelFactory>` class and its :py:func:`createModel <tamaas._tamaas.ModelFactory.createModel>` function::

  physical_size = [1., 1.]
  discretization = [512, 512]
  model = tm.ModelFactory.createModel(tm.model_type.basic_2d, physical_size, discretization)

.. warning::
   For models of type ``volume_*d``, the first component of the ``physical_size`` and ``discretization`` arrays corresponds to the depth dimension (:math:`z` in most cases). For example::

     tm.ModelFactory.createModel(tm.model_type.basic_2d, [0.3, 1, 1], [64, 81, 81])

   creates a model of depth 0.3 and surface size 1\ :superscript:`2`, while the number of points is 64 in depth and 81\ :sup:`2` on the surface. This is done for data contiguity reasons, as we do discrete Fourier transforms in the horizontal plane.

.. note::
   If ran in an MPI context, the method :py:meth:`createModel
   <tamaas._tamaas.ModelFactory.createModel>` expects the *global* system sizes
   and discretization of the model.

The properties ``E`` and ``nu`` can be used to set the Young's modulus and Poisson ratio respectively::

  model.E = 1
  model.nu = 0.3

Fields can be easlily accessed with the ``[]`` operator, similar to Python's dictionaries::

  surface_traction = model['traction']

To know what fields are available, you can call the :py:func:`getFields <tamaas._tamaas.Model.getFields>` method. You can add new fields to a model object with :py:func:`registerField <tamaas._tamaas.Model.registerField>`, which is convenient for dumping. A model can also be used to compute stresses from a strain field::

  import numpy as np

  strain = np.zeros(model.shape + [6])  # Mandel--Voigt notation
  stress = np.zeros_like(strain)

  model.applyElasticity(stress, strain)

Model dumpers
-------------

The submodule `tamaas.dumpers` contains a number of classes to save model data into different formats:

:py:class:`UVWDumper <tamaas.dumpers.UVWDumper>`
    Dumps a model to `VTK <https://vtk.org/>`_ format. Requires the `UVW <https://github.com/prs513rosewood/uvw>`_ python package which you can install with pip::

      pip install uvw

    This dumper is made for visualization with VTK based software like `Paraview <https://www.paraview.org/>`_.

:py:class:`NumpyDumper <tamaas.dumpers.NumpyDumper>`
    Dumps a model to a compressed Numpy file.

:py:class:`H5Dumper <tamaas.dumpers.H5Dumper>`
    Dumps a model to a compressed `HDF5 <https://support.hdfgroup.org/HDF5/>`_ file. Requires the `h5py <https://www.h5py.org/>`_ package.

The dumpers are initialzed with a basename and the fields that you wish to write to file (optionally you can set ``all_fields`` to ``True`` to dump all fields in the model). By default, each write operation creates a new file in a separate directory (e.g. :py:class:`UVWDumper <tamaas.dumpers.UVWDumper>` creates a ``paraview`` directory). To write to a specific file you can use the `dump_to_file` method. Here is a usage example::

  from tamaas.dumpers import UVWDumper, H5Dumper

  # Create dumper
  uvw_dumper = UVWDumper('rough_contact_example', 'stress', 'plastic_strain')

  # Dump model
  uvw_dumper << model

  # Or alternatively
  model.addDumper(H5Dumper('rough_contact_archive', all_fields=True))
  model.addDumper(uvw_dumper)
  model.dump()

The last ``model.dump()`` call will call both dumpers. The resulting files will have the following hierachy::

  ./paraview/rough_contact_example_0000.vtr
  ./paraview/rough_contact_example_0001.vtr
  ./hdf5/rough_contact_archive_0000.h5
    

.. note::
   Currently, only :py:class:`H5Dumper <tamaas.dumpers.H5Dumper>` supports
   parallel output with MPI.