Project

General

Profile

Tutorial: How to use iSALE

This tutorial will give you some advanced insights into proper usage of iSALE. It will provide advice on how to prepare the directory structure properly and some hints for setting up a new simulation.
As a prerequisite for this tutorial, it is strongly recommended to follow the instructions of at least one of the examples to become familiar with iSALE.

For this tutorial we assume a clean installation.
$PREFIX refers to the prefix-path defined when configuring iSALE, i.e. the directory where the examples, the binaries and documentation are installed.
$HOME refers to your home-directory.

Prepare the directory structure

In the instructions for the examples provided in this wiki, you started your simulations directly from within the examples directory (e.g., $PREFIX/shared/examples/demo2D/). For scientific studies, this is not advisable, since the examples directories will be overwritten whenever "make install" is called again (e.g., after updating the code or reconfiguring). Thus, it is recommended to create a separate directory from which to start your simulations. To clearly distinguish between examples and your own simulation setups, we highly recommend to create the new folder in a separate location.

Your setup directory will contain all the information and tools required to run your simulation, and---if properly generated---also to repeat your simulations and re-generate all your data at any time. Therefore we recommend you create this directory in a location that is secure and frequently backed up. On many systems, within your home-directory is a sensible location.

If not already done, we start by generating a folder for all of our simulations:

mkdir $HOME/isale_runs

Within this folder, we now generate a subfolder for our first project, e.g.:

mkdir $HOME/isale_runs/crater_collapse

To make things easier for ourselves, we will now copy the input files from an existing project (or example) into this folder. In this demonstration, we will simulate a Chicxulub-like impact, so we use the input-files from the "Chicxulub" example as starting point:

cd  $PREFIX/share/examples/Chicxulub
cp asteroid.inp material.inp parameters.db $HOME/isale_runs/crater_collapse

Note that it is important to copy both the input files *.inp and the parameter database parameters.db as all three files are required by iSALE.

Next, we generate copies of all required executables in our directory.

We recommended using copies of the executables rather than symbolic links (as provided in the examples). Once you update the code and perform a new "make install", the executable in the binary folder will be overwritten. At this point, all symbolic links will point to the new version of the binary (and not the one initially used for your simulation). Hence, following a code update you might not be able to exactly reproduce simulations previously run.

cd $PREFIX/bin
cp iSALE2D iSALEMat iSALEPar iSALEPlot vimod $HOME/isale_runs/crater_collapse/.

Note that as well as copying iSALE2D we have copied two additional tools to aid pre-processing (iSALEMat and iSALEPar) and two tools for post-processing (iSALEPlot and vimod).

Finally, we need to provide the equation-of-state files (e.g. *.aneos or *.tillo). Since these files are usually not changed frequently, the most sensible option is to simply create a symbolic link to the eos-directory (as done in the examples). However, if you want to edit the equation of state file the best option is to copy all required eos-files into your simulation-directory.

cp -r $PREFIX/share/eos $HOME/isale_runs/crater_collapse/.

Adjust asteroid.inp

The asteroid.inp is currently the same as in the original Chicxulub-example. It describes the impact of a granitic projectile into a three-layer target composed of a dunite mantle, a granite basement material and a sedimentary layer made of calcite. For our new simulation we will use, instead, a two-layer setup with a uniform crustal layer above a dunite mantle layer. To represent the crustal layer, we will use granite to begin with. Later in this tutorial, we will show you how to change the crustal material model to enable a granular (i.e. sand-like) rheology.

For this purpose, we now remove the information for the uppermost layer ("calcite") from asteroid.inp and change the layer position for the two lower layers according to our purposes. We will also rename the materials to be more generic; i.e., we will use "mantle_" instead of "dunite_" and "crust__" instead of "granite." Please note that we also need to reduce the number of layers to "2". The corresponding section in asteroid.inp

------------------- Target Parameters ----------------------------------
LAYNUM                layers number                 : 3
LAYPOS                layer position                : 103         : 178         : 185
LAYMAT                layer material                : dunite_     : granite     : calcite
LAYTPROF              thermal profile               : CONST       : CONST       : CONST

is therefore now changed into

