BioCro (version 3.3.0)

module_write: 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
  )

Value

A string containing a new BioCro module header file.

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.

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)

if (FALSE) {
  # Use writeLines to save as a `.h` file
  writeLines(out, "./testmod.h")
}

# 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

if (FALSE) {
  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')
}