User guide for LAKE model version 2.3
Compiling the model and creating a project
The only prerequisite to install LAKE model is Fortran compiler.
The model can be built from source code by GNU and Intel Fortran compilers. GNU compiler is set by default in the model install configuration. Install configuration is given in files Makefile and source/Makefile.
If you want to use Intel compiler, you have to change variable FC value to FC = ifort in these files.
Once you unpack the LAKE model archive or cloned its git project just type in the model root folder
user@computer:~/LAKE/lake$ make allto build the model from the source code. The next step is to configure the
model for you needs. This means that you create a project, identified
by the project name hereafter we will refer to it as project_name,
it may be any text, e.g. combination of the lake name and the time span you need to simulate this lake, for instance, "Valkea-Kotinen2006"). Once you've chosen the project name, type
user@computer:~/LAKE/lake$ ./crproj <project_name>This creates the folder structure in ./results, to which the output
files will be written. After that, create ./setup/project_name_driver.dat and ./setup/project_name_setup.dat files. These files must have
a certain structure, so that we recommend that you create them by copying from
sample files already existing in ./setup. Once copied, you can modify them appropriately. This is what the next two sections are devoted to.
To run the model you have to provide a file with meteorological data. It must be an ASCII table, where each column contains a time series of a certain meteorological variable. A sequence of columns is set in /setup/project_name_driver.dat. Shortly after start, the model will seek the file with meteorological data as ./data/project_name.dat.
Configuring the driver file
Driver file is used to set the outer environment of the LAKE model
that is normally the atmospheric model. This means, that atmospheric
model calculates the atmospheric forcing for the LAKE model, and some
external parameters are also being passed to the LAKE model through
the driver interface. When the LAKE model is coupled to atmospheric
model the driver file is not needed.
The format of the driver file is following. Each string of the file
starts with a comment (indicated by #) or with a keyword. The last
string of the file contains the keyword end. The keywords may
be listed in any order, but we recommend to keep them in thematic groups,
as it is done in sample files. Each keyword, excepting end, must
have a value that is set after the keyword at the same string separated
by at least one space. Some keywords are followed by a group of numbers.
Parameters in driver file
| Keyword | Description and acceptable values set |
|---|---|
| dataname | The project name, character, enclosed by ' '
|
| forc_format | The input file format: 0 - ASCII(text), 1 - netcdf |
| npoints | Number of lakes to be simulated |
| select_call, opt | The list of up to 20 numbers, each at new line, denoting particular lakes, that will be simulated. Relevant only if npoints > 1. Other lakes are omitted in the simulation. |
| lakinterac | The number of interacting lakes: 1 - no interaction, 2 - two lakes are linked by a channel, > 2 - not operational. |
| form | obsolete, put 0 (means adjustable ASCII format, see below) |
| height_T_q | The height above the lake surface at which temperature and humidity are given (calculated by the atmospheric model or measured), m |
| height_u | The height above the lake surface at which the wind speed is given (calculated by the atmospheric model or measured), m |
| interval | The time step of meteorological data, days |
| rad | Defines, atmospheric radiation (1) or net radiation (2) is in the relevant column of datafile, relevant if input file is ASCII (forc_format = 0) |
The set of parameters for adjustable format of input text file, relevant if forc_format = 0, form = 0
| Keyword | Description and acceptable values set |
|---|---|
| N_header_lines | The number of lines in a file header |
| N_coloumns | The total number of coloumns in a file |
| N_Year | The number of coloumn with the number of a year (not used in the model) |
| N_Month | The number of coloumn with the number of a month (not used in the model) |
| N_Day | The number of coloumn with the number of a day (not used in the model) |
| N_Hour | The number of coloumn with the number of a hour (not used in the model) |
| N_Uspeed | The number of coloumn with x-component speed, m/s |
| N_Vspeed | The number of coloumn with y-component speed, m/s |
| N_Temp | The number of coloumn with air temperature, K |
| N_Hum | The number of coloumn with air humidity, kg/kg |
| N_Pres | The number of coloumn with atmospheric pressure, Pa |
| N_SWdown | The number of coloumn with total solar radiation, W/m^2 |
| N_LWdown | The number of coloumn with atmospheric radiation, W/m^2) |
| N_Precip | The number of coloumn with precipitation, m/s |
| N_SensFlux | The number of coloumn with sensible heat flux, W/m^2 |
| N_LatentFlux | The number of coloumn with latent heat flux, W/m^2 |
| N_Ustar | The number of coloumn with friction velocity, m/s |
| N_surfrad | The number of coloumn with radiation emitted by the surface, W/m^2 |
| N_NetRad | The number of coloumn with net radiation, W/m^2 |
| N_cloud | The number of coloumn with total cloudiness, fraction |
| N_SurfTemp | The number of coloumn with water surface temperature, K; if not -1, then the surface temperature is used as Dirichlet boundary condition for temperature equation |
The parameters of time integration
| Keyword | Description and acceptable values set |
|---|---|
| year0 | Julian year of initial moment of integration |
| month0 | Julian month of initial moment of integration |
| day0 | Julian day of initial moment of integration |
| hour0 | Julian hour (may be fraction) of initial moment of integration |
| tinteg | The duration of integration, days |
| spinup_times | Number of spinup periods |
| spinup_period | The duration of spinup period, days |
| dt | Time step of integration, s |
| call_Flake | The switch for integrating FLake model: 1 - on, 0 - off |
| control_point | 0 – no control point, 1 – starting with initial conditions defined by init_T and writing control point regularly with cp_period interval, 2 – the same as 1 but starting with last saved control point |
| cp_period | The interval of control point output, days; relevant if control_point>0 |
External physical parameters of a lake
| Keyword | Description and acceptable values set |
|---|---|
| extwat | Solar radiation extinction in a water body, m^-1 |
| extice | Solar radiation extinction in an ice, m^-1 |
| alphax | Slope of water surface in the x-direction, deg |
| alphay | Slope of water surface in the y-direction, deg |
| a_veg | Effective cross-section of vegetation, m^2/m^2 |
| c_veg | Friction coefficient of vegetation in water, n/d |
| h_veg | The height of vegetation in the lake, m |
| kor | Coriolis parameter, s^-1; if -999., then it is computed from latitude |
| phi | Latitude, deg |
| lam | Longitude, deg |
| fetch | Average wind fetch, m |
| area_lake | Lake area, m^2 |
| cellipt | The ratio of x dimension to y dimension of a lake, n/d |
| lakeform | The form of the lake's horizontal cross-section: 1 -- ellipse, 2 -- rectangle |
| trib_inflow | Total tributaries' inflow, m^3/s; if -9999., then it is dynamically adjusted to keep the lake depth nearly constant |
| morphometry | Depth - lake cross-section area table, m^2; if not given, the area is constant with depth |
| effl_outflow | effluent discharge parameters group, specifying polynomial dependence of discharge on water level; the last value is relative altitude of effluent bottom over lake bottom (at deepest points, respectively); the first N values are polynomial coefficients, where N stands after effl_outflow keyword |
Initial conditions keywords
| Keyword | Description and acceptable values set |
|---|---|
| l10 | Initial ice thickness, m |
| h10 | Initial water thickness (lake depth), m |
| select_h10, opt | The list of up to 20 depths, each at new line, specifying lakes' depths, for lakes selected by select_call. |
| ls10 | Initial bottom ice thickness, m |
| hs10 | Initial snow thickness, m |
| Ts0 | Initial temperature of the top mixed layer, °C |
| Tb0 | Initial bottom temperature, °C |
| Tbb0 | Initial temperature at the bottom of soil layer, °C |
| Tbb0 | Initial mean temperature of the water column, °C |
| h_ML0 | Initial mixed-layer depth, m |
| Sals0 | Initial salinity in the mixed layer, kg/kg |
| Salb0 | Initial bottom salinity, kg/kg |
| us0 | Initial x-component of velocity in the mixed layer, m/s |
| vs0 | Initial y-component of velocity in the mixed layer, m/s |
| init_T | The type of profiles initialization: 1 - using h_ML0, Ts0 and Tb0; 2 - using Tm, Ts0 and Tb0; 3 - using the temperature profile, specified in \*_setup.dat or file specified after keyword T_profile; The temperature, salinity, CH_4,CO_2,O_2 will be initialized via profiles. init_T=2 works only for temperature |
Output controlling parameters
| Keyword | Description and acceptable values set |
|---|---|
| nstep_ncout | the interval of netcdf output from driver, timesteps (if -1 no netcdf output from driver) |
| nstep_out_Flake | the interval of output of Flake variables from driver, timesteps (if -1 the output of FLake variables from driver is not implemented), relevant if call_Flake = 1 |
| moving_average_window | the interval of moving average, netcdf output steps (intervals) |
| mean_cycle_period | the length of mean cycle, netcdf output steps (intervals) |
Configuring the setup file
Setup file has the same format, as the driver file. The list of parameters is given in a table below.
The parameters of setup file
General parameters
| Keyword | Description and acceptable values set |
|---|---|
| path | The full path to the model root, needed on some systems; normally, specify it as ''
|
| runmode | The mode of LAKE model: 1 - standalone, 2 - driven by atmospheric model |
| omp | The OpenMP: 0 - not used, 1 - used; normally OpenMP does not give significant speedup |
Spatio-temporal resolution group
| Keyword | Description and acceptable values set |
|---|---|
| nstep_keps | Number of tim esteps of k-epsilon parameterization per on model timestep, recommended value is 1 |
| M | Number of layers in water |
| ns | Number of layers in soil |
| nsoilcols | Number of soil columns (1 - single soil column contacting with the lowest numerical layer (of water or deep ice) only, > 1 - additional soil columns at the bottom slope, contacting with all numerical layers of water, ice and deep ice; morphometry information is necessary in driver file, if nsoilcols > 1) |
| Mice | Number of layers in bottom ice |
| d_surf | Grid zooming parameter at the surface, n/d |
| d_bot | Grid zooming parameter at the bottom, n/d |
Physical parameterizations
| Keyword | Description and acceptable values set |
|---|---|
| varalb | Water albedo: 0 - constant, 1 - zenith-angle dependent |
| PBLpar | Surface fluxes scheme: -1 - sensible, latent heat and momentum fluxes are given as input for the model; 0 - the latent heat flux is set to zero, while sensible heat and momentum fluxes are constant in time, specified by sensflux0 and momflux0; 1 - Businger-Dayer formulas (Monin-Obukhov theory) for exchange coefficients, the code from INM RAS climate model; 2 - formulation from NH3d (Louis, 1979); 3 - formulation from FLake; 4 - formulation implemented by D.Chechin |
| waveenh | The shallow water correction of surface fluxes (Panin et al., 1996) (0 - off, 1 - on) |
| momflxpart | Momentum flux treatment: 0 - all momentum flux from the atmosphere is consumed by currents acceleration; 2 - momentum flux from the atmosphere is partitioned between wave development (controlled by fetch) and currents acceleration (Stepanenko et al., 2014) |
| c_d | The momentum exchange coefficient, n/d; if -999, momentum flux is calculated by surface flux scheme |
| kwe | The factor of turbulence enhancement by wave breaking (wave energy factor), n/d (used in boundary conditions of K-\epsilon model) |
| relwind | In momentum flux calculation the currents speed is substracted from wind speed: 1 - on, 0 - off |
| eos | Equation of state: 1 - from Hostetler model (freshwater), 2 - TEOS-2010 (currently not operational), 3 - for Kivu lake (Schmid et al., 2003), 4 - UNESCO formula (freshwater), 5 - McCatcheon et al., 1993 |
| lindens | Switch for using linearized equation of state respective to temperature and salinity: 1 - on, 0 - off |
| nmeltpoint | Melting point: 0 - constant, 0 °C, 1 - linearly dependent on salinity, 2 - TEOS-2010 formula |
| Turbpar | Turbulence model: 2 - K-\epsilon closure; 8 - Hendersson-Sellers diffusivity (1985); 9 - Henderson-Sellers diffusivity adopted for shallow lakes |
| stabfunc | Stability function in K-\epsilon : 1 - constant coefficients (standard K-\epsilon model); 2 - stability functions according to (Canuto et al., 2001); 3 - stability functions according to (Galperin et al., 1988) |
| kepsbc | Boundary conditions in K-\epsilon model: 1 - Neuman boundary conditions for unstratified sheared flow (Burchard, 2002); 2 - Neuman boundary conditions for unstratified non-sheared flow with wave breaking; 3 - Neuman boundary conditions for unstratified sheared flow with wave breaking; 4 - Neuman boundary conditions for free convection |
| soiltype | The soil type: 1 - sand, 2 - loamy sand, 3 - sandy loam, 4 - loam, 5 - silt loam, 6 - sandy clay loam, 7 - clay loam, 8 - silty clay loam, 9 - sandy clay, 10 - silty clay, 11 - clay |
| soil_depth | The depth of the soil layer, m |
| soilswitch | The switch for soil model: 0 - off, 1 - on |
| saltice | The switch for salinity in ice: 0 - off, 1 - on |
| tricemethhydr | The ice treatment in the soil pores: 0. - treat as pure ice; 1. - treat as methane hydrate |
| skin | The skin temperature parameterization: 0 - off, 1 - on |
| massflux | The massflux parameterization of convection (Siebesma et al., 2007): 0 - off, 1 - on. |
| ifrad | Radiation fluxes at the water surface: 0 - set to zero; 1 - full treatment |
| ifbubble | Switch for the bubble model: 0 - off (bubbles do not change with depth); 1 - on |
| carbon_model | Switch for the carbon model: 1 - Stefan and Fang model; 2 - Hanson et al. model |
| sedim | Gravitational sedimentation of tracer in water: 0 - off, 1 - on |
| salsoil | Switch for salinity transport in soil: 0 - off (zero flux at the bottom), 1 - on |
| dyn_pgrad | Dynamic pressure gradient: 0 - off, 1 - barotropic pressure gradient, 2 - two-layer approximation for pressure gradient, 3 - multilayer model for pressure gradient |
| botfric | The law for friction at the sloping bottom: 0 - no bottom friction, 1 - linear friction, 2 - quadratic friction |
| horvisc | Horizontal viscosity, m^2/s, used to damp the 1-st horizontal velocity mode |
| backdiff | Switch for background diffusivity by Hondzo and Stefan (1993); 1 – off, 1 – on |
| nManning | Manning’s coefficient, relevant for dyn_pgrad =5 |
| zero_model | Switch for zero-dimensional model: 0 -off, 1 - on |
| thermokarst_meth_prod | Switch for old organics methane production under thermokarst lakes: 1. - on, 0. - off |
| soil_meth_prod | Switch for new organics methane production under lakes: 1. - on, 0. - off |
| outflpar | The treatment of effluent temperature: 0 - value at the outflow = cross-section mean; 1 - the cross-section mean = 0.5*(inflow value + outflow value); 2 - variables at the outflow are calculated using Lagrangian approach |
| sensflux0 | Sensible heat flux upwards, constant in time (relevant if PBLpar = 0), W/m^2 |
| momflux0 | Momentum flux downwards (positive), constant in time (relevant if PBLpar = 0), N/m^2 |
| soilbotflx | The constant heat flux at the soil or lake bottom (depending on if soil is switched on or off), W/m^2 |
| cuette | The switch for Cuette flow boundary conditions: 0 - no, 1 - Dirichlet conditions for temperature and velocities at both top and bottom boundaries, 11 - the same as 1, but momentum flux is imposed at the top boundary; Note! Other switches for physical parameterizations and initial conditions must be adjusted to the Cuette flow configuration |
| deadvol | Variables at the outflow are calculated using Lagrangian approach |
Initial conditions
| Keyword | Description and acceptable values set |
|---|---|
| T_profile | Initial temperature (°C, col.2), salinity (kg/kg, col.3), CH_4 (mol/m^3, col.4), CO_2 (mol/m^3, col.5), O_2 (mol/m^3, col.6), DIP (mol/m^3, col.7) profiles, at depth levels (m, col.1) |
Tributaries and effluents
| Keyword | Description and acceptable values set |
|---|---|
| tribheat | The switch for thermal effect of tributaries and effluents: 0 - off, 1 - on, constant inflow profiles, 2 - on, time-dependent inflow profiles |
| N_tribin | The number of tributaries, the next line should be a sequence of N_tribin numbers, from 1 to 4, describing the location of each tributary |
| N_triblev | The number of levels in tributaries data, relevant if tribheat = 1 or 2 |
| iefflloc | from 1 to 4, the location of an effluent |
| fileinflow | The name of file in data folder with time-dependent inflow profiles. Relevant if tribheat = 2,3 |
| fileoutflow | The name of file in data folder with time-dependent outflow profiles. Relevant if tribheat = 2,3 |
| dttribupdate | Time step for profiles update in fileinflow and fileoutflow, days. Relevant if tribheat = 2,3 |
Running the model
The model is launched by typing in the terminal
user@computer:~/LAKE/lake$ ./lake.outHowever, it usually happen that you need to run the model with different configurations (input parameters). In this case we recommend to use the script launch in a root folder. To run the model you invoke this script with an argument specifying the experiment label
user@computer:~/LAKE/lake$ ./launch <project_name>_<spec>for instance
user@computer:~/LAKE/lake$ ./launch Valkea-Kotinen2006_baseThis script does the following. It runs the model, the model writes output data to results/Valkea-Kotinen2006, then the script creates results/Valkea-Kotinen2006_base and copies there the content of results/Valkea-Kotinen2006, setup/Valkea-Kotinen2006_setup.dat and setup/Valkea-Kotinen2006_driver.dat. As a result, both model output and configuration files of an experiment labeled as base are written in a specific directory, so you will not mix them with that from other experiments.
Model output
The model output is written in ./results/project_name folder.
user@computer:~/LAKE/lake/results/project\_name$ ls
daily everystep hourly monthly netcdf time_series
user@computer:~/LAKE/lake/results/project\_name$The folders hourly, daily, monthly contain vertical profiles
of different variables in a lake, averaged over respective time intervals. Output files in netCDF format are being placed in netcdf folder, and files
with time series - in time_series folder. Sometimes, for debugging purposes,
it is advantageous to use the output at every time step of the model's numerical scheme, the respective files reside in time_series