------------------- Target Parameters ----------------------------------
LAYNUM                layers number                 : 2
LAYPOS                layer position                : 178         : 185
LAYMAT                layer material                : mantle_     : crust__
LAYTPROF              thermal profile               : CONST       : CONST

We will also switch the projectile material from "granite" to "mantle_" so that projectile and upper layer can be distinguished. To speed up the calculation a bit, we also reduce the impact velocity to 10 km/s (this reduces the amount of vapourisation).

------------------- Projectile ("Object") Parameters --------------------
OBJVEL      object velocity               : -1.D4
OBJMAT      object material               : mantle_

Generate or modify material input file with iSALEMat

Now, let's look into the corresponding material.inp. This file currently consists of the three materials required for the original setup:

#ISMAT ! iSale material input file identification string
-----------------------------------------------------------------------------
MATNAME    Material name          : granite      : dunite_      : calcite
EOSNAME    EOS name               : granit2      : dunite_      : calcite
EOSTYPE    EOS type               : aneos        : aneos        : aneos
STRMOD     Strength model         : ROCK         : ROCK         : ROCK
DAMMOD     Damage model           : IVANOV       : IVANOV       : IVANOV
ACFL       Acoustic fluidisation  : BLOCK        : BLOCK        : BLOCK
PORMOD     Porosity model         : NONE         : NONE         : NONE
THSOFT     Thermal softening      : OHNAKA       : OHNAKA       : OHNAKA
LDWEAK     Low density weakening  : POLY         : POLY         : POLY
----------------------------------------------------------------------------
POIS       pois                   : 3.0000D-01   : 2.5000D-01   : 3.0000D-01
----------------------------------------------------------------------------
TMELT0     tmelt0                 : 1.6730D+03   : 1.3730D+03   : 1.5000D+03
CHEAT      C_heat                 : 1.0000D+03   : 1.0000D+03   : 1.0000D+03
TFRAC      tfrac                  : 1.2000D+00   : 1.2000D+00   : 1.2000D+00
ASIMON     a_simon                : 6.0000D+09   : 1.5200D+09   : 6.0000D+09
CSIMON     c_simon                : 3.0000D+00   : 4.0500D+00   : 3.0000D+00
----------------------------------------------------------------------------
YDAM0      ydam0 (ycoh)           : 1.0000D+04   : 1.0000D+04   : 1.0000D+04
FRICDAM    fricdam                : 6.0000D-01   : 6.0000D-01   : 4.0000D-01
YLIMDAM    ylimdam                : 2.5000D+09   : 3.5000D+09   : 5.0000D+08
----------------------------------------------------------------------------
YINT0      yint0                  : 1.0000D+07   : 1.0000D+07   : 5.0000D+06
FRICINT    fricint                : 2.0000D+00   : 1.2000D+00   : 1.0000D+00
YLIMINT    ylimint                : 2.5000D+09   : 3.5000D+09   : 5.0000D+08
----------------------------------------------------------------------------
IVANOV_A   Damage parameter       : 1.0000D-04   : 1.0000D-04   : 1.0000D-04
IVANOV_B   Damage parameter       : 1.0000D-11   : 1.0000D-11   : 1.0000D-11
IVANOV_C   Damage parameter       : 3.0000D+08   : 3.0000D+08   : 3.0000D+08
----------------------------------------------------------------------------
GAMETA     gam_eta                : 8.0000D-03   : 8.0000D-02   : 0.0000D-03
GAMBETA    gam_beta               : 1.1500D+02   : 0.5000D+02   : 0.0000D+02
----------------------------------------------------------------------------
<<END ! used to identify the end of this file

For our simulation, we want to change the strength model for the crust material from an intact-rock strength model appropriate for granite to a granular strength model, appropriate for a weaker crustal material, such as sand or regolith. For this reason we are going to use a simple Drucker-Prager strength model and disable damage calculations for this material (the entire layer is assumed to be completely damaged, as realistic for sand-like materials). We will neglect acoustic fluidization for this layer. We will also switch the algorithm for damage-calculation for the mantle layer from the IVANOV-approach to the COLLINS one. Note that despite modifying the strength models for the crust and mantle, we will leave the equations of state the same for both layers: ANEOS-derived equation of state tables for granite and dunite (with solid-solid phase transition but no melt transition), for the crust and mantle, respectively.

