Extract the values of all the state variables at the end of a model run and format for use as new initial conditions.
e2ep_extract_start.Rd
The function saves the state of the model at the end of a run (using the e2ep_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.
Arguments
- model
R-list object defining the model configuration compiled by the e2ep_read() function.
- results
R-list object generated by the e2ep_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 Barents 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 e2ep_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 e2ep_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 e2ep_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 e2ep_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 Barents 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 <- e2ep_read("Barents_Sea", "2011-2019")
#> Current working directory is...
#> 'C:/Users/jackl/OneDrive - University of Strathclyde/Documents/StrathE2E/strath-e-2-e-polar-webdev/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\RtmpSgdWsc'
#>
#> Model setup and parameters gathered from ...
#> StrathE2E2 package folder
#> Model results will be directed to/from ...
#> 'C:\Users\jackl\AppData\Local\Temp\RtmpSgdWsc/Barents_Sea/2011-2019/'
results <- e2ep_run(model, nyears=1)
new_initial <- e2ep_extract_start(model,results,csv.output=FALSE)
new_initial
#>
#> detritus_so 3.459532e-01
#> detritus_d 9.822060e-01
#> x_detritus_s1 7.981909e+00
#> x_detritus_s2 9.123963e+00
#> x_detritus_s3 2.003412e+00
#> x_detritus_d1 3.724259e+01
#> x_detritus_d2 8.310566e+00
#> x_detritus_d3 2.919734e+00
#> xR_detritus_s1 2.817215e+03
#> xR_detritus_s2 2.135459e+03
#> xR_detritus_s3 5.057679e+02
#> xR_detritus_d1 7.621292e+03
#> xR_detritus_d2 3.118000e+03
#> xR_detritus_d3 1.462919e+03
#> discard_o 9.050039e-03
#> corpse_s1 7.443520e-02
#> corpse_s2 8.973206e-02
#> corpse_s3 1.956595e-02
#> corpse_d1 4.775434e-01
#> corpse_d2 9.687968e-02
#> corpse_d3 3.331724e-02
#> ammonia_so 1.031120e+02
#> ammonia_d 2.749245e+02
#> x_ammonia_s1 2.144575e-01
#> x_ammonia_s2 1.573046e-01
#> x_ammonia_s3 3.212957e-02
#> x_ammonia_d1 1.206235e+00
#> x_ammonia_d2 1.377844e-01
#> x_ammonia_d3 4.057025e-02
#> nitrate_so 3.802420e+02
#> nitrate_d 1.181680e+03
#> x_nitrate_s1 1.052212e-01
#> x_nitrate_s2 1.338937e-01
#> x_nitrate_s3 3.455900e-02
#> x_nitrate_d1 3.164373e-01
#> x_nitrate_d2 2.783995e-01
#> x_nitrate_d3 1.492648e-01
#> phyt_so 3.991676e-01
#> phyt_d 3.643100e-01
#> omni_o 1.410831e+01
#> carn_o 8.362167e+00
#> benthslar_o 7.555195e-06
#> benths_o 2.133026e+01
#> benthclar_o 3.277439e-06
#> benthc_o 7.579730e+00
#> fishp_o 3.322471e+00
#> fishplar_o 2.253724e-07
#> fishd_o 6.245716e+00
#> fishdlar_o 1.876282e-06
#> fishm_o 2.739032e-03
#> bird_o 1.130899e-03
#> detritus_si 2.676137e-01
#> ammonia_si 6.994415e+01
#> nitrate_si 8.539557e+01
#> phyt_si 2.078179e-02
#> benthslar_i 1.525726e-06
#> benthclar_i 7.271333e-07
#> benths_i 5.318751e+00
#> benthc_i 1.783265e+00
#> discard_i 1.427112e-03
#> omni_i 2.101369e+00
#> carn_i 9.173069e-01
#> fishplar_i 5.552258e-08
#> fishdlar_i 5.825892e-07
#> fishp_i 3.745892e-01
#> fishm_i 8.112221e-05
#> fishd_i 1.687098e+00
#> bird_i 8.052869e-05
#> seal_o 6.735488e-02
#> seal_i 3.298525e-03
#> ceta_o 1.694028e-01
#> ceta_i 4.336810e-03
#> corpse_s0 1.147049e-02
#> corpse_d0 5.055360e-03
#> kelpC 3.964861e+02
#> kelpN 5.284389e+01
#> kelpdebris 6.984281e+00
#> snow_ammonia_o 2.004734e-02
#> snow_nitrate_o 2.852982e-02
#> ice_ammonia_o 2.687967e-02
#> ice_nitrate_o 2.851459e-02
#> ice_detritus_o 6.277464e-04
#> ice_algae_o 1.192971e-04
#> snow_ammonia_i 1.524380e-02
#> snow_nitrate_i 1.468124e-02
#> ice_ammonia_i 3.087618e-02
#> ice_nitrate_i 1.483430e-03
#> ice_detritus_i 2.958132e-03
#> ice_algae_i 1.668537e-04
#> bear_o 1.773226e-03
#> bear_i 4.854519e-04
#> htlcorp_o 4.350259e-05
#> htlcorp_i 2.513845e-07
#> wintering_bird_o 2.114241e-02
#> wintering_bird_i 1.160017e-03
#> wintering_seal_o 0.000000e+00
#> wintering_seal_i 0.000000e+00
#> wintering_ceta_o 5.265305e-01
#> wintering_ceta_i 1.310048e-02
#> wintering_bear_o 0.000000e+00
#> wintering_bear_i 3.651227e-04
# 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 <- e2ep_read("Modelname","Variantname",models.path="Folder/Models",model.ident="new")
# results <- e2ep_run(model, nyears=30)
# new_initial <- e2ep_extract_start(model,results,csv.output=TRUE)
# The new initial values file will be written back into Folder/Models/Param with
# the identitifer "new"