SAMPLER

Seismic Activity Mapping & Projection for Lethal maritime Event Reconstruction (working title)

SAMPLER is a program for rasterizing unstructured meshes output by SeisSol into a format compatible with sam(oa)².

Additionally, it offers postprocessing options, namely depth filtering via Kajiura's filter and converting horizontal displacements to vertical ones using Tanioka's method.

Installation

First, set up Julia (v1.6 or greater) on your machine. The recommended ways are:

On SuperMUC-NG: Julia on SuperMUC-NG and HPC Systems, Getting Started
On Linux and Windows, locally: Julia Downloads

Afterwards, clone the SAMPLER repository to your machine (if you read this on the machine, you have already completed this step!):

git clone https://github.com/SeisSol/SAMPLER

Note: In the following it is assumed that path/to/sampler is the installation path (the sampler folder contains this README.md file).

Then, in path/to/sampler, run:

path/to/sampler> export JULIA_NUM_THREADS=3 # or higher
path/to/sampler> julia
julia> ]
(@v1.x) pkg> activate .
(SAMPLER) pkg> instantiate
(SAMPLER) pkg> test

When all tests pass, SAMPLER is installed correctly.

Usage

Once you have installed SAMPLER and you have the SeisSol outputs in XDMF format you can run the script:

cd path/to/sampler/
export JULIA_NUM_THREADS=<num_threads>
julia --project src/main.jl <options>

Note: In Windows (PowerShell), replace export ... with:

$env:JULIA_NUM_THREADS = <num_threads>

Note: For an explanation of the available command line options, type:

julia --project src/main.jl --help

You can also have a look at the run_sampler.sh and run_kajiura.sh scripts to see how SAMPLER can be executed on the LRZ compute clusters. More help for running on the cluster can be found here.

Once you have rasterized the SeisSol output files, you can optionally use Kajiura's filter on the outputs:

julia --project scripts/kajiura.jl <in_file.nc> <out_file.nc> <timestep_end>

Note: Kajiura's Filter needs to process all timesteps prior to timestep_end.

Examples

Basic example: Rasterize 2D grids (seafloor and sea surface data is available)

julia --project src/main.jl -m 8G --water-height=2000 -o ~/sampler-output.nc ~/seissol-outputs/out-surface.xdmf

Only rasterizes the 2D surface outputs (seafloor and sea surface elevation).

Rasterize only seafloor (and optionally apply Kajiura's Filter)

julia --project src/main.jl -m 8G --water-height=2000 -o ~/sampler-output.nc --seafloor-only ~/seissol-outputs/out-surface.xdmf

Only rasterizes the 2D seafloor elevation over time. Optionally thereafter:

julia --project src/main.jl ~/sampler-output.nc ~/kajiura-output.nc 300

Applies Kajiura's Filter for 300 timesteps.

Note: You can also rasterize the SeisSol outputs fully (without --seafloor-only) and then apply Kajiura's Filter to them. But that usually does not make much sense.

Rasterize seafloor using Tanioka's method

julia --project src/main.jl -m 8G --water-height=2000 -o ~/sampler-output.nc --seafloor-only --tanioka ~/seissol-outputs/out-surface.xdmf

Applies Tanioka's method while rasterizing the seafloor. Needed if bathymetry is not flat.

Note: You can also use Tanioka's method when rasterizing more than just the seafloor outputs. It will only affect the seafloor uplift.

Rasterize fully (with 3D velocity grid)

julia --project src/main.jl -m 8G --water-height=2000 -o ~/sampler-output.nc -s 300 ~/seissol-outputs/out-surface.xdmf

Rasterizes all grids and variables needed for tsunami simulation, including the 3D velocity grid. Only rasterizes timestep 300 (for example).

Using the outputs with sam(oa)²

You need the max-bachelor branch of sam(oa)² in order to seamlessly use the output files of SAMPLER. The other versions of sam(oa)² cannot handle multiple variables in one input file yet. Refer to its README.md for mor information.

Output format

SAMPLER will always produce a regular grid in NetCDF format, with point data according to the command line parameters given. You can control which input variables get mapped to which outputs via the --seafloor-vars, --surface-vars, and --volumetric-vars arguments. The standard mapping is:

Mesh region	Mappings
Seafloor	`u3 => d`
	`b => b`*
Surface	`u3 => eta`
Volumetric	`v1 => v1`
	`v2 => v2`

* b is not a variable in SeisSol outputs but is understood by SAMPLER as being the geometry of the 2D mesh. Thus, you can use the b => ... mapping to output mesh geometry.

Additionally, x, y and time will always be output as dimensions and variables and cannot be renamed.

Example mapping:

--seafloor-vars "W,b=>bathy"

Output u3 with the same name, remap mesh geometry height to bathy.

Known Issues

The --memory-limit or -m argument imposes a soft limit on the memory used. Thus, choose about half of the memory available on your machine / cluster node.

Vizualizing the rasterized grid with Paraview

The NetCDF Reader of ParaView does not show all arrays of the rasterized file (typically only the b variable). To vizualize the other variables (e.g. d or eta), we can extract the variable to be vizualized into a new NetCDF with ncks, e.g. :

ncks -v x,y,time,eta ~/sampler-output.nc ~/sampler-output-eta.nc