File Name and Location

• The sweep dyn master file is an xlsx file.
  
• The sweep dyn master file name is chosen by user and specified in the sweep_dyn function inputs: [e.g., 0_SWEEP_DYN_MASTER.xlsx ].
  
• the sweep dyn master file should be stored in the directory in which isobxr master file is found, where all runs for this box model system will be performed and where all outputs will be stored in automatically created subdirectories. This directory corresponds to the working directory (workdir) used as parameter of the sweep_dyn function.

File structure

The sweep dyn master file contains the 5 following sheet strictly named as follows:

1. RUN_LIST: define the list of 2 runs composing the sweep dyn scenario (run durations, run resolutions, lists of fluxes, lists of coefficients).
   
2. FORCING_RAYLEIGH: define Rayleigh forcings over one or several runs composing the sweep 2 steps scenario.
   
3. FORCING_ALPHA: define Rayleigh forcings over one or several runs composing the sweep 2 steps scenario.
   
4. FORCING_DELTA: define initial delta forcings over one or several runs composing the sweep 2 steps scenario.
   
5. FORCING_SIZE: define initial box size forcings over one or several runs composing the sweep 2 steps scenario.

RUN_LIST sheet (REQUIRED)

The sweep_dyn function strictly requires a list of 2 successive runs.

Both of these runs should be successively described one by one on two rows of this sheet, with notably:

1. the run number (COMPO_RUN_n column)
   
2. the run duration (t_lim_list column)
   
3. the run resolution (nb_steps_list)
   
4. the flux list name (flux_list) that will be read from isobxr master file
   
5. the coefficients list name (coeff_list) that will be read from isobxr master file

FORCING_SIZE sheet (OPT)

See composite master file format description for details.

FORCING_DELTA sheet (OPT)

See composite master file format description for details.

FORCING_ALPHA sheet (OPT)

See composite master file format description for details.

FORCING_RAYLEIGH sheet (OPT)

See composite master file format description for details.

Preparing sweep dyn master

The user needs to define the two runs composing the 2 steps scenario.

1. The first run is typically used to let the system relax to its steady state used as an initial state in run #2.
   1. The user should consider here a balanced system. The isobxr functions will thus use the analytical solver (ana_slvr).
   2. We thus recommend the user to set the number of steps for run #1 (nb_steps) to 1 (its' minimum value).
      This allows to only calculate the final state of the system, at the end of run #1.
      This reduces the calculation time and data produced without affecting the accuracy of the calculation.
2. The second run is used to explore the dynamic response of the system in the face of a given perturbation, as a function of all combinations of parameters #1 and #2 values.
   1. The main purpose of this function is to explore the influence of the 2 combined parameters over the time dependent response of a system that previously relaxed to it's steady state.
   2. The user has the choice to define a balanced or an unbalanced system in the run #2. A. The latter case (unbalanced system) could here constitute the perturbation of the system. The sweep_dyn function will here numerically solve the run #2 (num_slvr). A. In the case of a balanced system for run #2, the sweep_dyn function will analytically solve the run #2 (ana_slvr). A. The user should here be aware that the sweeping of the space of parameters using either the num_slvr or ana_slvr can be time consuming and require a fair bit of calculating power.
      The user is advised to wisely define the space of parameters (which will define the number of \(n \times m\) iterations) as well as the run resolution of run #2 (nb_steps).

remark

The reason why the sweep_dyn function sweeps both initial run #1 and run #2 is that the user might want to sweep parameters that are actually affecting the steady state of the system (e.g., sweep a series of lists of fluxes or coefficients).

Forcings

