sim.single_run: Run a single isotope box-model simulation

In isobxr: Stable Isotope Box Modelling in R

Run a single isotope box-model simulation

Description

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.

Usage

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

## Not run: 
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)

## End(Not run)

isobxr documentation built on Aug. 23, 2023, 5:06 p.m.