Extract the values of all the state variables at the end of a model run and format for use as new initial conditions.

The function saves the state of the model at the end of a run (using the e2e_run() function) for use as initial conditions in future runs. This enables, for example, the model to be run for a long time to attain a stationary state, and then restarted in that state.

Usage

e2e_extract_start(model, results, csv.output = TRUE)

Arguments

model: R-list object defining the model configuration compiled by the e2e_read() function.
results: R-list object generated by the e2e_run() function.
csv.output: Logical. If TRUE then enable writing of csv output files (default=FALSE).

Value

Table of state variable values from the end of a run formatted as required for input to a new model run as initial conditions. By selecting csv.output=TRUE these data are also returned as a csv file to the Param folder of the current model, unless this is one of the North Sea model versions within the package.

Details

Initial conditions for a model run are held in the /Param folder of the Model/Variant path specified in the e2e_read() function call used to define a run. By default, the function attampts to write the model end-state file back to this /Param folder. However, the package folders are read-only so if e2e_read() has been specified to load an internally provided Model/Variant then the output will revert to the currently specified results folder instead. To fix this, copy the required package model to a user workspace using the e2e_copy() function and re-run.

The new initial conditions file will have a name initial_values-*.csv, where * is the model.ident text identifier specified in e2e_read() To source the new initial conditions in a subsequent model run, edit the MODEL_SETUP.csv file in the required /Models/Variant folder

Examples

# Example which generates an initial values object from an internal North Sea model but
# does not attempt to save it back to the Parameters folder of the model setup. Just
# run for 1 year in this example:
    model <- e2e_read("North_Sea", "2003-2013")
#> Current working directory is... 
#> 'C:/Users/jackl/OneDrive - University of Strathclyde/Documents/Research/Packages/StrathE2E/strathe2e2/docs/reference'
#> No 'results.path' specified so any csv data requested
#> will be directed to/from the temporary directory...
#> 'C:\Users\jackl\AppData\Local\Temp\RtmpYdRhoX'
#> 
#> Model setup and parameters gathered from ...
#> StrathE2E2 package folder
#> Model results will be directed to/from ...
#> 'C:\Users\jackl\AppData\Local\Temp\RtmpYdRhoX/North_Sea/2003-2013/'
    results <- e2e_run(model, nyears=1)
    new_initial <- e2e_extract_start(model,results,csv.output=FALSE)
    new_initial
#>                            
#> detritus_so    5.225091e+00
#> detritus_d     9.632027e+00
#> x_detritus_s1  1.026034e+00
#> x_detritus_s2  1.706714e+01
#> x_detritus_s3  4.688093e+00
#> x_detritus_d1  2.147251e+01
#> x_detritus_d2  5.112290e+01
#> x_detritus_d3  2.237304e+00
#> xR_detritus_s1 1.093599e+02
#> xR_detritus_s2 1.060486e+04
#> xR_detritus_s3 1.467514e+03
#> xR_detritus_d1 1.768596e+03
#> xR_detritus_d2 1.664203e+04
#> xR_detritus_d3 5.854894e+02
#> discard_o      1.433301e-01
#> corpse_s1      2.186606e-02
#> corpse_s2      2.909027e-01
#> corpse_s3      7.201850e-02
#> corpse_d1      5.414734e-01
#> corpse_d2      8.489289e-01
#> corpse_d3      3.508698e-02
#> ammonia_so     3.450954e+01
#> ammonia_d      5.670773e+01
#> x_ammonia_s1   1.463005e-02
#> x_ammonia_s2   2.031617e-01
#> x_ammonia_s3   5.084491e-02
#> x_ammonia_d1   4.855120e-01
#> x_ammonia_d2   4.626300e-01
#> x_ammonia_d3   1.408431e-02
#> nitrate_so     2.246338e+02
#> nitrate_d      3.768632e+02
#> x_nitrate_s1   3.402812e-03
#> x_nitrate_s2   5.458893e-01
#> x_nitrate_s3   1.841532e-01
#> x_nitrate_d1   5.179863e-02
#> x_nitrate_d2   9.495670e-01
#> x_nitrate_d3   7.090843e-02
#> phyt_so        2.589635e-02
#> phyt_d         3.513854e-02
#> omni_o         6.094696e+00
#> carn_o         1.424300e+01
#> benthslar_o    1.321245e-02
#> benths_o       1.982064e+01
#> benthclar_o    3.137383e-06
#> benthc_o       1.159235e+01
#> fishp_o        1.100296e+01
#> fishplar_o     1.914903e+00
#> fishd_o        1.962549e+01
#> fishdlar_o     2.737294e-05
#> fishm_o        1.198940e+01
#> bird_o         8.836151e-03
#> detritus_si    1.474514e+00
#> ammonia_si     1.416921e+01
#> nitrate_si     6.172289e+01
#> phyt_si        6.673391e-02
#> benthslar_i    7.861082e-04
#> benthclar_i    1.795201e-07
#> benths_i       6.053768e+00
#> benthc_i       2.813576e+00
#> discard_i      5.722494e-02
#> omni_i         6.508379e-01
#> carn_i         1.578641e+00
#> fishplar_i     1.926118e-01
#> fishdlar_i     3.346241e-06
#> fishp_i        1.396547e+00
#> fishm_i        2.702041e-01
#> fishd_i        5.982759e+00
#> bird_i         7.998348e-04
#> seal_o         6.454721e-02
#> seal_i         8.867379e-03
#> ceta_o         4.655984e-02
#> ceta_i         2.357851e-03
#> corpse_s0      4.338553e-03
#> corpse_d0      1.055192e-02
#> kelpC          1.402803e+02
#> kelpN          2.018708e+01
#> kelpdebris     2.310793e+00

# Dummy example to illustrate the process of saving initial values
# data back into the model Param folder:
# Assumes that the model setup is held in models.path="Folder/Models". Replace this
# with your own relative path to your user library of models:
#    model <- e2e_read("Modelname","Variantname",models.path="Folder/Models",model.ident="new")
#    results <- e2e_run(model, nyears=30)
#    new_initial <- e2e_extract_start(model,results,csv.output=TRUE)
# The new initial values file will be written back into Folder/Models/Param with 
# the identitifer "new"