SINDBAD Helper Functions

This document provides an overview of useful helper functions in the SINDBAD framework.

Data Management Functions

getSindbadDataDepot

getSindbadDataDepot(; env_data_depot_var="SINDBAD_DATA_DEPOT", local_data_depot="../data")

Retrieves the path to the SINDBAD data depot, which is used for storing and accessing data files.

Arguments

• env_data_depot_var: Environment variable name for the data depot (default: "SINDBAD_DATA_DEPOT")

• local_data_depot: Local path to the data depot (default: "../data")

Returns The path to the SINDBAD data depot, determined by:

1. First checking the environment variable specified by env_data_depot_var

2. If not found, falling back to the local_data_depot path

Usage

# Get the data depot path
data_path = getSindbadDataDepot()

# Use custom environment variable
data_path = getSindbadDataDepot(env_data_depot_var="CUSTOM_DATA_DEPOT")

# Use custom local path
data_path = getSindbadDataDepot(local_data_depot="path/to/data")

TIP

SINDBAD uses getSindbadDataDepot to convert relative data paths to absolute data path. In case of sharing data directory across experiments, set the environment variable SINDBAD_DATA_DEPOT. In UNIX-like systems, add the following in .bashrc/SHELL settings.

export SINDBAD_DATA_DEPOT="/Path/To/A/DIRECTORY"

Variable Information Functions

getVariableInfo

getVariableInfo(vari_b::Symbol, t_step="day")
getVariableInfo(vari_b, t_step="day")

Retrieves detailed information about a SINDBAD variable from the variable catalog.

Arguments

• vari_b: The variable name (either as a Symbol or in the form of field__subfield)

• t_step: Time step of the variable (default: "day")

Returns A dictionary containing the following information about the variable:

• standard_name: The standard name of the variable

• long_name: A longer description of the variable

• units: The units of the variable (with time step replaced if applicable)

• land_field: The field in the SINDBAD model where the variable is used

• description: A detailed description of the variable

Usage

# Get information about a variable
var_info = getVariableInfo(:fluxes__gpp)

# Get information with custom time step
var_info = getVariableInfo(:fluxes__gpp, "hour")

whatIs

whatIs(var_name::String)
whatIs(var_field::String, var_sfield::String)
whatIs(var_field::Symbol, var_sfield::Symbol)
whatIs(var_name::Symbol)

A helper function to display information about a SINDBAD variable from the variable catalog.

Arguments

• var_name: The full variable name (e.g., "land.fluxes.gpp" or "fluxes__gpp")

• var_field: The field name of the variable (e.g., "fluxes")

• var_sfield: The subfield name of the variable (e.g., "gpp")

Behavior

• Checks if the variable exists in the SINDBAD variable catalog

• If the variable exists, displays its complete information

• If the variable doesn't exist, displays a template for adding it to the catalog

• Automatically handles different input formats (String or Symbol)

Usage

# Using full variable name
whatIs("land.fluxes.gpp")
whatIs(:fluxes__gpp)

# Using field and subfield separately
whatIs("fluxes", "gpp")
whatIs(:fluxes, :gpp)

TIP

When Sindbad is imported, sindbad_variables with all the variables in the catalog is available automatically.

whatIs is particularly useful for:

• Quickly looking up variable information during development

• Checking if a variable is properly documented in the catalog

• Getting a template for adding new variables to the catalog

• Understanding the structure and naming conventions of SINDBAD variables

Model Parameter Functions

modelParameter

modelParameter(models, model::Symbol)
modelParameter(model::LandEcosystem, show=true)

Returns and optionally displays the current parameters of a given SINDBAD model.

Arguments

• models: A list/collection of SINDBAD models (required when model is a Symbol)

• model::Symbol: A SINDBAD model name

• model::LandEcosystem: A SINDBAD model instance of type LandEcosystem

• show::Bool: Flag to print parameters to the screen (default: true)

Returns

• For model::LandEcosystem: A vector of parameter information pairs

• For model::Symbol: An OrderedDict containing parameter names and values

Usage

# get models from info
selected_models = info.models.forward
# Display parameters of a specific model
modelParameter(selected_models, :gpp)

modelParameters

modelParameters(selected_models)

Displays the current parameters of all given SINDBAD models.

Arguments

• models: A list/collection of SINDBAD models

