2. Getting started

2.1. Requirements

Unix-like system (e.g., Linux).

Fortran compiler.
So far, the GNU GCC (gfortran) and Intel Fortran (ifort) compilers are supported. If you wish to use a different compiler, please contact info@sicopolis.net.

SICOPOLIS writes output in NetCDF format (plus some ASCII). An installation of NetCDF version 3.6.x or newer is therefore required. For installation tips, see Dependencies/NetCDF.

For the shallow-shelf/shelfy-stream solver, the Library of Iterative Solvers for Linear Systems (Lis, version 1.4.43 or newer) is required. For installation tips, see Dependencies/Lis.

2.2. Download

Clone the Git repository (recommended)

The Git repository of SICOPOLIS is kindly hosted by the GitLab instance of the Alfred Wegener Institute for Polar and Marine Research (AWI) in Bremerhaven, Germany. Front page: https://gitlab.awi.de/sicopolis/sicopolis/.

Cloning the latest revision on the main branch:

git clone https://gitlab.awi.de/sicopolis/sicopolis.git

(Cloning with SSH instead of HTTPS is also available. See the above GitLab front page link for details.)

You should then have a new directory sicopolis that contains the entire program package.

Download an archive

Go to https://gitlab.awi.de/sicopolis/sicopolis/-/tree/main, click on the download symbol and choose the desired format (zip, tar.gz, tar.bz2, tar).

Tagged versions of SICOPOLIS are also available from Zenodo.

2.3. Initial configuration

  1. Change to the main directory sicopolis and execute the bash script copy_templates.sh:

    ./copy_templates.sh

    It copies several scripts from templates to . (the main directory), from tools/templates to tools, and the run-specs header files from headers/templates to headers. This allows modifying the scripts and headers suitably if needed, while the original files are always stored in the respective templates subdirectories for reference.

  2. Execute the bash script get_input_files.sh:

    ./get_input_files.sh

It downloads the input data files for the several model domains (Antarctica, Greenland, etc.) These files are stored on a server (Zenodo archive) and needed for various inputs such as topography, precipitation, geothermal heat flux, etc. The script can be configured before execution if the input files are only needed for selected domains (default is downloading everything). To do so, open it with a text editor and change the flag variables according to the instructions in the script.

  1. Locate the file sico_configs.sh in the main directory, and open it with a text editor.

    Set the flags LIS_FLAG, OPENMP_FLAG and LARGE_DATA_FLAG according to your needs.

    Default is "true"/"true"/"true". LIS_FLAG and OPENMP_FLAG can be set to "false" for simulations with pure shallow-ice dynamics. However, "true" is required for simulations with shallow-shelf dynamics (for floating ice) or hybrid shallow-ice–shelfy-stream dynamics (for grounded ice). The test simulations included in the repository all work with LARGE_DATA_FLAG set to "false". However, for higher-resolution simulations (e.g., Greenland/5 km or Antarctica/8 km), "true" is required.

    Set NETCDFHOME to the correct path of your NetCDF installation.

    If LIS_FLAG="true", set LISHOME to the correct path of your Lis installation.

    Depending on your system, some additional settings might have to be added in sico_configs.sh (module load commands for dynamic loading etc.).

  2. Locate the file sico_environment.sh in the main directory, open it with a text editor, and replace the SICO_INSTITUTION="Default" entry by the name of your institution (max. 256 characters).

2.4. Directory structure

Main directory

Initialization scripts copy_templates.sh, get_input_files.sh.

Configuration scripts sico_configs.sh, sico_environment.sh.

Shell script sico.sh for running a single simulation.

Shell scripts multi_sico_1.sh and multi_sico_2.sh for running multiple simulations by repeated calls of sico.sh.

README and LICENSE files.

Directory headers

Run-specs header files sico_specs_<run_name>.h (see below) for the simulations to be carried out with SICOPOLIS.

By default, it contains a number of test simulations.

Directory src

Main program file sicopolis.F90.

Subdirectory subroutines/general: general subroutines, for any modelled domain.

Subdirectory subroutines/ant: subroutines specific for the Antarctic ice sheet.

Subdirectory subroutines/grl: subroutines specific for the Greenland ice sheet.

Subdirectory subroutines/eismint: subroutines specific for the EISMINT simplified geometry experiments.

Accordingly subdirectories subroutines/nhem, nmars and smars for the northern hemisphere, and the north and south polar caps of Mars, respectively.

Subdirectory subroutines/tapenade: AD-specific subroutines and files.

Subdirectory subroutines/xyz: For creating new domains.

Directory sico_in

Input data files for SICOPOLIS.

Subdirectory general: general input files, for any modelled domain.

Subdirectory ant: input files specific for the Antarctic ice sheet.

Subdirectory grl: input files specific for the Greenland ice sheet.

Subdirectory eismint: input files specific for the EISMINT simplified geometry experiments.

Accordingly subdirectories nhem, nmars and smars for the northern hemisphere, and the north and south polar caps of Mars, respectively.

Subdirectory xyz: For creating new domains.

Note

These subdirectories also contain README files that describe the input data and provide the corresponding references.

Directory sico_out

Directory into which output files of SICOPOLIS simulations are written by default.

Directory docs

Documentation for SICOPOLIS.

Directory tmp

Empty directory, contents ignored by Git.

Directory tools

Some useful tools and a shell script (tools.sh) to execute them (see “Plotting and tools”).

Directory test_ad

AD-specific utilities and CI testing framework.

2.5. Run-specs header files

Each simulation (run) must be specified by a run-specs header file (or “header” for short). If the name of the simulation is supposed to be <run_name>, then the name of the header must be sico_specs_<run_name>.h. SICOPOLIS actually extracts the name of the simulation from the name of the header according to this pattern.

