# Technical details

This document specifies all the technical details.

## Getting the reference code

The code for this intercomparison project hosted on https://bitbucket.org/shmip/, in particular the code is https://bitbucket.org/shmip/hydro_intercomparison. The latter contains the reference implementations of topography and water source functions input_functions, and a list of default parameters parameters/.

If you are familiar with the version control software git, you should fork & clone this repository. If you are not, then download it from here, or learn git (here is a good tutorial).

### Contributing your model setup to the repository

You are encouraged to contribute the model setups you use to run the test to the repository https://bitbucket.org/shmip/hydro_intercomparison. You can either do this by forking and making a pull request, or by submitting a zip-file of the folder containing the setup with the test results. Please name the folder/zipfile with firstname-lastname.

## Output variables

The output variables are given in below table. It also specifies which variables are required, any others can left away if not applicable. More details on their sizes, etc. can be gathered from the NetCDF-file specification, see Output file format: NetCDF. Effective pressure $$N$$ should be given as the one which the ice "feels". There can be several distributed water layer thicknesses for multi-layer models, for instance GlaDS has two: the water sheet $$h$$, and the englacial storage layer $$hstore$$. If the model contains channels then the size of the channels should be given in $$S$$. The discharges of the sheet is given in $$q$$ and of the channels in $$Q$$.

Please provide all variables which you think are relevant for your model. This may mean that new ones need to be introduced (as well as unused ones left away). If a new variable is needed, please contact Mauro and Basile to figure out a good variable name. For example, your model may have a till layer, then the variables $$htill$$ (effective water thickness in till) and $$qtill$$ (discharge through till) would probably be good. We will add extra variables to below table as we receive results, so please check back to see whether yours have appeared.

Table 1: Table of output dimensions and variable names. Please order them in the NetCDF file as in this table. index* in the shape represent the index of the coord on which the variable is defined. This table will be updated with new variable names as needed. Before your submission, please check back to make your variables consistently named.
Variable Description
(also long_name)
Units Required Remarks shape
Dimensions
time time   yes unlimited is fine
dim spatial dimension of the model   yes
n_nodes_ch number of nodes per channel segment   no fixed to 2 (?)
index1 number of nodes   yes
index2 number of cells   no
index_ch number of channels   no

Coordinates
time time s yes   (time)
coords1 node coordinates m yes horizontal (dim, index1)
coords2 cell midpoint coordinates m no   (dim, index2)
coords_ch channel midpoint coordinates m no   (dim, index_ch)
connect_ch channel connectivity   no with respect to index1 (nb_nodes3, index_ch)

Variables
B bed elevation m yes   (index*)
H ice thickness m yes   (index*)
W domain width m 1D models only   (index*)
N effective pressure Pa yes   (time, index*)
h water sheet thicknesses m no   (time, index*)
hstore stored water effective layer thickness m no   (time, index*)
q water sheet discharge m2/s no absolute value (time, index*)
S channel cross-sectional area m2 no   (time, index_ch)
Q channel discharge m3/s no   (time, index_ch)
Ee EPL thickness m no   (time, index*)

## Output file format: NetCDF

Model output has to be provided in NetCDF files following below conventions (for easier post-processing). Files can be in either NetCDF version 3 or version 4 (classic format). We hope that we have found a one-size-fits all NetCDF layout, however, it is likely that this format will change to accommodate bugs and different model. We strongly suggest that you keep the original model output around to be able to re-save them, at least until this exercise has finished.

The file naming convention for the submitted files is the following: scenario#_1-initial+3-letter-author[_version].nc for example A2_mwer.nc or A2_mwer_2.nc (if submitting several results for a run).

You can and should check that your NetCDF output is correctly formatted by running the python SHMIPncTest.py A1.nc code which is provided in Toolbox.

