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
(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¶
Change to the new directory
sicopolis
and execute the bash scriptcopy_templates.sh
:./copy_templates.sh
It copies several scripts from
runs/templates
toruns
and the run-specs header files fromruns/headers/templates
toruns/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.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 directoryruns
, 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"
/"false"
, which works for all test simulations included in the SICOPOLIS package.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). For high-resolution simulations (e.g., Greenland/5 km or Antarctica/8 km),LARGE_DATA_FLAG
must be set to"true"
.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 directoryruns
, 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
.License file.
- Directory
runs
Configuration scripts
sico_configs.sh
,sico_environment.sh
.Shell script (bash)
sico.sh
for running a single simulation.Shell scripts (bash)
multi_sico_1.sh
andmulti_sico_2.sh
for running multiple simulations by repeated calls ofsico.sh
.- Subdirectory
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.
- Subdirectory
- 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/asf
,nhem
,scand
,tibet
,nmars
andsmars
for Austfonna, the northern hemisphere, Scandinavia, Tibet 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
asf
,nhem
,scand
,tibet
,nmars
andsmars
for Austfonna, the northern hemisphere, Scandinavia, Tibet 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
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. [44]), named repo_emtp2sge25_expA
, use the script sico.sh
as follows:
(./sico.sh -m repo_emtp2sge25_expA) >out_001.dat 2>&1
(from directory runs
, 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) >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) >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.