Introduction to AEME • AEME

Summary

The AEME package hosts three one-dimensional hydrodynamic models: the DYnamic REservoir Simulation Model (DYRESM), the General Lake Model (GLM), and the General Ocean Turbulence Model (GOTM, which has been adapted for closed basins for application to lakes and reservoirs). The models can be coupled to their corresponding water quality models, the DYRESM-CAEDYM (Computational Aquatic Ecosystem Dynamics Model), GLM-AED2 (Aquatic Ecosystem Dynamics Model 2), and GOTM-WET (Water Ecosystem Tool).

Key aspects of the AEME package include:

Defined S4 class for aeme objects
Configuration of models from common and standardised inputs
Standardised calibration, manipulation and visualisation

AEME object

Description

The aeme object is the main object in the AEME package. It is an S4 class that contains all the information required to run a model. The aeme object contains the following slots:

lake - a list object containing information about the lake (name, id, latitude, longitude, elevation, shape, depth, area)
time - a list object containing information about the time (start, stop, time_step, spin_up)
configuration - a list object containing information about the configuration (dy_cd, glm_aed, gotm_wet)
observations - a list object containing information about the observations (lake, level)
inputs - a list object containing information about the inputs ()
inflows - a list object containing information about the inflows (data, factor)
outflows - a list object containing information about the outflows (data, factor, lvl)
water_balance - a list object containing information about the water balance configuration (method, use, data)
outputs - a list object containing information about the outputs ()

Lake

The lake slot contains information about the lake. It is a list object that contains the following objects:

name - Name of the lake (character).
id - Lake ID (character or numeric).
latitude - Latitude of the lake (numeric). If not provided, the latitude will be calculated from the centroid of the shape.
longitude - Longitude of the lake (numeric). If not provided, the longitude will be calculated from the centroid of the shape.
elevation - Elevation of the lake (numeric).
shape - Shape of the lake (sf object). The shape of the lake can be represented as a polygon. The centroid of the polygon will be used to calculate the latitude and longitude of the lake.
depth - Max depth of the lake (m) (numeric). Depth and area are used to generate a simple hypsographic curve if none is provided in the inputs slot.
area - Surface area of the lake (m2) (numeric)

Objects in bold are required for building and running the model.

Time

The time slot contains information about the time. It is a list object that contains the following objects:

start - Start date of the simulation (character). The start date must be in the format YYYY-MM-DD HH:MM:SS.
end - End date of the simulation (character). The end date must be in the format YYYY-MM-DD HH:MM:SS.
timestep - Timestep of the simulation (numeric). The timestep must be in seconds.
spin_up - List of spin up periods of the simulation for each model (numeric). The spin up period must be in days. The spin up period is the period of time that the model is run before the simulation period. The spin up period is used to initialise the model which is then discarded when examining the simulation period.

Configuration

The configuration slot is a list that contains each of the model configurations. This includes the configurations files for the hydrodynamic components as well as the aquatic ecosystem model components:

Files for hydrodynamic and ecosystem models.
Model	Hyrodynamic	Ecosystem
DYRESM-CAEDYM	.cfg file and .par file	.con, caedym3p1.bio, caedym3p1.chm and caedym3p1.sed files
GLM-AED	glm3.nml file	aed2.nml, phytos.nml, zoops.nml files
GOTM-WET	gotm.yaml and output.yaml files	fabm.yaml file

Observations

The observations slot is a list that contains observations of in-lake (lake) variables (e.g. water temperature, chlorophyll-a, dissolved oxygen etc.) and water level (level). The observations are used to assess model performance using the function and also to calibrate the model using the aemetools package.

The lake observations are stored in a data frame with the following columns:

Date - Date of the observation (character). The date must be in the format YYYY-MM-DD HH:MM:SS.
depth - Depth of the observation (m) (numeric). The depth must be in metres.
var - Variable name of the observation (character). The variable names an input preparation are designed in the AEME inputs article.
value - Value of the observation (numeric).

The level observations are stored in a data frame with the following columns:

Date - Date of the observation (character). The date must be in the format YYYY-MM-DD HH:MM:SS.
value - Value of the observation (numeric).

Creation

The aeme object can be created from a YAML file using the yaml_to_aeme function. The YAML file contains all the information required to run the model.

aeme <- yaml_to_aeme(path = path, "aeme.yaml")
slotNames(aeme)
#>  [1] "lake"          "time"          "configuration" "observations" 
#>  [5] "input"         "inflows"       "outflows"      "water_balance"
#>  [9] "output"        "parameters"

Manipulation

The aeme object can be manipulated using the AEME package functions. The functions are defined by the slot names of the aeme object. For example, the lake slot can be manipulated using the lake function.

# Load lake data
lke <- lake(aeme)
# Print lake data to console
print(lke)
#> $name
#> [1] "Wainamu"
#> 
#> $id
#> [1] "45819"
#> 
#> $latitude
#> [1] -36.8898
#> 
#> $longitude
#> [1] 174.469
#> 
#> $elevation
#> [1] 23.64
#> 
#> $shape
#> Simple feature collection with 1 feature and 4 fields
#> Geometry type: POLYGON
#> Dimension:     XY
#> Bounding box:  xmin: 174.4645 ymin: -36.89195 xmax: 174.4757 ymax: -36.88648
#> Geodetic CRS:  WGS 84
#>   lake_id   name_final    lake elevation                       geometry
#> 1   45819 Lake Wainamu wainamu     36.36 POLYGON ((174.4734 -36.8912...
#> 
#> $depth
#> [1] 13.07
#> 
#> $area
#> [1] 152343