netcdf sqrt_ch1_mesh4 {
dimensions:
time = 81 ; \\ can be unlimited
dim = 2 ;  \\ spatial dimensions
n_nodes_ch = 2 ; \\ how many nodes to make a channel edge.  Fixed(?) at 2
index1 = 2650 ; \\ index into coords1
index2 = 5031 ; \\ index into coords2
\\ if you got more coordinates add index3, etc, add them here
index_ch = 7680 ; \\ index into channel coordinates coords_ch
variables:
double time(time) ;
time:units = "s" ;
time:long_name = "time" ;
double coords1(dim, index1) ; \\ specify what the coordinates point to in long_name
coords1:units = "m" ;
coords1:long_name = "node coordinates" ;
double coords2(dim, index2) ;
coords2:units = "m" ;
coords2:long_name = "cell midpoint coordinates" ;
double coords_ch(dim, index_ch) ; \\ coords_ch should point to channel mid-points
coords_ch:units = "m" ;
coords_ch:long_name = "channel midpoint coordinates" ;

\\ connectivity of channels.  Needs to be wrt to index1!
double connect_ch(nodes_per_ch, index_ch) ;
connect_ch:units = "" ;
connect_ch:long_name = "channel connectivity" ;

\\ Geometry variables, if possible give them on coords1
\\ Required
double B(index1) ;
B:units = "m" ;
B:long_name = "bed elevation" ;
double H(index1) ;
H:units = "m" ;
H:long_name = "ice thickness" ;
double W(index1) ;   \\ only needed and required for 1D models
W:units = "m" ;
W:long_name = "domain width" ;
double N(time, index1) ; \\ required
N:units = "Pa" ;
N:long_name = "effective pressure" ;

\\ index1 variables
double h(time, index1) ;
h:units = "m" ;
h:long_name = "water sheet thickness" ;
double hstore(time, index1) ;
hstore:units = "m" ;
hstore:long_name = "stored water effective layer thickness" ;

\\ index2 variables
double q(time, index2) ;
q:units = "m^2/s" ;
q:long_name = "water sheet discharge" ;

\\ index_ch variables
double S(time, index_ch) ;
S:units = "m^2" ;
S:long_name = "channel cross-sectional area" ;
double Q(time, index_ch) ;
Q:units = "m^3/s" ;
Q:long_name = "channel discharge" ;

// global attributes:
:title = "werder_sqrt_ch1_mesh4" ; \\ free-form title
:meshtype = "unstructured" ;  \\ "unstructured", "structured", "lumped"
:channels_on_edges = "yes" ;  \\ "yes" or "no"
:institution = "Mauro A Werder, ETHZ" ; \\ your name(s) and institution
:references = "http://shmip.bitbucket.io/" ; \\ fixed
}


Notes:

• The output variables are provided as point clouds, i.e. at (x,y)-points (or just x in 1D). This should hopefully allow any type of model to submit data, irrespective of mesh (or no mesh).
• Several sets of coordinates are possible, say one for cell-centres, one for cell-edges, etc. For each set have a dimension index1, index2, etc.
• For channels there is the special dimension index_ch.
• For channels, provide a connectivity connect_ch as well as channel mid-point coordinates coords_ch (if possible). The channel connectivity matrix has the form: column n should give the index (in index1) of the two endpoint nodes. Indices are zero-based, i.e. they are running from 0 to n-1.
• Provide all variables which you think are relevant for your model output, see section Output variables. Required is only effective pressure N (and the specified bed elevation B and ice thickness H, to check for correctness).
• All variables need the attributes units and long_name.
• If you don't have some particular variables, then leave them away. For instance, if you don't have channels, then leave away index_ch, coords_ch, connect_ch, etc.
• All output should be provided in SI units (m, kg, s) and derived (e.g. Pa). Don't use prefixes, say G or k.

## Questionnaires

You are asked to complete some small questionnaires: one for the whole inter-comparison and one for each suite.

Whole inter-comparison:

• Name of the model & citation
• Name of the modeller(s)
• On what computer was the model run
• Parallel or serial model
• Is the model available? If so, where?
• What revision/version of the model was used?
• Other remarks

Model tuning:

• What model parameters were set as given in section Parameters?
• Was the model tuned to A3 and/or A5? To $$N$$? $$q$$? $$Q$$?
• What parameters where used for the tuning? Values?
• What are the values of any additional model parameters?

For each suite A-F:

• How long was the model run for (model-time)?
• Are any parameters different from the ones used in Suite A?
• Remarks

For each run:

• CPU time used for the run.
• How confident are you of model convergence?

Result data upload is be handled through the ETH-Zurich site https://cifex.ethz.ch/. Once your results are ready, please request a guest account from Mauro Werder (valid for one month).

## Providing feedback

If you feel that this web-site needs clarification, then please email us or, better, file a bug report at https://bitbucket.org/shmip/shmip-website-source/issues?status=new&status=open. If there is a problem with the model setup, then file a bug report at https://bitbucket.org/shmip/hydro_intercomparison/issues?status=new&status=open.