Run a single isotope box-model simulation

Source: R/sim_single_run.R

A function to run the isobxr stable isotope box model, assessing the design of the model and automatically running solve_numerically or solve_analytically depending on system design.

sim.single_run(
  workdir,
  SERIES_ID,
  flux_list,
  coeff_list,
  t_max,
  n_steps,
  isobxr_master_file = "0_ISOBXR_MASTER",
  suppress_messages = FALSE,
  export.diagrams = FALSE,
  export.delta_plot = FALSE,
  export.data_as_csv_xlsx = FALSE,
  plot.time_as_log10 = TRUE,
  plot.time_unit = NULL,
  show.delta_plot = TRUE,
  inspect_inputs = TRUE,
  save_outputs = FALSE,
  return_data = FALSE,
  solver = "auto",
  n_zeros_RUN_IDs = 4,
  FORCING_RAYLEIGH = NULL,
  FORCING_SIZE = NULL,
  FORCING_DELTA = NULL,
  FORCING_ALPHA = NULL,
  COMPOSITE = FALSE,
  COMPO_SERIES_n = NaN,
  COMPO_SERIES_FAMILY = NaN,
  EXPLORER = FALSE,
  EXPLO_SERIES_n = NaN,
  EXPLO_SERIES_FAMILY = NaN,
  isobxr_master = NULL,
  diagram_pdf.widh_height = NULL
)

Arguments

workdir

Working directory of isobxr excel master file and where output files will be stored if exported by user. (character string)

SERIES_ID

Name of the series the run belongs to.
It determines the folder in which the output files will be stored inside workdir.
(character string)

flux_list

Name of the list of fluxes and initial box sizes to be used for the run,
calling (by its header name) a single column of the FLUXES sheet of the isobxr excel master file.
(character string)

coeff_list

Name of the list of fractionation coefficients to be used for the run,
calling (by its header name) a single column of the COEFFS sheet of the isobxr excel master file.
(character string)

t_max

Run duration, given in the same time units as unit declared in CONSTANTS
spreadsheet of isobxr excel master file in the TIME_UNIT column. (integer)

n_steps

Number of calculation steps.
It determines the resolution of the run.
(integer)

isobxr_master_file

Name of isobxr excel master file.
Default is "0_ISOBXR_MASTER".

suppress_messages

If TRUE, hides all information and warning messages regarding run.
Default is FALSE.

export.diagrams

If TRUE, exports box-model flux and fractionation diagrams as pdf.
Default is FALSE.

export.delta_plot

If TRUE, exports delta and size time evolution plots of the evolution of the system, as pdf.
Default is FALSE.

export.data_as_csv_xlsx

If TRUE, exports all results and run conditions as csv and xlsx files,
to DIGEST directory.
Default is FALSE.

plot.time_as_log10

If TRUE, uses logarithmic time scale in plot.
Default is FALSE.

plot.time_unit

Time unit to use on plot if different from native time unit.
Character string, to be selected among the following:
micros, ms, s, min, h, d, wk, mo, yr, kyr, Myr, Gyr
Default is NULL.

show.delta_plot

If TRUE, prints delta and size time evolution plots in R. Default is TRUE.

inspect_inputs

If TRUE, inspects and proof checks format of input taken from isobxr excel master file.
(Inspection run by read.isobxr_master function.)
Default is TRUE.

save_outputs

If TRUE, saves all run outputs to local working directory (workdir).
By default, run outputs are stored in a temporary directory and erased if not saved.
Default is FALSE.

return_data

If TRUE, returns all data (inputs and outputs) as a list.
Default is FALSE.

solver

Determines what solver to used: "analytical" or "numerical".
Default is "auto" for automatic selection of adapted solver. Note that this option returns warnings or prevents user to run when solver wished is not adapted to system solution.

n_zeros_RUN_IDs

Number of figures used in iteration of RUNs of a given series (SERIES_ID).
Default is 4: the run IDs of a given series range between 0001 and 9999.

FORCING_RAYLEIGH

OPTIONAL
Dataframe describing the forcing on a fractionation coefficient by a Rayleigh isotope distillation,
as a function of flux intensities and a fundamental fractionation coefficient.
Dataframe formatting details are in isobxr vignette.
Default is NULL.

FORCING_SIZE

OPTIONAL
Dataframe describing the forcing on one or several box sizes (mass of element X).
The newly defined sizes for the given set of boxes overwrite their sizes as previously defined in isobxr excel master file.
Dataframe formatting details are in isobxr vignette.
Default is NULL.

FORCING_DELTA

OPTIONAL
Dataframe describing the forcing on one or several boxes initial isotope composition expressed as delta values.
The newly defined delta values for the given set of boxes overwrite the delta values as previously defined in isobxr excel master file.
Dataframe formatting details are in isobxr vignette.
Default is NULL.

FORCING_ALPHA

OPTIONAL
Dataframe describing the forcing on one or several fractionation coefficients from one reservoir to another.
The newly defined alpha values for the given set of boxes overwrite the alpha values as previously defined in isobxr excel master file.
Dataframe formatting details are in isobxr vignette.
Default is NULL.

COMPOSITE

NOT TO BE USED IN SINGLE RUN
Logical value automatically defined in sim.scenario.
Default is FALSE.

COMPO_SERIES_n

NOT TO BE USED IN SINGLE RUN
Iteration of the composite run for the given series it belongs to, automatically defined in sim.scenario.
Default is NaN.

COMPO_SERIES_FAMILY

NOT TO BE USED IN SINGLE RUN
Composite run series family, automatically defined in sim.scenario.
Default is NaN.

EXPLORER

NOT TO BE USED IN SINGLE RUN
Logical value automatically defined in sweep.final_nD or sweep.dyn_2D.
Default is FALSE.

EXPLO_SERIES_n

NOT TO BE USED IN SINGLE RUN
Iteration of the sweep run for the given series it belongs to, automatically defined in sweep.final_nD or sweep.dyn_2D.
Default is NaN.

EXPLO_SERIES_FAMILY

NOT TO BE USED IN SINGLE RUN
Sweep run series family, automatically defined in sweep.final_nD or sweep.dyn_2D.
Default is NaN.

isobxr_master

isobxr_master list of input dataframes formatted by read.isobxr_master
Overwrites isobxr_master_file. Default is NULL.

diagram_pdf.widh_height

Vector of width and height in inches of the pdf diagrams.

Value

A results data set as a list containing the following components:

  1. inputs input data:

    1. CONSTS data frame of all run specific constants.

    2. INITIAL data frame of delta and sizes at t = 0 in all boxes.

    3. FLUXES data frame of all fluxes intensities (row ID: FROM / col ID: TO)

    4. COEFFS data frame of all fractionation coefficient values (row ID: FROM / col ID: TO)

    5. BOX_META data frame of box specific metadata (e.g., flux balance, residence times, layout position )

    6. bx.groups list of box names grouped by relevant categories (e.g., disconnected boxes, infinite boxes)

    7. LOG data frame of run specific LOG excerpt.

  2. outputs output data:

    1. solver

    2. final_state

    3. delta_vs_t

    4. size_vs_t

    5. for analytical solutions

      1. diffeq_solutions solutions of differential equations,
        including relaxation times, eigenvalues, constants, eigenvectors

  3. paths list of run specific paths

Examples

if (FALSE) {
sim.single_run(workdir = "/Users/username/Documents/1_ABC_tutorial",
               SERIES_ID = "1_ABC_balanced_closed",
               flux_list = "Fx1_ABC_bal",
               coeff_list = "a1",
               t_max = 2500,
               n_steps = 2500)
}