From 84db2e9bfce3004e4c30501186d99158e5df47f3 Mon Sep 17 00:00:00 2001
From: Pavel Balazki <pavel.balazki@gmail.com>
Date: Mon, 6 May 2024 15:24:01 +0200
Subject: [PATCH] Add documentation how to vary RHS params in SimulationBatch
 (#1398)

---
 R/utilities-simulation.R                   | 17 +++++++-----
 tests/testthat/test-utilities-simulation.R |  3 +-
 vignettes/efficient-calculations.Rmd       | 32 ++++++++++++++++++++--
 3 files changed, 42 insertions(+), 10 deletions(-)

diff --git a/R/utilities-simulation.R b/R/utilities-simulation.R
index 1d8356473..fb85e196b 100644
--- a/R/utilities-simulation.R
+++ b/R/utilities-simulation.R
@@ -124,11 +124,13 @@ saveSimulation <- function(simulation, filePath) {
 #' popPath <- system.file("extdata", "pop.csv", package = "ospsuite")
 #' population <- loadPopulation(popPath)
 #' results <- runSimulation(sim, population, simulationRunOptions = simRunOptions)
-#'}
+#' }
 runSimulation <- function(simulation, population = NULL, agingData = NULL, simulationRunOptions = NULL) {
-  lifecycle::deprecate_soft(when = "12.0.0",
-                            what = "runSimulation()",
-                            with = "runSimulations()")
+  lifecycle::deprecate_soft(
+    when = "12.0.0",
+    what = "runSimulation()",
+    with = "runSimulations()"
+  )
 
   # Check that only one simulation is passed
   simulation <- c(simulation)
@@ -202,7 +204,6 @@ runSimulations <- function(simulations, population = NULL, agingData = NULL, sim
     outputList <- list()
     outputList[[simulations[[1]]$id]] <- results
   } else {
-
     # more than one simulation? This is a concurrent run.
 
     # We do not allow population variation
@@ -338,7 +339,7 @@ runSimulations <- function(simulations, population = NULL, agingData = NULL, sim
 createSimulationBatch <- function(simulation, parametersOrPaths = NULL, moleculesOrPaths = NULL) {
   validateIsOfType(simulation, "Simulation")
   validateIsOfType(parametersOrPaths, c("Parameter", "character"), nullAllowed = TRUE)
-  validateIsOfType(moleculesOrPaths, c("Molecule", "character"), nullAllowed = TRUE)
+  validateIsOfType(moleculesOrPaths, c("Quantity", "character"), nullAllowed = TRUE)
 
   if (length(parametersOrPaths) == 0 && length(moleculesOrPaths) == 0) {
     stop(messages$errorSimulationBatchNothingToVary)
@@ -352,7 +353,9 @@ createSimulationBatch <- function(simulation, parametersOrPaths = NULL, molecule
 
   variableMolecules <- c(moleculesOrPaths)
 
-  if (isOfType(variableMolecules, "Molecule")) {
+  # Checking for Quantity instead of Molecule because state variable parameters must
+  # be added as molecules
+  if (isOfType(variableMolecules, "Quantity")) {
     variableMolecules <- unlist(lapply(variableMolecules, function(x) x$path), use.names = FALSE)
   }
 
diff --git a/tests/testthat/test-utilities-simulation.R b/tests/testthat/test-utilities-simulation.R
index 558d8cb73..a3d7fc09f 100644
--- a/tests/testthat/test-utilities-simulation.R
+++ b/tests/testthat/test-utilities-simulation.R
@@ -80,7 +80,8 @@ test_that("Two sims not from cache and third from cache", {
 
 test_that("It throws an exception if the pkml loaded is not a valid simulation file", {
   expect_error(loadTestSimulation("molecules"),
-               regexp =  "Could not load simulation")
+    regexp = "Could not load simulation"
+  )
 })
 
 test_that("It can remove simulation from cache", {
diff --git a/vignettes/efficient-calculations.Rmd b/vignettes/efficient-calculations.Rmd
index d902d2244..04b691886 100644
--- a/vignettes/efficient-calculations.Rmd
+++ b/vignettes/efficient-calculations.Rmd
@@ -178,7 +178,6 @@ results <- runSimulationBatches(simulationBatches)
 print(names(unlist(results)))
 ```
 
-
 The enqueued run values are cleared after calling `runSimulationBatches()`, so executing the run
 again would result in an empty results list. We can now set more values to the batches and run them again. 
 Notes: 
@@ -204,4 +203,33 @@ rm(simBatch2)
 
 Usage of `SimulationBatch` is recommended for advanced scenarios where simulations
 expected to be run hundreds of times and where each second that can be spared
-will impact the performance significantly. 
+will impact the performance significantly.
+
+### Varying state variable parameters with SimulationBatch
+
+State variable parameters, i.e., those defined by a right hand side (RHS), are treated as molecules internally. Trying to create and run a simulation batch with a state variable parameter set as a variable parameter
+will result in an error:
+
+```{r BatchRunStateVarParam, eval=TRUE, error = TRUE, purl = FALSE}
+stateVariableParam <- getParameter(path = "Organism|Lumen|Stomach|Liquid", container = sim1)
+print(stateVariableParam)
+
+# Create simulation batch with state variable parameter set as a variable parameter
+simBatch <- createSimulationBatch(simulation = sim1, parametersOrPaths = stateVariableParam)
+
+# Add run values
+resId <- simBatch$addRunValues(parameterValues = 0.5)
+# Try to run batch
+results <- runSimulationBatches(simBatch)
+```
+
+Instead, the state variable parameter should be treated as a species and set as a variable molecule start value.
+
+```{r BatchRunStateVarMolecule, eval=TRUE}
+# Create simulation batch with state variable parameter set as a variable molecule
+simBatch <- createSimulationBatch(simulation = sim1, moleculesOrPaths = stateVariableParam)
+# Add run values
+resId <- simBatch$addRunValues(initialValues = 0.5)
+# Try to run batch
+results <- runSimulationBatches(simBatch)
+```