A header consists of a pretty large number of preprocessor directives of the form

#define PARAMETER value

These allow specifying many aspects of a simulation and are documented in the headers themselves. See also the “Modelling choices” section.

For a number of test simulations, the run-specs header files are contained in the SICOPOLIS repository. Further examples can be found in the several paper-accompanying datasets on Zenodo.

2.6. Physical-parameter files

In these files, a number of physical parameters (densities, acceleration due to gravity, heat conductivity, specific heat, latent heat, etc.) are defined. SICOPOLIS expects them in the respective directory for the input files (sico_in/ant for Antarctica, sico_in/grl for Greenland, etc.) If the name of the file is phys_para_xxx.dat, it must be specified in the run-specs header file as

#define PHYS_PARA_FILE 'phys_para_xxx.dat'

The physical-parameter files can be provided in either ASCII or NetCDF format. The file type is recognized automatically by the extension (*.nc for NetCDF, otherwise ASCII is assumed).

2.7. How to run a simulation

For example, to run the EISMINT Phase 2 Simplified Geometry Experiment A (Payne et al. [51]), named repo_emtp2sge25_expA, use the script sico.sh as follows:

(./sico.sh -m repo_emtp2sge25_expA) >tmp/out_001.dat 2>&1 &

(from the main directory, bash required). Accordingly for any other simulation.

To list further options, execute ./sico.sh -h.

Warning

The name out_<run_name>.dat must not be used for the redirected output of sico.sh. This name is reserved for the runtime output of SICOPOLIS itself. (Both are very useful in case of compilation or runtime errors!)

If you prefer to run all EISMINT, Antarctica and Greenland simulations consecutively, execute the script multi_sico_1.sh:

(./multi_sico_1.sh) >tmp/out_multi_100.dat 2>&1 &

To list further options, execute ./multi_sico_1.sh -h.

Alternatively, all other test simulations (Austfonna etc.) can be run with the script multi_sico_2.sh:

(./multi_sico_2.sh) >tmp/out_multi_200.dat 2>&1 &

Approximate computing times are listed in the “Test simulations” section.

2.8. Output files

Output files are written by default to the directory sico_out/<run_name>. This can be changed by executing sico.sh (or multi_sico_*.sh) with the option -d /path/to/output/directory. Four types are produced:

<run_name>.log:

ASCII file that lists the main specifications of simulation <run_name>.

<run_name>.ser, <run_name>_ser.nc:

Time-series files (ASCII, NetCDF) that contain scalar variables:

  • Time, t

  • Surface temperature anomaly, D_Ts, or glacial index, glac_ind (forcing)

  • Sea level, z_sl (forcing)

  • Total ice volume, V

  • Volume of grounded ice, V_g

  • Volume of floating ice, V_f

  • Total ice area, A

  • Area of grounded ice, A_g

  • Area of floating ice, A_f

  • Ice volume above flotation in sea level equivalent, V_sle

  • Volume of temperate ice, V_t

  • Area of temperate-based grounded ice, A_t

  • Maximum ice thickness, H_max

  • Maximum thickness of temperate ice, H_t_max

  • Maximum surface elevation, zs_max

  • Maximum surface speed, vs_max

  • Maximum basal temperature (relative to pmp), Tbh_max

  • (Some more in the NetCDF file, execute ncdump -h <run_name>_ser.nc for a listing)

<run_name>.core, <run_name>_core.nc:

Time-series files (ASCII, NetCDF) that contain for selected locations xxx:

  • Time, t

  • Surface temperature anomaly, D_Ts, or glacial index, glac_ind (forcing)

  • Sea level, z_sl (forcing)

  • Thickness, H_xxx

  • Surface velocity, v_xxx

  • Basal temperature, T_xxx

  • (Some more in the NetCDF file, execute ncdump -h <run_name>_core.nc for a listing)

For the Greenland ice sheet, these data are written for seven locations:
GRIP (xxx=GR), GISP2 (xxx=G2), Dye 3 (xxx=D3), Camp Century (xxx=CC), NorthGRIP (xxx=NG), NEEM (xxx=NE), EastGRIP (xxx=EG).
For the Antarctic ice sheet, these data are written for six locations:
Vostok (xxx=Vo), Dome A (xxx=DA), Dome C (xxx=DC), Dome F (xxx=DF), Kohnen (xxx=Ko), Byrd (xxx=By).
<run_name>0001.nc, <run_name>0002.nc, …:

Complete set of fields (topography, velocity, temperature etc., written in NetCDF format) for selected time slices.

Writing of output files can be controlled by the several parameters in the “Data output” section of the run-specs headers. For example, simulation repo_emtp2sge25_expA writes scalar variables into the time-series files repo_emtp2sge25_expA{.ser,.core,_ser.nc,_core.nc} every 100 years. In addition, it produces three time-slice files repo_emtp2sge25_expA0001.nc, repo_emtp2sge25_expA0002.nc and repo_emtp2sge25_expA0003.nc, which correspond to the times \(t=5\,\mathrm{ka}\), \(50\,\mathrm{ka}\) and \(200\,\mathrm{ka}\), respectively.

Note

By default, when trying to re-run a simulation, already existing output will not be overwritten, and an error message will be produced. However, overwriting can be enforced by executing sico.sh (or multi_sico_*.sh) with the option -f.

Note

If a time-slice file of the initial state of a simulation is written, not all variables will already be defined (because SICOPOLIS has not done any proper computation yet). For instance, “diagnosed” 2D fields like the basal temparatures temp_b and temph_b (relative to pressure melting) or the thermal state mask n_cts will contain only default values. They will be filled with meaningful values after the first time step.