Usage

# Display parameters of all models
modelParameters(selected_models)

Configuration Functions

sindbadDefaultOptions

sindbadDefaultOptions(::MethodType)

Retrieves the default configuration options for optimization or sensitivity analysis methods in SINDBAD.

Arguments

• ::MethodType: The method type for which default options are requested. Supported types:

  • OptimizationMethod: General optimization methods

  • GSAMethod: General global sensitivity analysis methods

  • GSAMorris: Morris method for global sensitivity analysis

  • GSASobol: Sobol method for global sensitivity analysis

  • GSASobolDM: Sobol method with derivative-based measures

  • CMAEvolutionStrategyCMAES: CMA-ES optimization method

Returns A NamedTuple containing the default options for the specified method.

Default Options by Method

• GSAMorris:

  • total_num_trajectory = 200

  • num_trajectory = 15

  • len_design_mat = 10

• GSASobol:

  • samples = 5

  • method_options = (order=[0, 1])

  • sampler = "Sobol"

  • sampler_options = ()

• CMAEvolutionStrategyCMAES:

  • maxfevals = 50

Usage

# Get default options for Morris method
opts = sindbadDefaultOptions(GSAMorris())

# Get default options for Sobol method
opts = sindbadDefaultOptions(GSASobol())

Model and Definition Functions

getSindbadModels

getSindbadModels()

Retrieves a dictionary of SINDBAD models and their approaches.

Returns A dictionary containing:

• Keys: Model names as symbols

• Values: Corresponding model approaches and implementations

Usage

# Get all SINDBAD models and their approaches
models = getSindbadModels()

TIP

getSindbadModels is particularly useful for:

• Discovering available models in standard_sindbad_models in the SINDBAD framework

getSindbadDefinitions

getSindbadDefinitions(sindbad_module, what_to_get; internal_only=true)

Returns all defined (and optionally internal) objects in the SINDBAD framework.

Arguments

• sindbad_module: The module to search for defined things

• what_to_get: The type of things to get (e.g., Type, Function)

• internal_only: Whether to only include internal definitions (default: true)

Returns An array of all defined things in the SINDBAD framework that match the specified type.

Usage

# Get all defined types in the SINDBAD framework
defined_types = getSindbadDefinitions(Sindbad, Type)

# Get all functions in a specific module
functions = getSindbadDefinitions(Sindbad.Models, Function)

# Get all definitions including external ones
all_definitions = getSindbadDefinitions(Sindbad, Any, internal_only=false)

TIP

getSindbadDefinitions is particularly useful for:

• Discovering available types and functions in SINDBAD modules

• Understanding the structure of SINDBAD's codebase

• Accessing internal implementations for debugging or development

Model Input-Output Functions

getInoutModels

This function extracts the input-output structure of models for a specified function (e.g., :compute, :precompute). It is useful for analyzing the dependencies and outputs of models in SINDBAD experiments.

getInoutModels(info::NamedTuple, which_function::Symbol=:compute)

Retrieves the input-output (IO) model structure for a specific function in the SINDBAD framework.

Arguments

• info::NamedTuple: A NamedTuple containing experiment information, including model configurations and metadata.

• which_function::Symbol: The function for which the IO structure is retrieved (default: :compute).

Returns A dictionary where:

• Keys are model names (as symbols).

• Values are dictionaries containing :input and :output fields, each listing the variables associated with the model.

Usage

# Retrieve IO structure for compute function
io_structure = getInoutModels(experiment_info, :compute)

Package Management Functions

addPackage

addPackage(where_to_add, the_package_to_add)

Adds a specified Julia package to the environment of a given module or project.

Arguments

• where_to_add: The module or project where the package should be added.

• the_package_to_add: The name of the package to add.

Behavior

• Activates the environment of the specified module or project.

• Checks if the package is already installed in the environment.

• If the package is not installed:

  • Adds the package to the environment.

  • Removes the Manifest.toml file and reinstantiates the environment to ensure consistency.

  • Provides instructions for importing the package in the module.

• Restores the original environment after the operation.

Usage

Add the DataFrames package to SindbadData module

addPackage(SindbadData, "DataFrames")

Notes

• This function assumes that the where_to_add module or project is structured with a standard Julia project layout.

• It requires the Pkg module for package management, which is re-exported from the core SINDBAD framework.