..
  SPDX-FileCopyrightText: 2018 SeisSol Group

  SPDX-License-Identifier: BSD-3-Clause
  SPDX-LicenseComments: Full text under /LICENSE and /LICENSES/

  SPDX-FileContributor: Author lists in /AUTHORS and /CITATION.cff

ASAGI
=====

The software package `ASAGI <https://github.com/TUM-I5/ASAGI>`__ can be
used to map gridded simulation properties of the domain to the mesh used
for a SeisSol simulation.
ASAGI reads NetCDF files, which follow the COARDS Convention for netCDF files.
This convention in particular states that:

 `"1-dimensional netCDF variables whose dimension names are identical to their variable names are regarded as "coordinate variables"."`

Here is an example of the structure of an ASAGI file (generated by `ncdump -h test_ASAGI.nc`), describing two 2D arrays (strike_slip and dip_slip) indexed by variables u and v.

.. code-block:: bash

    netcdf test_ASAGI {
    types:
      compound material {
        float strike_slip ;
        float dip_slip ;
      }; // material
    dimensions:
            u = 40 ;
            v = 20 ;
    variables:
            float u(u) ;
            float v(v) ;
            material data(v, u) ;
    }

Typically, 1D, 2D, and 3D ASAGI files are used in SeisSol setups.


.. _installing_ASAGI:

Installing ASAGI
----------------

Be careful that the python and gcc package is the same as for the
compilation of SeisSol in a later step.
First clone ASAGI with:

.. code-block:: bash

  git clone git@github.com:TUM-I5/ASAGI
  # git clone https://github.com/TUM-I5/ASAGI.git
  cd ASAGI
  git submodule update --init

Set compiler options, e.g. for intel compilers on SuperMUC:

.. code-block:: bash

  export FC=mpif90
  export CXX=mpiCC
  export CC=mpicc

Run cmake, and compile with:

.. code-block:: bash

  mkdir build && cd build
  CMAKE_PREFIX_PATH=$NETCDF_BASE
  cmake .. -DSHARED_LIB=no -DSTATIC_LIB=yes -DCMAKE_INSTALL_PREFIX=$HOME
  make -j 48
  make install
  (Know errors: 1.Numa could not found - turn off Numa by adding -DNONUMA=on . )


Building SeisSol with ASAGI support
-----------------------------------

Simply turn on the option ``ASAGI=ON`` in the using ccmake.

Generating the NetCDF input file
--------------------------------

Using python
~~~~~~~~~~~~~~~

The most straightforward way to generate ASAGI file is to use the netCDF4 module of python.
A typical example which generates a 2D ASAGI file can be found
`here <https://github.com/SeisSol/SeisSol/tree/master/preprocessing/science/generating_ASAGI_file.py>`__.

Using asagiconv
~~~~~~~~~~~~~~~

Asagiconv (Located
`here <https://github.com/SeisSol/SeisSol/tree/master/preprocessing/science/asagiconv>`__)
allows querying data, vizualising and exporting to NetCDF data from the
3D Velocity Model for Southern California. For more detail, see `ASAGI
docu <http://www.seissol.org/sites/default/files/asagi.pdf>`__.


Velocity models given as structured grids
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

| Asagi expects a 1D, 2D, 3D (or higher dimensions) structured grid NetCDF files. Such files can be
  generated from an ASCII file using the command:
  ``ncgen -b asagi_example.txt``
| Here is a typical example for the ASCII file:

::

   netcdf asagi_example {
   types:
     compound material {
       float rho ;
       float mu ;
       float lambda ;
     }; // material
   dimensions:
       x = 3 ; // Number of points in x-direction
       y = 2 ; // Number of points in y-direction
       z = 1 ; // Number of points in z-direction
   variables:
       float x(x) ;
       float y(y) ;
       float z(z);
       material data(z, y, x) ;
   data:
     x = 2, 2.5, 3 ; // Grid points in x-direction (must have the same spacing)
     y = -1, 0 ; // Grid points in y-direction (must have the same spacing)
     z = 0 ; // Grid points in z-direction (must have the same spacing)

     data =
     {1, -1, 10}, // rho,mu,lambda for x0, y0, z0
     {2, -2, 11}, // rho,mu,lambda for x1, y0, z0
     {3, -3, 12}, // rho,mu,lambda for x2, y0, z0
     {4, -4, 13}, // rho,mu,lambda for x0, y1, z0
     {5, -5, 14}, // rho,mu,lambda for x1, y1, z0
     {6, -6, 15} ; // rho,mu,lambda for x2, y1, z0
   }


SeisSol parameter file
----------------------


A simple example file setting the elastic properties using EASI can be
found
`here <https://github.com/SeisSol/easi/blob/master/examples/101_asagi.yaml>`__.

Such a file would be called adding in the namelist equation:

.. code-block:: fortran

   MaterialFileName = 101_asagi.yaml

In this example, the ASAGI file describes 2D arrays.
The AffineMap is therefore needed to define the unit vectors used for indexing the 2D arrays.
Note that the variables in the affine map can have different names than x, y or z (actually it should be preferred to avoid confusion).
An AffineMap may also be used for 3D arrays, in case the coordinates variables are not aligned with the Cartesian coordinate system.


Further information
-------------------

For further information, the use of asagiconv and asagi and its
compilation, please see: `ASAGI
docu <http://www.seissol.org/sites/default/files/asagi.pdf>`__.

Known issues
------------

There is a bug when using ASAGI with MPI. A workaround is described in https://github.com/SeisSol/SeisSol/issues/46.