The user can define some forcings over the system (will affect both run #1 and run #2).
These forcings will overwrite the conditions set by the reading of the isobxr master file.
These forcings will be overwritten by the swept parameters that affect run #1 and #2.

Required arguments

In addition to all the usual input parameters required for the sweep_dyn function, the user has to define the two parameters to be swept.

There are 6 types of sweepable parameters (or that can be explored), which names are strictly defined as follows:

#> [1] "EXPLO_n_FLUX_MATRICES"
#> [1] "EXPLO_n_ALPHA_MATRICES"
#> [1] "EXPLO_1_SIZE"
#> [1] "EXPLO_1_DELTA"
#> [1] "EXPLO_1_ALPHA"
#> [1] "EXPLO_1_RAYLEIGH_ALPHA"

data.frame(VALUES_1 = c("flux_list_1",  # RUN #1 vector of n strings of chars.
                        "...", 
                        "flux_list_i", 
                        "...", 
                        "flux_list_n"),  
           VALUES_2 = c("flux_list_1",  # RUN #2 vector of n strings of chars.
                        "...", 
                        "flux_list_i", 
                        "...", 
                        "flux_list_n"),  
           EXPLO_TYPES = "EXPLO_n_FLUX_MATRICES") # stricly leave as such

data.frame(VALUES_1 = c("coeff_list_1", # RUN #1 vector of n strings of chars.
                        "...", 
                        "coeff_list_i", 
                        "...", 
                        "coeff_list_n"), 
           VALUES_2 = c("coeff_list_1", # RUN #2 vector of n strings of chars.
                        "...", 
                        "coeff_list_i", 
                        "...", 
                        "coeff_list_n"), 
           EXPLO_TYPES = "EXPLO_n_ALPHA_MATRICES") # stricly leave as such

data.frame(BOXES_ID = "BOX_i", # 1 string of char
           SIZE_MIN = "min_sweep_value", # 1 numerical value
           SIZE_MAX = "max_sweep_value", # 1 numerical value
           SIZE_STEPS = "sweep_steps", # 1 numerical value
           EXPLO_TYPES = "EXPLO_1_SIZE") # stricly leave as such

data.frame(BOXES_ID = "BOX_i", # 1 string of char
           DELTA_MIN = "min_sweep_value", # 1 numerical value
           DELTA_MAX = "max_sweep_value", # 1 numerical value
           DELTA_STEPS = "sweep_steps", # 1 numerical value
           EXPLO_TYPES = "EXPLO_1_DELTA") # stricly leave as such

data.frame(FROM = "BOX_i", # 1 string of char
           TO = "BOX_j", # 1 string of char
           ALPHA_MIN = "min_sweep_value", # 1 numerical value
           ALPHA_MAX = "max_sweep_value", # 1 numerical value
           ALPHA_STEPS = "sweep_steps", # 1 numerical value
           EXPLO_TYPES = "EXPLO_1_ALPHA") # stricly leave as such

data.frame(XFROM = "Box_B", # B>C flux at numerator (strings of char)
           XTO = "Box_C",
           YFROM = "Box_A", # A>B flux at denominator (strings of char)
           YTO = "Box_B",
           AFROM = "Box_B", # resulting fract. coefficient (strings of char)
           ATO = "Box_C",
           ALPHA_0_MIN = "min_sweep_value", # value of incremental B>A coeff. (num.)
           ALPHA_0_MAX = "max_sweep_value", 
           ALPHA_0_STEPS = "sweep_steps",
           EXPLO_TYPES = "EXPLO_1_RAYLEIGH_ALPHA") # stricly leave as such

Default and optional outputs

By default, the sweep_dyn prints in the R session a series of default time evolution plots of the delta values of each system finite boxes in the 2D space of parameters.

All sweep_dyn output data is stored in a temporary directory by default.

The user can save these outputs to their working directory by changing the save_run_outputs argument to TRUE.

The sweep_dyn outputs are structured as as shown in the full package documentation..

Plotting sweep_dyn outputs

By default, the sweep_dyn prints in the R session a series of default heatmap plots of the delta values of each system finite boxes at the final state of the run in the 2D space of parameters.

The outputs of the sweep_dyn can be plotted using the shinobxr_app function.

The shinobxr_app function launches an interactive html app allowing to edit and export graphical representation of the model runs.

The shinobxr_app requires the user to save the sweep_dyn output files to a local working directory (by setting the argument save_run_outputs = TRUE).

More on the use of the shinobxr_app function can be found on the Shiny app page.