Running a Simulation

In order to run the FRICOSIPY model, the user must first configure the simulation by editing the configuration file: config.py

---

File Selection

For each simulation, the user must specify the three model input files:

• Static – the input file with topographic data that varies across the spatial domain \((x,y)\).
• Meteo – the input file with meteorological data that varies through time \((t)\).
• Illumination – the input file that determines whether grid nodes across the spatial domain \((x,y)\) are illuminated by the sun for any given timestep \((t)\).

---

Spatio-temporal Range

Temporal Range

The temporal range of the simulation must be specified by providing datetime values [yyyy-mm-dd hh:mm] indicating the starting and ending timestamp (which must be within the datetime range of the input meteorological file).

---

Spatial Subset:

The default setting of spatial_subset = False and [x_min, x_max, y_min, y_max] = None uses the entirity of the spatial domain of the input static file.

Alternatively, the user can set spatial_subset = True and define a bounding box of easting \((x)\) and northing \((y)\) values to reduce the spatial extent of the simulation. Modifying the spatial extent enables the user to run point or domain-wide simulations using the same static file and enables the clipping of surrounding terrain needed to accurately create the input illumination file.

---

Output Variables

The FRICOSIPY model reports a large selection of variables into the output NetCDF dataset. The user can (de)select any of these variables in the configuration file.

---

3-D Output Variables ( \(𝑥\) , \(𝑦\) , \(t\) )

The FRICOSIPY model will report the following variables for each spatial node \((x,y)\) for every simulation timestep \((t)\):

Meteorological Variables \((6)\)

Variable	Description	Unit
AIR_TEMPERATURE	Air temperature	°C
AIR_PRESSURE	Barometric air pressure	hPa
RELATIVE_HUMIDITY	Relative humidity	%
SPECIFIC_HUMIDITY	Specific humidity	g kg\(^{-1}\)
WIND_SPEED	Wind speed	m s\(^{-1}\)
FRACTIONAL_CLOUD_COVER	Fractional cloud cover	—

---

Surface Energy Fluxes \((7)\)

Variable	Description	Unit
SHORTWAVE	Net shortwave radiation flux	W m\(^{-2}\)
SENSIBLE	Net sensible radiation flux	W m\(^{-2}\)
LATENT	Net latent radiation flux	W m\(^{-2}\)
LONGWAVE	Net longwave radiation flux	W m\(^{-2}\)
RAIN_HEAT	Rain heat flux	W m\(^{-2}\)
SUBSURFACE	Subsurface heat flux	W m\(^{-2}\)
MELT_ENERGY	Melt energy flux	W m\(^{-2}\)

---

Surface Mass Fluxes \((8)\)

Variable	Description	Unit
RAIN	Rain	m w.e.
SNOWFALL	Snowfall	m w.e.
EVAPORATION	Evaporation	m w.e.
SUBLIMATION	Sublimation	m w.e.
CONDENSATION	Condensation	m w.e.
DEPOSITION	Deposition	m w.e.
SURFACE_MELT	Surface melt	m w.e.
SURFACE_MASS_BALANCE	Surface mass balance	m w.e.

---

Subsurface Mass Fluxes \((4)\)

Variable	Description	Unit
REFREEZE	Refreezing	m w.e.
SUBSURFACE_MELT	Subsurface melt	m w.e.
RUNOFF	Runoff	m w.e.
MASS_BALANCE	Mass balance	m w.e.

---

Other \((11)\)

Variable	Description	Unit
SNOW_HEIGHT	Snow height	m
SNOW_WATER_EQUIVALENT	Snow water equivalent	m w.e.
TOTAL_HEIGHT	Total height	m
SURFACE_ELEVATION	Surface elevation	m a.s.l.
SURFACE_TEMPERATURE	Surface temperature	\(^\circ\)C
SURFACE_HUMIDITY	Surface humidity	g kg\(^{-1}\)
SURFACE_ALBEDO	Surface albedo	—
N_LAYERS	Number of layers	—
FIRN_TEMPERATURE *	Firn temperature	\(^\circ\)C
FIRN_TEMPERATURE_CHANGE *	Firn temperature change	\(^\circ\)C \(^{-1}\)
FIRN_FACIE *	Firn Facie (acc. Shumskii, 1964) 0 : Recrystillisation (dry snow) 1 : Recrystallisation-infiltration 2 : Cold-infiltration 3 : Warn-infiltration (temperate)	—

( * Note: Firn temperatures and facies are evaluated at the depth prescribed by the firn_temperature_depth parameter. )

---

4-D Output Variables ( \(x\) , \(𝑦\) , \(z\) , \(t\) )

If the user sets full_field == True, then the FRICOSIPY model will also report the following subsurface variables for every layer \((z)\):

Subsurface Variables \((12)\)

Variable	Description	Unit
DEPTH	Layer depth	m
HEIGHT	Layer height	m
DENSITY	Layer density	kg m\(^{-3}\)
TEMPERATURE	Layer temperature	\(^\circ\)C
WATER CONTENT	Layer volumetric water content	—
COLD CONTENT	Layer cold content	J m\(^{-2}\)
POROSITY	Layer volumetric porosity	—
ICE FRACTION	Layer volumetric ice fraction	—
IRREDUCIBLE WATER	Layer irreducible water content	—
REFREEZE	Layer refreeze	m w.e.
HYDRO YEAR	Layer hydrological year	yyyy
GRAIN SIZE	Layer grain size	mm

---

Output Reporting Frequency

By default, as with the original COSIPY model, FRICOSIPY reports each output variable for every simulation timestep. However, this can produce extremely large output datasets when operating with a long simulation time period. Therefore, the FRICOSIPY model offers a few methods to customise the reporting frequency for the output dataset.

---

\((i)\) Model Initialisation / Spin-up

In particular for subsurface investigations, it is customary to precede a simulation with an initialisation phase / spin-up to attain steady-state conditions. Therefore, by setting
model_spin_up = True and stating an inital timestamp in datetime format [yyyy-mm-dd hh:mm], the user can specify an initial time period of the simulation where output variable data is neither aggregated nor recorded.

---

\((ii)\) Output Timestamps

The user can also directly specify the output timestamps on which the simulation reports output variables. The user must simply set reduced_output = True and place a CSV with the desired timestamps, expressed in datetime format [yyyy-mm-dd hh:mm], in the 'data/output/output_timestamps/' directory. Inbetween the reported values, variables are aggregated: meteorological conditions and energy fluxes are averaged, mass fluxes are summated and state variables are reported as their instantaneous values.

Ex. An exemplar output timestamps CSV file showing yearly timestamps for the time period 2000 – 2025, which would reduce the output dataset from 219,150 hourly values to 25 aggregated annual values.

2000-12-31 23:00
2001-12-31 23:00
⋮
2024-12-31 23:00
2025-12-31 23:00

---

Dask Parallelisation

The FRICOSIPY model, supports multi-thread processing using the Dask parallel computing library. By modifying workers = 1, the user specifies the number of spatial nodes that the simulation will concurrently simulate

---

Executing a Simulation

Once the configuration file is set up, the FRICOSIPY model is executed with the command:

python FRICOSIPY.py

As the simulation starts, detailed information will be reported into the terminal. Thereafter, progress will be indicated upon the completion of each spatial node until the simulation is complete.

---