The first step to perform these changes is to change the header of the material.inp to the following:

#ISMAT ! iSale material input file identification string
-----------------------------------------------------------------------------
MATNAME    Material name          : crust__      : mantle_      : calcite
EOSNAME    EOS name               : granit2      : dunite_      : calcite
EOSTYPE    EOS type               : aneos        : aneos        : aneos
STRMOD     Strength model         : DRPR         : ROCK         : ROCK
DAMMOD     Damage model           : NONE         : COLLINS      : IVANOV
ACFL       Acoustic fluidisation  : NONE         : BLOCK        : BLOCK
PORMOD     Porosity model         : NONE         : NONE         : NONE
THSOFT     Thermal softening      : OHNAKA       : OHNAKA       : OHNAKA
LDWEAK     Low density weakening  : POLY         : POLY         : POLY

Note that we have left the last column entries untouched as these will be automatically removed later (see below).

A key feature of iSALE is that it offers a large number of possible options to model the material rheology. Unfortunately, this has the disadvantage of requiring a large number of different input parameters. Each material model requires its own set of input parameters (which may or may not overlap with other similar models). And not all material models can be combined with each other. Without in-depth understanding of these models, it is easy for a User to enter invalid input data.

Which (material) parameters are required for my current simulation?
Did I miss some parameters?
Did I set proper combinations of material models?

To help answer these and other questions, a specific tool, iSALEMat, has been designed. This tool processes the asteroid.inp and material.inp and assists the User in modifying or generating material.inp.

For example, we may now simply call iSALEMat and see what happens

./iSALEMat

iSALEMat has automatically modified material.inp. Let's look inside the modified version:

#ISMAT ! iSale material input file identification string
--------------------------------------------------------------------------------
MATNAME    Material name                            : mantle_      : crust__
EOSNAME    EOS name                                 : dunite_      : granit2
EOSTYPE    EOS type                                 : aneos        : aneos
STRMOD     Strength model                           : ROCK         : DRPR
DAMMOD     Damage model                             : COLLINS      : NONE
ACFL       Acoustic fluidisation                    : BLOCK        : NONE
PORMOD     Porosity model                           : NONE         : NONE
THSOFT     Thermal softening                        : OHNAKA       : OHNAKA
LDWEAK     Low density weakening                    : POLY         : POLY
--------------------------------------------------------------------------------
---------general parameters ----------------------------------------------------
POIS       pois                                     : 2.5D-01      : 3.D-01
---------thermal softening -----------------------------------------------------
TFRAC      tfrac                                    : 1.2D+00      : 1.2D+00
---------thermal parameters ----------------------------------------------------
TMELT0     tmelt0                                   : 1.373D+03    : 1.673D+03
CHEAT      C_heat                                   : 1.D+03       : 1.D+03
ASIMON     a_simon                                  : 1.52D+09     : 6.D+09
CSIMON     c_simon                                  : 4.05D+00     : 3.D+00
---------shear strength of intact material -------------------------------------
YINT0      yint0                                    : 1.D+07       : xxxxxxxxxxxx
FRICINT    fricint                                  : 1.2D+00      : xxxxxxxxxxxx
YLIMINT    ylimint                                  : 3.5D+09      : xxxxxxxxxxxx
---------shear strength of damaged material ------------------------------------
YDAM0      ydam0 (ycoh)                             : 1.D+04       : 1.D+04
FRICDAM    fricdam                                  : 6.D-01       : 6.D-01
YLIMDAM    ylimdam                                  : 3.5D+09      : 2.5D+09
---------shear damage (Collins) ------------------------------------------------
BDTPRES    bdt_pres                                 : -1.D+00      : xxxxxxxxxxxx
BPTPRES    bpt_pres                                 : -1.D+00      : xxxxxxxxxxxx
---------acoustic fluidization (block model) -----------------------------------
GAMETA     gam_eta                                  : 8.D-02       : xxxxxxxxxxxx
GAMBETA    gam_beta                                 : 5.D+01       : xxxxxxxxxxxx
<<END ! used to identify the end of this file

