easi
easi is a library for the Easy Initialization of model parameters in three (or less) dimensional domains. easi offers the possibility to parameterize the simulation without having to recompile SeisSol. Thanks to easi, all user can run their simulations with the same executable (no more hardcoded fortran initialization routines).
Writing easi models
easi uses configuration files written in Yet Another Markup Language (YAML). For example, a simple model with constant material parameters could be described in the following way:
!ConstantMap
map:
lambda: 3.2044e+010
mu: 3.2038e+010
rho: 2670.
Qp: 69.3
Qs: 155.9
Complex models may be easily built, too. For example, builtin with easi come linear or polynomial models (e.g. to build depthdependent models). Furthermore, one may sample parameters from large two or threedimensional uniform grids. Lastly, code may be supplied written in a Clike language, which is compiled at runtime.
Please refer to easi’s documentation and to easi’s examples for further details.
Invoking SeisSol
It is recommended to place easi models in the folder that also contains
the parameter file.
Within the parameterfile, add the parameter MaterialFileName
to
the equations block, e.g.
&equations
MaterialFileName = 'material.yaml'
/
When using Dynamic rupture, add the parameter ModelFileName
to
the DynamicRupture block, e.g.
&DynamicRupture
ModelFileName = 'fault.yaml'
/
Rheological model parameters
The following parameters need to be set by easi. The columms E, A, V, and P denote if the respective parameter is required when using an (isotropic) elastic, anisotropic (elastic), viscoelastic, and viscoplastic rheological model.
Parameter 
Unit 
E 
A 
V 
P 
Description 

rho 
\(\frac{kg}{m^3}\) 
✓ 
✓ 
✓ 
✓ 
Density. 
mu, lambda 
Pa 
✓ 
✓ 
✓ 
Lamé parameters. 

c11, …, c66 1 
Pa 
✓ 
stiffness tensor. 

Qp, Qs 
✓ 
Pwave and Swave quality factors. 

bulkFriction 
✓ 
Bulk friction coefficient. 

plastCo 
Pa 
✓ 
Plastic cohesion. 

s_xx, s_yy, s_zz, s_xy, s_yz, s_xz 
Pa 
✓ 
Initial stress tensor. 
 1
See Anisotropic for more details.
Fault parameters (dynamic rupture)
The following parameters need to be set by easi. The column FL denotes for which friction law the respective parameter is required. Please note that there are two ways to specify the initial stress on the fault: You may either specify a stress tensor (s_xx, s_yy, s_zz, s_xy, s_yz, s_xz), which has to be given for the same cartesian coordinate system as the mesh, or you may specify a traction vector (T_n, T_s, T_d), which has to be given in a fault local coordinate system. You must not specify both.
Parameter 
Unit 
FL 
Description 

s_xx, s_yy, s_zz, s_xy, s_yz, s_xz 
Pa 
all (excludes initial traction) 
Initial stress tensor. 
T_n, T_s, T_d 
Pa 
all (excludes initial stress) 
Initial traction in n=normal, s=strike, d=dip direction. 
cohesion 
Pa 
2, 6 
Magnitude of cohesive force. 
mu_s, mu_d 
2, 6 
Linear slip weakening: Static and dynamic friction coefficient. 

d_c 
m 
2, 6 
Linear slip weakening: Critical distance. 
forced_rupture_time 
s 
16 
Time of forced rupture. 
rs_a, rs_srW, RS_sl0 
101, 103 
Rateandstate friction parameter. 

nuc_{xx, yy, zz, xy, yz, xz} or Tnuc_{n, s, d} 
Pa 
2, 3, 4, 103 
Nucleation stress or tractions. 
Debugging easi script
test.yaml: yamlcpp: error at line 6, column 9: illegal map value
27.1: syntax error, unexpected '}', expecting ;
An example illustrating some subtleties of easi error logs
Let suppose that we try to retrieve s_zz located at (x,y,z)=(0,0,0) in group 1 from the following easi file:
[s_zz,s_yy,s_yz,s_xx,s_xz,s_xy,d_c,mu_s]: !AffineMap
matrix:
xf: [0.4054811 , 0.91410343, 0. ]
yf: [0.62424723, 0.2769057 , 0.73050574]
zf: [0.6677578 , 0.29620627, 0.68290656]
translation:
xf: 348441.377459
yf: 4760209.93637
zf: 0.0
components: !ASAGI
file: norciax_210fault_nncia.nc
parameters: [s_zz,s_yy,s_yz,s_xx,s_xz,s_xy,d_c,mu_s]
var: data
interpolation: nearest
and get the following error log:
terminate called after throwing an instance of 'std::runtime_error'
what(): fault2.yaml@2: Could not find model for point [ 348441 4.76021e+06 0 ] in group 1.
How to interpret this error log? The component at Line 2 is throwing the error (the AffineMap). The AffineMap component is complaining that its output point is not accepted by any of its child components. In this case, the point is outside the bounds of the ASAGI file.
Note that in the slightly different example below, without the AffineMap, easi will not verify that the point is outside the bounds of ASAGI file:
[s_zz,s_yy,s_yz,s_xx,s_xz,s_xy,d_c,mu_s]: !ASAGI
file: norciax_210fault_nncia.nc
parameters: [s_zz,s_yy,s_yz,s_xx,s_xz,s_xy,d_c,mu_s]
var: data
interpolation: nearest
In fact, in this case, ASAGI is directly queried and easi, therefore, does no verify that the point queried in inside the bounds of the ASAGI file. If the point is out of bounds, ASAGI will pick the value of the nearest grid point and issue a warning:
Thu Jan 09 14:32:22, Warn: ASAGI: Coordinate in dimension 2 is out of range. Fixing.