tilupy.models.shaltop.read
==========================

.. py:module:: tilupy.models.shaltop.read


Attributes
----------

.. autoapisummary::

   tilupy.models.shaltop.read.LOOKUP_NAMES
   tilupy.models.shaltop.read.AVAILABLE_OUTPUT
   tilupy.models.shaltop.read.READ_FROM_FILE_OUTPUT
   tilupy.models.shaltop.read.FORCES_OUTPUT
   tilupy.models.shaltop.read.INTEGRATED_OUTPUT


Functions
---------

.. autoapisummary::

   tilupy.models.shaltop.read.read_params
   tilupy.models.shaltop.read.read_file_bin
   tilupy.models.shaltop.read.read_file_init


Classes
-------

.. autoapisummary::

   tilupy.models.shaltop.read.Results


Module Contents
---------------

Attributes
^^^^^^^^^^

.. py:data:: LOOKUP_NAMES

   Dictionary of correspondance, to match code output names.

.. py:data:: AVAILABLE_OUTPUT
   :value: ['h', 'hvert', 'u', 'hu', 'hu2', 'ux', 'uy']


   All output available for a shaltop simulation.

   Implemented states:

       - h : Flow thickness (normal to the surface)
       - hvert : True vertical flow thickness
       - ux : Velocity component in X direction
       - uy : Velocity component in Y direction

   Output computed from other output:

       - u : Norm of the velocity (from ux and uy)
       - hu : Momentum flux (from h and u)
       - hu2 : Convective momentum flux (from h and u)

.. py:data:: READ_FROM_FILE_OUTPUT
   :value: ['h_max', 'u_max', 'hu_max', 'hu2_int']


   Output read from the file.

   Read output:

       - h_max : Maximum value of h integrating all time steps
       - u_max : Maximum value of u integrating all time steps
       - hu_max : Maximum value of hu integrating all time steps
       - hu2_int : Integral of values of hu2 for each time steps

.. py:data:: FORCES_OUTPUT
   :value: []


   Force-related output variables, including components in x, y, and additional forces.

   Generated from:

        - faccx, faccy : acceleration force
        - fcurvx, fcurvy : curvature force
        - ffricx, ffricy : friction force
        - fgravx, fgravy : gravitational force
        - finertx, finerty : inertial force
        - fpressionx, fpressiony : pressure force

   Additional variables:

        - shearx, sheary, shearz : shear stresses
        - normalx, normaly, normalz : normal stresses
        - pbottom : basal pressure
        - pcorrdt : pressure correction (time step)
        - pcorrdiv : pressure correction (divergence)

.. py:data:: INTEGRATED_OUTPUT
   :value: ['ek', 'ep', 'etot']


   Integrated energy quantities.

   Implemented energy:

       - ek : kinetic energy
       - ep : potential energy
       - etot : total energy


Functions
^^^^^^^^^

.. py:function:: read_params(file: str) -> dict

   Read simulation parameters from file.

   :param file: Path to the parameters file.
   :type file: str

   :returns: **params** -- Dictionnary with parameters
   :rtype: dict


.. py:function:: read_file_bin(file: str, nx: int, ny: int) -> numpy.ndarray

   Read shaltop .bin result file.

   :param file: Path to the .bin file.
   :type file: str
   :param nx: Number of cells in the X direction.
   :type nx: int
   :param ny: Number of cells in the Y direction.
   :type ny: int

   :returns: Values in the .bin file.
   :rtype: numpy.ndarray


.. py:function:: read_file_init(file: str, nx: int, ny: int) -> numpy.ndarray

   Read shaltop initial .d files.

   :param file: Path to the .d file.
   :type file: str
   :param nx: Number of cells in the X direction.
   :type nx: int
   :param ny: Number of cells in the Y direction.
   :type ny: int

   :returns: Values in the .d file.
   :rtype: numpy.ndarray



Classes
^^^^^^^

.. py:class:: Results(folder=None, file_params=None, **varargs)

   Bases: :py:obj:`tilupy.read.Results`


   Results of shaltop simulations.

   This class is the results class for shaltop. Reading results from shaltop outputs
   are done in this class.

   This class has all the global and quick attributes of the parent class. The quick
   attributes are only computed if needed and can be deleted to clean memory.

   In addition to these attributes, there are those necessary for the operation of
   reading the shaltop results.

   :param folder: Path to the folder containing the simulation files.
   :type folder: str
   :param file_params: Name of the simulation parameters file.
   :type file_params: str

   .. attribute:: _htype

      Always "normal".

      :type: str

   .. attribute:: _tforces

      Times of output.

      :type: list

   .. attribute:: _params

      Dictionary of the simulation parameters.

      :type: dict


   .. py:method:: get_zinit(zinit=None) -> numpy.ndarray

      Get zinit, the initial topography.

      :returns: The initial topography.
      :rtype: numpy.ndarray



   .. py:method:: get_axes(**varargs) -> tuple[numpy.ndarray, numpy.ndarray]

      Get X and Y axes.

      varargs : dict
          All parameters needed to compute the axes :
          :data:`x0`, :data:`y0`, :data:`nx`, :data:`ny`, :data:`per`,
          :data:`pery` and :data:`coord_pos`.

      :returns: Values of X and Y axes.
      :rtype: tuple[numpy.ndarray, numpy.ndarray]



   .. py:method:: get_u() -> numpy.ndarray

      Compute velocity norm from results.

      :returns: Values of flow velocity (norm).
      :rtype: numpy.ndarray