module_write: Generate a BioCro module header file.

In BioCro: Modular Crop Growth Simulations

Generate a BioCro module header file.

Description

To facilitate the creation of new BioCro modules, module_write generates a BioCro module header file. Given a set of input and output variables, module_write will create a C++ header file ('.h' file) by filling in a template with the input and output variables, ensuring the correct C++ syntax for a BioCro module.

Usage

  module_write(
    module_name,
    module_library,
    module_type,
    inputs,
    outputs,
    output_equations = NULL,
    input_units = NULL,
    output_units = NULL
  )

Arguments

module_name	A string for the module's name.
module_library	A string for the module's library namespace. E.g., 'biocro'.
module_type	A string setting the module type: 'direct' or 'differential'.
inputs	A character vector of the module's input variables.
outputs	A character vector of the module's output variables.
output_equations	A character vector. The module's output variables will be updated with these variables. If NULL, a zero is inserted instead.
input_units	A character vector of the inputs' units. If NULL, no units are embedded.
output_units	A character vector of the outputs' units. If NULL, no units are embedded.

Details

type should be either 'direct' or 'differential'; however, module_write does not enforce this in case new module types are created in the future.

Value

A string containing a new BioCro module header file.

Note

This function returns a string and has no file I/O. Use writeLines to print the output to console, or to save the output. See examples below. Note that it is customary to name the header file with the same name as the module.

module_write checks for duplicate input or output variables, and if detected, it will raise an error. In theory, this check should ensure that the generated module will compile correctly. However, it is still possible to define an module that is circular and will not pass the checks in validate_dynamical_system_inputs. See ⁠Example 4⁠.

Examples

# Example 1
# Inputs as character vector
xs = c('x1','x2','x3')

# Units
xs_units <- c('Mg / ha', 'Mg / ha / hr', 'dimensionless')

# Outputs
ys = c('y1','y2')

out <- module_write('testmod', 'testlib', 'direct',
    inputs=xs, input_units= xs_units, outputs=ys)

# Use writeLines to print to console
writeLines(out)

## Not run: 
  # Use writeLines to save as a `.h` file
  writeLines(out, "./testmod.h")

## End(Not run)

# Example 2: A differential module
xs <- c('var_1','var_2')
out <- module_write('testmod', 'testlib', 'differential', xs, xs)
writeLines(out)

# Example 3: A module with pairwise names
# Here we use an outer product to generate pairwise combinations of
# tissues and pool types
tissues <- c('leaf', 'stem', 'root')
pools <- c('carbon', 'nitrogen')
xs <- as.vector(outer(tissues, pools, paste, sep = '_'))
out <- module_write('testmod', 'testlib', 'differential', xs, xs)
writeLines(out)

# Example 4: Circular modules

## Not run: 
  out <- module_write(inputs = c('x' ,'x'))

  # Will compile, but will cause a "circular quantities" error if it is used
  # in a BioCro simulation:
  out <- module_write('inconsistent', 'examplelib', type='direct',
          inputs = 'x', outputs = 'x')

## End(Not run)

BioCro documentation built on April 4, 2025, 2:36 a.m.