| Title: | PEcAn Package for Integration of the LPJ-GUESS Model |
|---|---|
| Description: | This module provides functions to link LPJ-GUESS to PEcAn. |
| Authors: | Istem Fer [aut, cre], Tony Gardella [aut], University of Illinois, NCSA [cph] |
| Maintainer: | Istem Fer <[email protected]> |
| License: | BSD_3_clause + file LICENSE |
| Version: | 1.9.0.9000 |
| Built: | 2026-06-05 14:48:20 UTC |
| Source: | https://github.com/PecanProject/pecan |
Calculates soil carbon This should be put into the SDA procedure.
calculateGridcellSOC( model.state, pools = c("SOILSTRUCT", "SOILMETA", "SOILMICRO", "SLOWSOM", "PASSIVESOM") )calculateGridcellSOC( model.state, pools = c("SOILSTRUCT", "SOILMETA", "SOILMICRO", "SLOWSOM", "PASSIVESOM") )
model.state |
A large multiply-nested list containing the entire LPJ-GUESS state as read by
function |
pools |
"SOILSTRUCT","SOILMETA","SOILMICRO","SLOWSOM","PASSIVESOM" (see somdynam.cpp) |
The total SOC in Gridcell. The unit is consistent with cmass in state, usually kg C m-2
Yinghao Sun
Calculates a per-PFT, gridcell-summed quantity from the LPJ-GUESS state, correctly averaging over patches. This should be put into the SDA procedure.
calculateGridcellVariablePerPFT( model.state, variable, pft.params, min.diam = 5 )calculateGridcellVariablePerPFT( model.state, variable, pft.params, min.diam = 5 )
model.state |
A large multiply-nested list containing the entire LPJ-GUESS state as read by
function |
variable |
A character string specifying what variable to extract. This can be chosen based on the LPJ-GUESS variable name as recorded in the big list of list (that represents describes the model state in R). Once special case is "biomass" which returns the sum of "cmass_leaf", "cmass_root", "cmass_sap" and "cmass_heart" |
pft.params |
A data frame containing PFT parameters such as allometric coefficients. |
min.diam |
Minimum tree diameter (in cm) required for inclusion in calculations. |
A numeric vector, with one entry per PFT
Matthew Forrest
Identifies the line number of the matching closing bracket for a given opening bracket.
find_closing(find = "}", line_no, file_in, if_else_check = FALSE)find_closing(find = "}", line_no, file_in, if_else_check = FALSE)
find |
A character string of the opening bracket. |
line_no |
A numeric value indicating the line number to start the search. |
file_in |
A character vector of the file content. |
if_else_check |
Optional. A logical value indicating whether to check for if/else blocks (default is FALSE). |
A numeric value indicating the line number of the matching closing bracket.
met2model wrapper for LPJ-GUESS
met2model.LPJGUESS( in.path, in.prefix, outfolder, start_date, end_date, overwrite = FALSE, verbose = FALSE, ... )met2model.LPJGUESS( in.path, in.prefix, outfolder, start_date, end_date, overwrite = FALSE, verbose = FALSE, ... )
in.path |
location on disk where inputs are stored |
in.prefix |
prefix of input and output files |
outfolder |
location on disk where outputs will be stored |
start_date |
the start date of the data to be downloaded (will only use the year part of the date) |
end_date |
the end date of the data to be downloaded (will only use the year part of the date) |
overwrite |
should existing files be overwritten |
verbose |
should the function be very verbose |
... |
additional arguments, currently ignored |
Istem Fer
Convert LPJ-GUESS output to netCDF
model2netcdf.LPJGUESS(outdir, sitelat, sitelon, start_date, end_date)model2netcdf.LPJGUESS(outdir, sitelat, sitelon, start_date, end_date)
outdir |
Location of LPJ-GUESS model output |
sitelat |
Latitude of the site |
sitelon |
Longitude of the site |
start_date |
Start time of the simulation |
end_date |
End time of the simulation |
Istem Fer
Function to translate pecan param names and units to lpjguess names and units
pecan2lpjguess(trait.values)pecan2lpjguess(trait.values)
trait.values |
trait.values, list |
translated list
Istem Fer
Reads a binary file formatted for LPJ-GUESS and extracts relevant data.
read_binary_LPJGUESS(outdir, rundir, version = "PalEON", bak = FALSE)read_binary_LPJGUESS(outdir, rundir, version = "PalEON", bak = FALSE)
outdir |
The directory where the .state file is stored (e.g., .../state/1961) |
rundir |
The directory where the corresponding params.ins is stored (e.g., .../run/ENS-00001) |
version |
A character string specifying the LPJ-GUESS version (default is "PalEON"). |
bak |
whether read bak.state or not (default is FALSE) |
A matrix or list containing the extracted data.
Istem Fer, Yinghao Sun
Read Restart for LPJGUESS
read_restart.LPJGUESS(outdir, runid, stop.time, settings, var.names, params)read_restart.LPJGUESS(outdir, runid, stop.time, settings, var.names, params)
outdir |
output directory |
runid |
run ID |
stop.time |
year that is being read |
settings |
PEcAn settings object |
var.names |
var.names to be extracted |
params |
passed on to return value |
X_tmp vector of forecasts
Istem Fer, Yinghao Sun
## Not run: settings <- PEcAn.settings::read.settings("pecan.xml") params <- list() rx <- read_restart.LPJGUESS( outdir = "/projectnb/…/LPJ_output", runid = "123456", stop.time = as.POSIXct("2001-12-31 23:59:59", tz = "UTC"), settings = settings, var.names = c("AGB.pft"), params = params) ## End(Not run)## Not run: settings <- PEcAn.settings::read.settings("pecan.xml") params <- list() rx <- read_restart.LPJGUESS( outdir = "/projectnb/…/LPJ_output", runid = "123456", stop.time = as.POSIXct("2001-12-31 23:59:59", tz = "UTC"), settings = settings, var.names = c("AGB.pft"), params = params) ## End(Not run)
Reads a state file and processes its contents for further use.
read_state(file_path)read_state(file_path)
file_path |
A character string specifying the path to the state file. |
A list containing the processed state information.
read binary state file of LPJ-GUESS
readStateBinary(out.path, npft)readStateBinary(out.path, npft)
out.path |
location on disk where model run outputs are stored |
npft |
number of pfts specified in instruction file |
Patchpft_list state variables common to all individuals of a particular PFT
Istem Fer
Splits climate met for LPJGUESS
split_inputs.LPJGUESS( settings, start.time, stop.time, inputs, overwrite = FALSE, outpath = NULL )split_inputs.LPJGUESS( settings, start.time, stop.time, inputs, overwrite = FALSE, outpath = NULL )
settings |
PEcAn settings object |
start.time |
start date and time for each SDA ensemble |
stop.time |
stop date and time for each SDA ensemble |
inputs |
list of model inputs to use in write.configs.LPJGUESS |
overwrite |
Default FALSE |
outpath |
if specified, write output to a new directory. Default NULL writes back to the directory being read |
name of the split met file
Istem Fer
Adjust LPJ-GUESS state variables based on input parameters by nudging density ONLY, with a robust bisection fallback to ensure physical viability.
update_state_both_LPJGUESS( model.state, pft.params, dens.initial, dens.target, AbvGrndWood.initial, AbvGrndWood.target, AbvGrndWood.epsilon, trace, min.diam, HEIGHT_MAX = 150 )update_state_both_LPJGUESS( model.state, pft.params, dens.initial, dens.target, AbvGrndWood.initial, AbvGrndWood.target, AbvGrndWood.epsilon, trace, min.diam, HEIGHT_MAX = 150 )
model.state |
A large multiply-nested list containing the entire LPJ-GUESS state as read by
function |
pft.params |
A data.frame containing the parameters for each PFT. Each row represents one PFT (ordering must be consistent with the vectors below. The names of the columns describe the per-PFT parameter and must include: wooddens, crownarea_max, lifeform (1 = tree, 2 = grass), k_latosa, k_rp, k_allom1, k_allom2, k_allom3, crownarea_max and sla. |
dens.initial |
A numeric vector of the initial stand-level stem densities (indiv/m^2) as named numeric vector with one entry per PFT/species, with the names being the PFT/species codes. |
dens.target |
A numeric vector of the target stand-level stem densities (indiv/m^2) as named numeric vector with one entry per PFT/species, with the names being the PFT/species codes. |
AbvGrndWood.initial |
A numeric vector of the initial stand-level above ground wood (kgC/m^2) as named numeric vector with one entry per PFT/species, with the names being the PFT/species codes. |
AbvGrndWood.target |
A numeric vector of the target stand-level above ground wood (kgC/m^2) as named numeric vector with one entry per PFT/species, with the names being the PFT/species codes. |
AbvGrndWood.epsilon |
A single numeric specifying how close the final above ground wood needs to be to the target above ground stem biomass for each individual. eg. 0.05 requires that the final above ground wood is within 5 of the target above ground wood |
trace |
Logical; if TRUE, prints detailed adjustment process information. |
min.diam |
Minimum tree diameter (in cm) for inclusion in adjustments. |
HEIGHT_MAX |
Maximum allowed height of an individual. This is the maximum height that a tree can have. This is hard-coded in LPJ-GUESS to 150 m, but for SDA that might be unrealistically big, so this argument allows adjustment. |
Adjust LPJ-GUESS state (both biomass and density)
And updated model state (as a big old list o' lists)
Yinghao Sun
Adjust LPJ-GUESS state variables based on input parameters.
update_state_LPJGUESS( model.state, pft.params, dens.initial, dens.target, AbvGrndWood.initial, AbvGrndWood.target, AbvGrndWood.epsilon, trace, min.diam, HEIGHT_MAX = 150 )update_state_LPJGUESS( model.state, pft.params, dens.initial, dens.target, AbvGrndWood.initial, AbvGrndWood.target, AbvGrndWood.epsilon, trace, min.diam, HEIGHT_MAX = 150 )
model.state |
A large multiply-nested list containing the entire LPJ-GUESS state as read by
function |
pft.params |
A data.frame containing the parameters for each PFT. Each row represents one PFT (ordering must be consistent with the vectors below. The names of the columns describe the per-PFT parameter and must include: wooddens, crownarea_max, lifeform (1 = tree, 2 = grass), k_latosa, k_rp, k_allom1, k_allom2, k_allom3, crownarea_max and sla. wooddens, crownarea_max, lifeform (1 = tree, 2 = grass), k_latosa, k_rp, k_allom1, k_allom2, k_allom3, crownarea_max and sla. |
dens.initial |
A numeric vector of the initial stand-level stem densities (indiv/m^2) as named numeric vector with one entry per PFT/species, with the names being the PFT/species codes. These values should be produced using state data assimilation from function XXXXXX. |
dens.target |
A numeric vector of the target stand-level stem densities (indiv/m^2) as named numeric vector with one entry per PFT/species, with the names being the PFT/species codes. These values should be produced using state data assimilation from function XXXXXX |
AbvGrndWood.initial |
A numeric vector of the target stand-level above ground wood (kgC/m^2) as named numeric vector with one entry per PFT/species, with the names being the PFT/species codes. These values should be produced using state data assimilation from function XXXXXX |
AbvGrndWood.target |
A numeric vector of the target stand-level above ground wood (kgC/m^2) as named numeric vector with one entry per PFT/species, with the names being the PFT/species codes. These values should be produced using state data assimilation from function XXXXXX |
AbvGrndWood.epsilon |
A single numeric specifying how close the final above ground wood needs to be to the target above ground stem biomass for each individual. eg. 0.05 requires that the final above ground wood is within 5 of the target above ground wood |
trace |
Logical; if TRUE, prints detailed adjustment process information. |
min.diam |
Minimum tree diameter (in cm) for inclusion in adjustments. |
HEIGHT_MAX |
Maximum allowed height of an individual. This is the maximum height that a tree can have. This is hard-coded in LPJ-GUESS to 150 m, but for SDA that might be unrealistically big, so this argument allows adjustment. |
Adjust LPJ-GUESS state
And updated model state (as a big old list o' lists)
Matthew Forrest, Yinghao Sun
Write updated variables into a copy of the original LPJ-GUESS .state file
write_binary_LPJGUESS(State_updated, outdir)write_binary_LPJGUESS(State_updated, outdir)
State_updated |
A list containing updated state variables, position list and size list (get from read_binary) |
outdir |
Path to a directory containing the '0.state' and 'meta.bin' files. |
No return value. Writes files to disk as side effect.
Yinghao Sun
A robust writer for LPJ-GUESS '0.state' that supports changes in the number of cohorts/individuals (i.e., variable-length Individuals blocks). When no cohort count changes are detected, it can fall back to a fast in-place writer (e.g., your existing 'write_binary_LPJGUESS()' that uses stored offsets).
write_binary_LPJGUESS_flexible( State_updated, outdir, use_fast_inplace_if_possible = TRUE, verbose = FALSE )write_binary_LPJGUESS_flexible( State_updated, outdir, use_fast_inplace_if_possible = TRUE, verbose = FALSE )
State_updated |
A list containing: - 'state': updated Gridcell object (parsed state tree) - 'pos_list': named list/vector of byte offsets for each key - 'siz_list': named list/vector of byte sizes per element for each key |
outdir |
Character scalar. Directory containing '0.state' and 'meta.bin'. |
use_fast_inplace_if_possible |
Logical. If 'TRUE', uses the existing in-place writer when no 'number_of_individuals' changes are detected. |
verbose |
Logical. If 'TRUE', prints minimal progress messages. |
If cohort count changes are detected, this function rebuilds a new '0.state' by streaming-replay: it copies unchanged raw bytes from the original state, writes updated fields, and fully rewrites the Individuals blocks for affected stand/patches so downstream offsets remain correct.
Invisibly returns 'TRUE' on success. Side effect: - Creates 'bak.state' as a backup of the original '0.state' - Writes a new '0.state' (possibly via '0.state.tmp' and rename)
Yinghao Sun
Write restart files for LPJGUESS new.state includes X (AGB.pft) from Analysis new.params includes LPJGUESS_state
write_restart.LPJGUESS( outdir, runid, start.time, stop.time, settings, new.state, new.params, inputs = NULL, RENAME = TRUE, verbose = FALSE )write_restart.LPJGUESS( outdir, runid, start.time, stop.time, settings, new.state, new.params, inputs = NULL, RENAME = TRUE, verbose = FALSE )
outdir |
output directory |
runid |
run ID |
start.time |
start date and time for each SDA ensemble |
stop.time |
stop date and time for each SDA ensemble |
settings |
PEcAn settings object |
new.state |
analysis state vector |
new.params |
list of parameters to convert between different states |
inputs |
list of model inputs to use in write.configs.LPJGUESS |
RENAME |
flag to either rename output file or not |
verbose |
decide if we want to print the runid |
NONE
Yinghao Sun
Writes a LPJ-GUESS config file.
write.config.LPJGUESS(defaults, trait.values, settings, run.id, restart = NULL)write.config.LPJGUESS(defaults, trait.values, settings, run.id, restart = NULL)
defaults |
list of defaults to process |
trait.values |
vector of samples for a given trait |
settings |
list of settings from pecan settings file |
run.id |
id of run |
restart |
Logical, whether to restart the simulation. |
Requires a pft xml object, a list of trait values for a single model run, and the name of the file to create
configuration file for LPJ-GUESS for given run
Istem Fer, Tony Gardella
Write LPJ-GUESS instruction script
write.insfile.LPJGUESS( settings, trait.values, rundir, outdir, run.id, restart = NULL )write.insfile.LPJGUESS( settings, trait.values, rundir, outdir, run.id, restart = NULL )
settings |
PEcAn settings list |
trait.values |
trait.values |
rundir |
rundir |
outdir |
outdir |
run.id |
PEcAn run ID |
restart |
A list object passed from the SDA workflow containing run-specific restart information, or NULL for initial runs. |
settings Updated list
Istem Fer, Yinghao Sun