UNDER CONSTRUCTION

1 Introduction

1.1 Purpose & Audience

This document serves two primary purposes:

• To provide instruction that allows a user to begin to use the Seakon model with the expection of only basic shell programming knowledge
• To serve as a repository of knowledge about different experimental configurations of the Seakon model such that they can be readily reproduced, modified, or extended as needed

This document does not describe the underlying numerics or physics of the model. Such information is largely documented in Latychev et al. (2005) and the source-code of the model itself.

1.2 Document Structure

The userguide will be structured to parallel the Seakon model itself with the following sections:

1. Prerequisites
2. Preprocessing & Data prep
3. Model Execution
4. Postprocessing

2 Prerequsites

One of the advantages of the Seakon model is the sparse library requirements. To compile the model on a given compute platform only a Fortran compiler (e.g. GCC’s gfortran or Intel’s ifort) and Message-Passing-Interface (MPI) library (e.g. OpenMPI, MPICH) is needed. However, to prepare model inputs as well as process and visualize model output there are several utilities which will greatly ease the process. Many of these will already be installed on a typical Linux based HPC platform (e.g. Compute Canada).

• NetCDF - a library for storing and interfacing with geospatial datasets [https://www.unidata.ucar.edu/software/netcdf]
• Generic Mapping Tools (GMT) - Can produce spatial plots, resample gridded data, and produce gridded data files from plaintext output lacking grid-information [https://www.generic-mapping-tools.org]
• NetCDF Operators (NCO) - Can be used for low-level and high-level operations on NetCDF files (i.e. metadata creation and modification, as well as basic mathematical and statistical operations) [http://nco.sourceforge.net/]
• Climate Data Operators (CDO) - Useful for various regridding implementations and many mathematical and statistical operations [https://code.mpimet.mpg.de/projects/cdo]
• Panoply - A Java based interactive visualizing tool for NetCDF and other gridded input data formats [https://www.giss.nasa.gov/tools/panoply/]
• ncview - A very simple NetCDF visualizing tool, suitable for running through X-forwarding over SSH [http://meteora.ucsd.edu/ pierce/ncview_home_page.htm]

Since the inputs and outputs of Seakon are plain-text many operations can also be done with using shell scripting in lieu of a more complicated programming language. While example scripts will make use of many of these tools, the exact operation of each may not be immediately obvious to the novice. As such, a non-exhaustive list of tools of which a typical user should have basic knowledge is provided below. For more information on each of these tools the reader can consult the man-pages (available on many *nix systems via man grep, and in the case of some info grep) as well as text such as the "Unix Power Tools" series of texts published by O’Reilly.

• awk - at its simplest this tool operates on data in columns but it can be used as an entire programming languge if so desired
• grep - line-by-line string matching
• sed - line-by-line string operations (search, replace, modify, etc.)
• cut - simple column extraction
• sort - sorts data in a variety of ways, multiple sorting keys can be specified and as such lends itself well to dealing with Lat-Long data
• uniq - merges unique lines
• pipes (|) - not explictly a ‘tool’ in the idea of a binary to download and execute per-se but rather a means of chaining together other commands. A pipe takes standard-out from one command and provides it to standard in of another command. A simple example is to use sort in combination with uniq to remove duplicate lines from a file containing a 1D array of data: sort inputFile.dat|uniq. Pipes can be chained together to develop complex work-flows without the use of intermediate files.
• bash expansions - like pipes this is not specifically an executable but intrinsic to the shell. The shell scripts documented in this text use the Bash shell (unless otherwise noted) and may make use of some Bash specific expansions and wildcards. Three of the most common in use are ‘?’, ‘[N-M]’, and ‘*’. ‘?’ replaces any single character in place and as such a command such as ls solution_?? will match against any file with the prefix ‘solution_’ and any two other characters (e.g. will match solution_01 through to solution_53 as in the ICE5G dataset). ‘[N-M]’ will match any number between N and M, for example ls solution_[4-5]? will only match solution files from 40-59. [N-M] can also be used with letters (e.g. [a-z], [A-Z], or even [a-Z]). Finally, ‘*’ will match any number of any characters, which makes it both very powerful and very dangerous and should be used sparingly. Before using ‘*’ in any command which can modify data I suggest running it through ls to see which files it will operate on.

3 Preprocessing & Data prep

Here we summarise the order of operations for producing the required input files for a single experiment. The setup of the Seakon model can operate either interactively, via the Seakon Director, or non-interactively via the use of setup files or set_io_interact files. New users should familiarize themselves with the options available to them via the Seakon Director software, however the interactive approach for configuring experiments makes ensemble scale work problematic. The non-interative approach, I advocate for using the set_io_interact method as is comparable to using Fortran namelists, but with the additional step of re-compiling each utility. Setup files can also be used and output by the Seakon director, however this is an additional parsing step which increases the opportunity for bugs.

Our testcase will use the following parameters:

• Elastic lithosphere thickness :120km lithosphere
• Upper mantle viscosity : 3×10²¹Pa s
• Lower mantle viscosity : 90×10²¹Pa s
• Ice sheet reconstruction : ICE5G
• Shear Velocity Model (for lateral viscosity) : S40RTS
• 48-processor cores
• Basegrid solver-grid

3.1 Overview & Program Flow

To setup and execute a single experiment from only provided inputs (e.g. loading history, topography, and grid file) the program flow shown in Fig. 1 applies.

---

---

3.2 p_sftdd

Inputs: Master grid file produced by sftdd (single grid-file to distributed grid file) and sftgen (gridfile generator). (e.g. grid48_???) Outputs: distributed grid file suitable for passing to solver and other utilities.

3.2.1 Description from Source

Finalize the construction of a distributed output grid, given a distributed input grid in the form DATA_NAMExxx produced by sftdd.f90. It must be placed in DATA_PATH (see module io_mod). A distributed output will be written to GRID_PATH in the form GRID_NAMExxx, where xxx = [000, np-1] is a 3-digit CPU number. Optionally a (theta,phi) rotation can be performed. To enable an interactive setup, uncomment "! call set_io_interact" in the main unit, located at the end and run seakon_director.f90. Alternatively, to import parameters from a setup script, uncomment this line in the main unit "! call read_io_set", then compile. The setup script must be called p_sftdd.set and placed in the same directory as the compiled executable.

3.2.2 set_io_interact Format

3.3 p_setgv

X

3.4 p_map_stopo

X

3.5 p_map_sload

X

3.6 p_mp3d

X

4 Model Exection

5 Postprocessing

5.1 p_exsurf

X

---

---

6 Conclusions

• PLACEHOLDER

References

Appendix A: Reference Scripts