As you can see, iSALEMat automatically removed the unused material "calcite" from the file. This is because only two separate materials (crust__ and mantle_ were specified in asteroid.inp. To further increase the readability of the file, parameters not required for the current material are now automatically marked with 'xxxxx'. Unnecessary lines (i.e. parameters not required by any of the defined materials) are removed from the file, too. All other information has been adopted from the previous material.inp file.

We can now clearly see that it requires much less material properties for our granular material than for the original intact (ROCK) rheology of granite.

In the next step, we might want to adjust the parameters used here. To model sand-like behaviour, we may want to neglect cohesion for the crust__ material so we select

YDAM0      ydam0 (ycoh)                             : 0.D0         : 1.D+04       : xxxxxxxxxxxx

Finally, our material.inp is

#ISMAT ! iSale material input file identification string
--------------------------------------------------------------------------------
MATNAME    Material name                            : mantle_      : crust__
EOSNAME    EOS name                                 : dunite_      : granit2
EOSTYPE    EOS type                                 : aneos        : aneos
STRMOD     Strength model                           : ROCK         : DRPR
DAMMOD     Damage model                             : COLLINS      : NONE
ACFL       Acoustic fluidisation                    : BLOCK        : NONE
PORMOD     Porosity model                           : NONE         : NONE
THSOFT     Thermal softening                        : OHNAKA       : OHNAKA
LDWEAK     Low density weakening                    : POLY         : POLY
--------------------------------------------------------------------------------
---------general parameters ----------------------------------------------------
POIS       pois                                     : 2.5D-01      : 3.D-01
---------thermal softening -----------------------------------------------------
TFRAC      tfrac                                    : 1.2D+00      : 1.2D+00
---------thermal parameters ----------------------------------------------------
TMELT0     tmelt0                                   : 1.373D+03    : 1.673D+03
CHEAT      C_heat                                   : 1.D+03       : 1.D+03
ASIMON     a_simon                                  : 1.52D+09     : 6.D+09
CSIMON     c_simon                                  : 4.05D+00     : 3.D+00
---------shear strength of intact material -------------------------------------
YINT0      yint0                                    : 1.D+07       : xxxxxxxxxxxx
FRICINT    fricint                                  : 1.2D+00      : xxxxxxxxxxxx
YLIMINT    ylimint                                  : 3.5D+09      : xxxxxxxxxxxx
---------shear strength of damaged material ------------------------------------
YDAM0      ydam0 (ycoh)                             : 1.D+04       : 0.D0
FRICDAM    fricdam                                  : 6.D-01       : 6.D-01
YLIMDAM    ylimdam                                  : 3.5D+09      : 2.5D+09
---------shear damage (Collins) ------------------------------------------------
BDTPRES    bdt_pres                                 : -1.D+00      : xxxxxxxxxxxx
BPTPRES    bpt_pres                                 : -1.D+00      : xxxxxxxxxxxx
---------acoustic fluidization (block model) -----------------------------------
GAMETA     gam_eta                                  : 8.D-02       : xxxxxxxxxxxx
GAMBETA    gam_beta                                 : 5.D+01       : xxxxxxxxxxxx
<<END ! used to identify the end of this file

As an additional exercise you might also like to activate the porosity model for the crustal layer, to give an even more sand-like material model. To do this, simply change the PORMOD header option for the crust__ layer from NONE to WUNNEMA, and then re-run iSALEMat. When you reopen the material.inp file the required porosity model parameters will have been added (with default values) to the input file, which can be modified appropriately for the desired material.

At this stage, we are - in principle - ready to start our simulation...

Changing the resolution - resizing the mesh automatically with iSALEPar

ATTENTION: This section describes a feature which is currently under development. It is NOT contained in the current stable release of iSALE (iSALE-Chicxulub). iSALE-users working with the stable release are asked to skip this section or, as we strongly recommend, perform the scaling manually to gain understanding of the mesh setup process. iSALE-developers working with the developer version can use the automatic scaling option described in the tutorial below. But please be aware that this feature might not work for very special setups, such as collisions of spheres, or landslide/slope geometries.
Please use it with care!

The current simulation setup is based upon a resolution of 18 CPPR (CPPR=Cells per projectile radius). To reduce the calculation time for the benefit of this tutorial, we will show how to downsample the input-file to half of the resolution (9 CPPR). To do this manually we would need to adjust

  • the physical size of the cell
  • the number of cells in the high-resolution zone
  • the number of cells in the extension zone (you need to compute how many extension cells you need to obtain the same dimension of the extension grid)
  • the position of every layer
  • ... and sometimes even more, such as placement of tracers, ...

Fortunately, an additional pre-processing tool called 'iSALEPar' can be used to perform these modifications to the input file automagically. For this purpose, we call it with the following flags:

./iSALEPar --scale 9 -i asteroid.inp

Now, a new file called 'asteroid.inp.scaled' is generated. Please cross-check whether the changes are correct for your desired setup. For simplicity, we now replace the original file by this one (mv asteroid.inp.scaled asteroid.inp).

Comparison of original setup and setup downscaled to half the resolution
Figure above: Comparison of the original setup (left, 18 CPPR) and the downscaled setup (right, 9 CPPR). Please note: Since the layer position (and hence layer thickness) is defined in an integer number of cells, down- or upscaling might result in minor differences of the layer thickness.

To reduce the calculation time further for this tutorial setup, we will reduce the number of extended cells and at the same time increase the GRIDEXT-value, which defines the ratio of adjacent cell sizes within the extension zone, so that the physical size of the extension zone remains approximately the same. We will use a value of 1.1 (10% increase in cell size; GRIDEXT=1.10D0) for now and reduce the extended cells on the right and bottom to 20. Thus, we change the mesh geometry section of asteroid.inp from

------------------- Mesh Geometry Parameters ---------------------------
GRIDH       horizontal cells              : 0           : 125         : 47
GRIDV       vertical cells                : 47          : 100         : 13
GRIDEXT     ext. factor                   : 1.05d0

to the following:

------------------- Mesh Geometry Parameters ---------------------------
GRIDH       horizontal cells              : 0           : 125         : 20
GRIDV       vertical cells                : 20          : 100         : 13
GRIDEXT     ext. factor                   : 1.10d0

Since we removed 27 (extended-)cells from the bottom of the grid, we need to adjust the positions of the layers. These are defined in cell numbers counted from the bottom of the grid. To assure that the layer position is at the same position within the high-resolution zone, we therefore need to subtract 27 cells from every layer position value. Here we use a value of 80 for the upper layer. We slightly increase the thickness of the upper layer by reducing the position of the lower layer (mantle_) to 70:

------------------- Target Parameters ----------------------------------
LAYNUM      layers number                 : 2
LAYPOS      layer position                : 70          : 80
LAYMAT      layer material                : mantle_     : crust__

Finally, we want to adjust the model run-time and the time interval for writing the timesteps:

TEND        end time                      : 2.D2
DTSAVE      save interval                 : 2.D0

This way, we will obtain a datafile containing 100 (=200/2) timesteps, which will give an output-data file of manageable size.

Check setup with iSALEPar

Now we are ready to start our simulation:

./iSALE2D &

Unfortunately, the simulation does not start. iSALE exits with an error message. The screen output might look like this:

  +++++++++++++++++++++++++++++++++++++++++++++++ 
  +++                  iSALE                  +++ 
  +++    by Kai Wuennemann, Gareth Collins    +++ 
  +++          and Dirk Elbeshausen           +++ 
  +++                                         +++ 
  +++  based on SALEB  by Ivanov              +++ 
  +++           SALES  by Melosh              +++ 
  +++           SALE   by Amsden et al.       +++ 
  +++                                         +++ 
  +++++++++++++++++++++++++++++++++++++++++++++++ 

Opening parameter input-file........................................asteroid.inp
Opening material input-file.........................................material.inp
Your input file is up to date!..............................No changes required!
Checking input-file version...................................................OK
Checking non-optional parameters; errors....................................none
Checking list of valid values; errors.......................................none
Checking physical range; errors.............................................none
------ TOTAL NUMBER OF ERRORS OCCURED.......................................none
--------------------------------------------------------------------------------
INVALID VALUE FOR PARAMETER..............................................GRIDEXT
 ... value is.......................................................1.100000E+00

################################################################################
Parameter information for GRIDEXT
Meaning.................................................grid extension parameter
Parameter type............................................................real*8
Behavior for iSALE-2D...........................................................
  Allowed range............................................ [ 1.D0 : +infinite ]
  Recommended range......................................... [ 1.02D0 : 1.08D0 ]
  Optional parameter.........................................................yes
  Default value...........................................................1.04D0
Behavior for iSALE-3D...........................................................
  Allowed range............................................ [ 1.D0 : +infinite ]
  Recommended range......................................... [ 1.02D0 : 1.08D0 ]
  Optional parameter.........................................................yes
  Default value...........................................................1.04D0
Corresponding section.......................................................MESH
################################################################################
--------------------------------------------------------------------------------
Checking recommended range; warnings...........................................1
------ TOTAL NUMBER OF WARNINGS OCCURED........................................1
 ... warnings occured. Check input-parameter(s).
 ... warnings occured. Check input-parameter(s).
 ... warnings occured. Check input-parameter(s).
 Please examine error file for details about error.

So what happened here?

All input parameters required for iSALE are contained in a specific database, together with meta-information, such as data-type (e.g. integer, floating point, or string), allowed values or valid ranges for values. The tool iSALEPar that we already used above is able to access this database and process the corresponding information. Before starting the actual simulation, iSALE calls this tool to perform some sanity checks.

When looking carefully at the message of iSALE, we realize that we provided an 'invalid value' for the extension parameter ("GRIDEXT"). As we can see, the value we used (1.1) is within the allowed range, but exceeds a so-called "recommended range" (1.02 ... 1.08). Where specified, the "allowed range" of an iSALE input parameter is the range of physically sensible values; values outside this range are not valid iSALE input parameters and cannot be used. In addition, some iSALE input parameters also have a different range of recommended values defined. These values are a subset of the allowed values---i.e., they are within the physically sensible range---that are also known (with reasonable confidence) to give good results. This range is used to ensure that inexperienced Users do not use parameter values which might lead to unstable or unrealistic iSALE simulations.

In contrast to a violation of the allowed range, the warnings produced when exceeding the recommended range can be ignored (with caution!).

Note: There is a good reason for defining a recommended range! Do not ignore these warnings unless you know exactly what you do!

In our case, we used an extremely large extension value to reduce the number of cells and increase the calculation speed. This is not recommended for scientific calculations, since it might result in numerical artefacts. For the purpose of this tutorial, however, we require a simulation that is finished after a couple of minutes. Thus, here we know what we do and we want to ignore this warning. Therefore, we call iSALE with the '--ignore' flag:

./iSALE2D --ignore &

Now iSALE ignores the warnings and is forced to start the simulation.

While the simulation is running in the background, you might want to take a closer look to iSALEPar and it's ability to work with the parameter database. Click here for a description of its usage and functionality.

Further tips

  • You can also perform the parameter checks before calling iSALE. Use 'iSALEPar -i asteroid.inp for this purpose. The advantage of doing so, is that iSALEPar provides you also with some (rough) estimates of the required memory. In particularly if you are starting a high-resolution simulation you should perform this additional step to avoid starting simulations that do not fit in the memory of your computer.
  • You can also use iSALEPar to access extensive information to a specific parameter. Use 'iSALEPar --info ABBREV' for this purpose, where ABBREV is the parameter abbreviation, i.e. the entry in the first column of asteroid.inp or material.inp (e.g. iSALEPar --info GRIDEXT). See here for more information.
  • You can modify any parameter also from command-line when starting iSALE. Call iSALE with e.g. 'iSALE2D --GRIDEXT 1.08D0' to change the extension value to 1.08. The original asteroid.inp in your simulation directory keeps untouched, whereas the copy provided in your data-directory will be updated with your command-line information. In combination with the '-f MODELNAME flag (same as iSALE2D --MODEL MODELNAME) this functionality is very helpful if a large and systematic parameter study is intended.

compare_original_downscaled.png View - Comparison of original setup and setup downscaled to half the resolution (2.92 KB) Dirk Elbeshausen, 07/16/2013 03:49 PM