FLAREr

This document serves as a user guide and a tutorial for the FLARE (Forecasting Lake and Reservoir Ecosystems) system (Thomas et al. 2020). FLARE generates forecasts with uncertainty of water temperature and water quality for 1- to 35-day-ahead time horizon at multiple depths of a lake or reservoir. It uses data assimilation to update the initial starting point for a forecast and the model parameters based a real-time statistical comparisons to observations. It has been developed, tested, and evaluated for Falling Creek Reservoir in Virginia (Thomas et al. 2020), Beaverdam Reservoir in Virginia (Wander et al. 2024), Lake Sunapee in New Hampshire (Woelmer et al. 2024), National Ecological Observatory Network lakes across the United States (Thomas et al. 2023 and Olsson et al. 2024), and Lough Feeagh in Ireland (Páiz et al. 2025). FLARE was among the top-performing forecast models in a year-long water quality forecasting challenge across seven lakes (Olsson et al. 2025).

FLAREr is a set of R scripts that

• Generating the inputs and configuration files required by the General Lake Model (GLM)
• Applying data assimilation to GLM
• Processing and archiving forecast output
• Visualizing forecast output

FLARE uses the 1-D General Lake Model (Hipsey et al. 2019) as the mechanistic process model that predicts hydrodynamics of the lake or reservoir. For forecasts of water quality, it uses GLM with the Aquatic Ecosystem Dynamics library. FLARE v4.0 requires GLM-AED version 4, which adds the NetCDF restart capacity that FLARE's restart workflow depends on. GLM-AED 4 is currently available on the v4alpha branch of GLM-AED and is provided by the GLMAEDr package (see Installation below).

More information about the GLM can be found here:

• GLM 3.0.0 manuscript
• GLM on GitHub
• GLM users guide

FLARE development has been supported by grants from the U.S. National Science Foundation (CNS-1737424, DBI-1933016, DBI-1933102)

Installation

You will need to download the necessary packages before running.

remotes::install_github("FLARE-forecast/FLAREr")

Next, you need the GLM model. You can get in using multiple pathways

The recommended way is to install the GLMAEDr package from Github, which downloads and manages the GLM binary for you. It provides GLM-AED version 4 (the v4alpha build), which FLARE v4.0 requires for its NetCDF restart capacity:

remotes::install_github("flare-forecast/GLMAEDr")
GLMAEDr::glm_install()
Sys.setenv('GLM_PATH'=GLMAEDr::glm_path())

Windows is not currently supported. GLM-AED version 4 binaries are not yet built for Windows, so GLMAEDr cannot provide a working GLM binary on that platform. Use macOS or Linux (for example, via WSL2 on Windows) until v4 Windows binaries are available.

The alternative pathways below predate GLM-AED 4 and may not include the NetCDF restart capacity. Use them only if the binary they provide is a GLM-AED 4 (v4alpha) build; otherwise the FLARE restart workflow will not work.

Alternatively, you can install the GLM3r package from Github using

remotes::install_github("rqthomas/GLM3r")

or you can download it from the AquaticEcoDynamics GitHub organization. This code assumes you are in the directory with the FLARE configurations and workflow subdirectories

download.file("https://github.com/rqthomas/glm-aed/archive/refs/heads/main.zip", "glm_aed.zip")
unzip("glm_aed.zip")

if you are running on Mac you will need to run:

system2("chmod","u+x glm-aed-main/binaries/macos/Sonoma/glm_latest/glm")
system2("./glm-aed-main/binaries/macos/Sonoma/glm_latest/glm")

if you are running on Linux you will need to run:

system2("chmod","u+x glm-aed-main/binaries/ubuntu/22.04/glm_latest/glm")
system2("./glm-aed-main/binaries/ubuntu/22.04/glm_latest/glm")

Use

FLAREr is a set of functions that address key steps in the forecasting workflow.

Requires

User-generated insitu observations, meteorology, and inflow/outflow in a specified format. See the FLARE example vignette for format specification.

The expected top-level directory structure (referred to as lake_directory in the code) is:

lake_directory/
├── configuration/
│   └── <config_set_name>/   # e.g. "default" — holds FLARE yml files and GLM nml
├── drivers/
│   ├── met/                 # meteorological driver files
│   ├── iflow/               # inflow driver files
│   └── oflow/               # outflow driver files
└── targets/
    └── <site_id>/           # observed in-situ data

The configuration/ sub-directory must contain a configure_run.yml file and the GLM namelist (glm3.nml). Additional configuration files (states, parameters, observations) live alongside these. See the FLAREr example vignette for full format specifications.

Quick Run

The code below will produce a single forecast for Falling Creek Reservoir using configuration files included with the package.

library(arrow)
library(tidyverse)
library(FLAREr)

remotes::install_github("flare-forecast/GLMAEDr")
GLMAEDr::glm_install()
Sys.setenv('GLM_PATH'=GLMAEDr::glm_path())


dir.create(tempdir(),showWarnings = FALSE)
lake_directory <- file.path(tempdir(), "extdata")
file.copy(system.file("extdata", package = "FLAREr"), tempdir(), recursive = TRUE)
run_flare(lake_directory = lake_directory,configure_run_file = "configure_run.yml", config_set_name = "default")

open_dataset(file.path(lake_directory,"forecasts/parquet")) |> 
  filter(variable == "temperature",
         depth == 1) |> 
  collect() |> 
  ggplot(aes(x = datetime, y = prediction, group = parameter)) +
  geom_line() +
  geom_vline(aes(xintercept = as_datetime(reference_datetime))) +
  labs(title = "1 m water temperature forecast")

Storage backends (local, S3, and FaaSr)

FLAREr reads its drivers, targets, and configuration — and writes its
forecast output, scores, and restart files — through a single I/O layer
that can target three different backends. The backend is selected per run
from two flags in configure_run.yml:

When neither flag is set both default to FALSE (local mode), so
existing local configurations keep working unchanged. use_faasr: TRUE
requires use_s3: TRUE — FaaSr mode is always cloud-backed and FLAREr
errors at startup if use_faasr is set without use_s3.

Bucket names and endpoints for s3 and faasr modes are defined in the
s3: block of configure_flare.yml, with one entry per DataStore (e.g.
drivers, targets, forecasts_parquet, restart, scores). Set
anonymous: true on a store for public read-only buckets; non-anonymous
access reads AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY from the
environment.

FaaSr (serverless cloud execution)

FaaSr runs R functions as serverless actions on
platforms such as GitHub Actions, AWS Lambda, and OpenWhisk, using
S3-compatible DataStores for persistent storage. When FLAREr runs as a
FaaSr action, set use_faasr: TRUE so that all object I/O is routed
through the FaaSr runtime's helpers (faasr_get_file(),
faasr_put_file(), faasr_arrow_s3_bucket(), …) instead of calling
aws.s3 directly. FaaSr supplies the DataStore credentials, so they do
not need to be baked into the FLAREr configuration.

FaaSr is not a package dependency of FLAREr: its helper functions are
injected into the global environment by the FaaSr executor when an action
starts. If use_faasr: TRUE but those helpers are not present — for
example, when the same configuration is run outside a FaaSr container —
FLAREr prints a warning and falls back to s3 mode.

Inside a FaaSr action function, call initialize_faasr(config) once
before run_flare() to validate the configuration: it errors on the
inconsistent use_faasr: TRUE / use_s3: FALSE combination and warns
early if AWS credentials are missing. See ?initialize_faasr for
details.