# Change lake name
lke[["name"]] <- "AEME"

# reassign lake data to aeme object
lake(aeme) <- lke

aeme
#>             AEME 
#> -------------------------------------------------------------------
#>   Lake
#> AEME (ID: 45819); Lat: -36.89; Lon: 174.47; Elev: 23.64m; Depth: 13.07m;
#> Area: 152343 m2; Shape file: Present
#> -------------------------------------------------------------------
#>   Time
#> Start: 2020-08-01; Stop: 2021-06-30; Time step: 3600
#>  Spin up (days): GLM: 2; GOTM: 1; DYRESM: 1
#> -------------------------------------------------------------------
#>   Configuration
#>     Model controls: Absent 
#>           Physical   |   Biogeochemical
#> DY-CD    : Absent     |   Absent 
#> GLM-AED  : Absent     |   Absent 
#> GOTM-WET : Absent     |   Absent 
#> -------------------------------------------------------------------
#>   Observations
#> Lake: Present; Level: Present
#> -------------------------------------------------------------------
#>   Input
#> Inital profile: Absent; Inital depth: 13.07m; Hypsograph: Present (n=132);
#> Meteo: Present; Use longwave: TRUE; Kw: 1.31
#> -------------------------------------------------------------------
#>   Inflows
#> Data: Present; Scaling factors: DY-CD: 1; GLM-AED: 1; GOTM-WET: 1
#> -------------------------------------------------------------------
#>   Outflows
#> Data: Present; Scaling factors: DY-CD: 1; GLM-AED: 1; GOTM-WET: 1
#> -------------------------------------------------------------------
#>   Water balance
#> Method: 2; Use: obs; Modelled: Absent; Water balance: Absent
#> -------------------------------------------------------------------
#>   Parameters: 
#> Number of parameters: 0
#> -------------------------------------------------------------------
#>   Output: 
#> Number of ensembles: 0
#> DY-CD:    
#> GLM-AED:  
#> GOTM-WET:

Visualisation

The aeme object can be visualised simply using the plot function. The plot function can be applied to the different slots of the aeme object. For example, the lake slot can be visualised using the plot function.

plot(aeme, "lake")

plot(aeme, "input")

Build Model Ensemble

model_controls <- get_model_controls()
inf_factor = c("dy_cd" = 1, "glm_aed" = 1, "gotm_wet" = 1)
outf_factor = c("dy_cd" = 1, "glm_aed" = 1, "gotm_wet" = 1)
model <- c("dy_cd", "glm_aed", "gotm_wet")
aeme <- build_aeme(path = path, aeme = aeme, model = model,
                            model_controls = model_controls, inf_factor = inf_factor,
                            ext_elev = 5, use_bgc = TRUE)
#> Building simulation for AEME [2024-11-18 05:20:53]
#> Using observed water level
#> Missing values in observed water level
#> Using constant water level
#> Correcting water balance using estimated outflows (method = 2).
#> Calculating lake level using lake depth and a sinisoidal function.
#> Building DYRESM-CAEDYM for lake aeme
#> Copied in DYRESM par file
#> Writing DYRESM configuration
#> [1] "TEMPTURE SALINITY DO"
#> Writing DYRESM control file
#> Building GLM3-AED2 model for lake aeme
#> Copied in GLM nml file
#> Copied in AED nml file
#>    oxy_initial   = 625 replaced with 312.5
#> Building GOTM-WET for lake aeme
#> Copied all GOTM configuration files
#> instances/abiotic_water/initialization/sO2W 13 replaced with 10
aeme
#>             AEME 
#> -------------------------------------------------------------------
#>   Lake
#> AEME (ID: 45819); Lat: -36.89; Lon: 174.47; Elev: 23.64m; Depth: 13.07m;
#> Area: 152343 m2; Shape file: Present
#> -------------------------------------------------------------------
#>   Time
#> Start: 2020-08-01; Stop: 2021-06-30; Time step: 3600
#>  Spin up (days): GLM: 2; GOTM: 1; DYRESM: 1
#> -------------------------------------------------------------------
#>   Configuration
#>     Model controls: Present
#>           Physical   |   Biogeochemical
#> DY-CD    : Present    |   Present
#> GLM-AED  : Present    |   Present
#> GOTM-WET : Present    |   Present
#> -------------------------------------------------------------------
#>   Observations
#> Lake: Present; Level: Present
#> -------------------------------------------------------------------
#>   Input
#> Inital profile: Present; Inital depth: 13.07m; Hypsograph: Present (n=44);
#> Meteo: Present; Use longwave: TRUE; Kw: 1.31
#> -------------------------------------------------------------------
#>   Inflows
#> Data: Present; Scaling factors: DY-CD: 1; GLM-AED: 1; GOTM-WET: 1
#> -------------------------------------------------------------------
#>   Outflows
#> Data: Present; Scaling factors: DY-CD: 1; GLM-AED: 1; GOTM-WET: 1
#> -------------------------------------------------------------------
#>   Water balance
#> Method: 2; Use: obs; Modelled: Absent; Water balance: Present
#> -------------------------------------------------------------------
#>   Parameters: 
#> Number of parameters: 0
#> -------------------------------------------------------------------
#>   Output: 
#> Number of ensembles: 0
#> DY-CD:    
#> GLM-AED:  
#> GOTM-WET:

cfg <- configuration(aeme)