2. Getting started
2.1. Requirements
Unix-like system (e.g., Linux).
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
You should then have a new directory
sicopolis
that contains the entire program package.Note
Cloning with SSH instead of HTTPS is also available. See the above GitLab front page link for details.
- 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
Change to the main directory
sicopolis
and execute the bash scriptcopy_templates.sh
:./copy_templates.sh
It copies several scripts from
templates
to.
(the main directory), fromtools/templates
totools
, and the run-specs header files fromheaders/templates
toheaders
. This allows modifying the scripts and headers suitably if needed, while the original files are always stored in the respective templates subdirectories for reference.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.
Locate the file
sico_configs.sh
in the main directory, and open it with a text editor.Set the flags
LIS_FLAG
,OPENMP_FLAG
andLARGE_DATA_FLAG
according to your needs.Default is
"true"
/"true"
/"true"
.LIS_FLAG
andOPENMP_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 withLARGE_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"
, setLISHOME
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.).Locate the file
sico_environment.sh
in the main directory, open it with a text editor, and replace theSICO_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
andmulti_sico_2.sh
for running multiple simulations by repeated calls ofsico.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 modules, for any modelled domain.Subdirectories
subroutines/eismint
,subroutines/heino
,subroutines/mocho
,subroutines/n_s_mars
: special modules for EISMINT (Huybrechts et al. [42], Payne et al. [53]), ISMIP HEINO (Calov et al. [12]), the Mocho-Choshuenco ice cap, and the north and south polar caps of Mars, respectively.Subdirectory
subroutines/tapenade
: AD-specific modules, scripts and files.Subdirectory
subroutines/xyz
: For creating new domains (by default contains only placeholder files).- Directory
sico_in
Input data files for SICOPOLIS.
Subdirectory
general
: general input files, for any modelled domain.Subdirectory
ant
: input files for the Antarctic ice sheet.Subdirectory
grl
: input files for the Greenland ice sheet.Subdirectories
nhem
,lcis
,scand
,tibet
,asf
,npi
,mocho
,eismint
,heino
,nmars
,smars
: input files for the other pre-defined domains.Subdirectory
xyz
: For creating new domains (by default empty).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 (domain, physical parameters, grid, resolution, times, …) 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.
Warning
When running SICOPOLIS on a Unix or Linux system, it is important to save the run-specs headers always with Unix-style newlines (LF). If they have Windows-style newlines (CR-LF), which may occur when editing headers on a Windows system, the processing by the bash script sico.sh
may not work properly (depending on the specified options) and produce some strange error messages.
2.6. How to run a simulation
For example, to run the EISMINT Phase 2 Simplified Geometry Experiment A (Payne et al. [53]), 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.7. 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>.site
,<run_name>_site.nc
:Time-series files (ASCII, NetCDF) that contain for selected sites (i.e., ice cores) 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>_site.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,.site,_ser.nc,_site.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.