simplace: Interface to use the modelling framework 'SIMPLACE'

Description

Interface to interact with the modelling framework 'SIMPLACE' and to parse the results of simulations

Details

Package needs a Java Runtime Environment as well as an installation of 'SIMPLACE'. See www.simplace.net for more information about 'SIMPLACE'.

Author(s)

Gunther Krauss

References

www.simplace.net

See Also

Useful links:

• https://github.com/gk-crop/simplace_rpkg/

• https://r-forge.r-project.org/projects/simplace/

Examples

  ## Not run: 
    SimplaceInstallationDir <- "D:/java/simplace/"
    
    SimplaceWorkDir <- "D:/java/simplace/simplace_run/simulation/"
    SimplaceOutputDir <-  "D:/java/simplace/simplace_run/output/"
    
    Solution <- "D:/java/simplace/simplace_run/simulation/gk/solution/complete/Complete.sol.xml"
    
    simplace <- initSimplace(SimplaceInstallationDir,SimplaceWorkDir,SimplaceOutputDir)
    
    openProject(simplace, Solution)
    
    parameter <- list()
    parameter$vTempLimit <- 32
    
    simid <- createSimulation(simplace,parameter)
    runSimulations(simplace)
    
    result <- getResult(simplace,"DIAGRAM_OUT", simid);
    
    closeProject(simplace)
    
    resultlist <- resultToList(result)
    resultframe <- resultToDataframe(result)
  
## End(Not run)

Close Project

Description

Call to the shutDown method of the simulation.

Usage

closeProject(simplace)

Arguments

Value

No return value, called for the side effect of closing the simulation project

See Also

openProject

Creates a simulation and substitute parameters

Description

Creates a simulation from the opened project and substitutes the values of the parameters given in the parameter list. Simulation won't be queued by default.

Usage

createSimulation(simplace, parameterList = NULL, queue = FALSE)

Arguments

Value

id of the created simulation

See Also

runSimulations, resetSimulationQueue

Search for simplace installation and returns first match

Description

Checks directories if they contain simplace_core, simplace_modules and optionally simplace_run (or a data directory given by the user) and returns the first match. There is no check whether the installation is really working.

Usage

findFirstSimplaceInstallation(
  directories = c(),
  tryStandardDirs = TRUE,
  simulationsDir = "simplace_run",
  ignoreSimulationsDir = FALSE
)

Arguments

Details

Beside the checks for some standard directories (like home directory, current working dir and drives c: to g:) and their subdirectories (workspace, simplace, java/simplace) the user can give a vector of additional directories. Directories given by the user are checked first.

Value

matching directory/ies as character vector

Search for simplace installations and returns results as vector

Description

Checks directories if they contain simplace_core, simplace_modules and optionally simplace_run (or a data directory given by the user) and returns the matches. There is no check whether the installation is really working.

Usage

findSimplaceInstallations(
  directories = c(),
  tryStandardDirs = TRUE,
  firstMatchOnly = FALSE,
  simulationsDir = "simplace_run",
  ignoreSimulationsDir = FALSE,
  verbose = TRUE
)

Arguments

Details

Beside the checks for some standard directories (like home directory, current working dir and drives c: to g:) and their subdirectories (workspace, simplace, java/simplace) the user can give a vector of additional directories.

Value

matching directory/ies as character vector

Get the datatypes of the result variables

Description

Get the datatypes of each variable (i.e. data column). The output is a named character vector, where each element is named by the variables name.

Usage

getDatatypesOfResult(result)

Arguments

Value

named character vector with the datatypes

Fetch output from a simulation

Description

The output is a JavaObject containing the variable names, data types, units and the values. Output can be converted with resultToList or resultToDataframe to R objects. Only MEMORY outputs are accessible. For CSV or database outputs you have to read the data by generic methods.

Usage

getResult(simplace, outputId, simulationId = nullString)

Arguments

Value

handle to the data container which has to be processed afterwards

Get the directories (work-, output-, projects- and data-dir)

Description

Get the directories (work-, output-, projects- and data-dir)

Usage

getSimplaceDirectories(simplace)

Arguments

Value

character vector with the directories

See Also

setSimplaceDirectories

Lists IDs of the performed simulations

Description

Returns a vector with the IDs of the simulations. IDs are required to get the output of the simulations.

Usage

getSimulationIDs(simplace)

Arguments

Value

character vector with the IDs

Get the units of the result variables

Description

Get the units of each variable (i.e. data column) in a human readable format. The output is a named character vector, where each element is named by the variables name.

Usage

getUnitsOfResult(result)

Arguments

Value

named character vector with the units

Initialisation of Framework

Description

Initializes the JVM and creates the SimplaceWrapper object which is used to interact with Simplace.

Usage

initSimplace(
  InstallationDir = findFirstSimplaceInstallation(),
  WorkDir = paste0(InstallationDir, "simplace_run/simulation/"),
  OutputDir = paste0(InstallationDir, "simplace_run/output/"),
  ProjectsDir = nullString,
  DataDir = nullString,
  additionalClasspaths = c(),
  javaparameters = getOption("java.parameters"),
  force.init = TRUE
)

Arguments

Value

handle to the SimplaceWrapper object

Initialises Simplace with work- and outputdir for different settings

Description

Initialises Simplace with work- and outputdir for different settings

Usage

initSimplaceDefault(setting = "run")

Arguments

Value

handle to the SimplaceWrapper object

See Also

initSimplace

Opens a Simplace project

Description

Initializes a project. Solution is mandatory, project is optional. Solution and project files can be specified by giving absolute paths or paths relative to the simplace directory. Instead of using solution and project files, one can use the content of the solution / project directly as a string or a "xml_document" class.

Usage

openProject(simplace, solution, project = nullString, parameterList = NULL)

Arguments

Value

invisibly a list with java FWSimsession object as well as the solution, project and parameterList

See Also

closeProject

Clears the list of simulations

Description

Simulation list is cleared

Usage

resetSimulationQueue(simplace)

Arguments

Value

No return value, called for the side effect of clearing the simulation list

See Also

createSimulation, runSimulations

Convert result to dataframe

Description

All scalar output columns are transformed to appropriate R objects and then glued together in a dataframe. Array outputs columns are ignored.

Usage

resultToDataframe(result, expand = FALSE, from = NULL, to = NULL)

Arguments

Value

data.frame with scalar output columns

See Also

resultToList returns the output columns as list

Examples

## Not run: 
simplace <- initSimplace(SimplaceInstallationDir,SimplaceWorkDir,SimplaceOutputDir)
openProject(simplace, Solution)
parameter <- list(vTempLimit = 32)
simid <- createSimulation(simplace,parameter)
runSimulations(simplace)
result <- getResult(simplace,"DIAGRAM_OUT", simid);
closeProject(simplace)
resultframe <- resultToDataframe(result)
resultframe[3,]
## End(Not run)

Convert result to list

Description

Converts all scalar output columns to appropriate R lists. Columns containing arrays are left unchanged, unless expand is TRUE.

Usage

resultToList(result, expand = FALSE, from = NULL, to = NULL)

Arguments

Value

list with output columns

See Also

resultToDataframe returns the scalar output columns as data.frame

Examples

## Not run: 
simplace <- initSimplace(SimplaceInstallationDir,SimplaceWorkDir,SimplaceOutputDir)
openProject(simplace, Solution)
parameter <- list(vTempLimit = 32)
simid <- createSimulation(simplace,parameter)
runSimulations(simplace)
closeProject(simplace)
result <- getResult(simplace,"DIAGRAM_OUT", simid);
resultlist <- resultToList(result)
resultlist$CURRENT.DATE
## End(Not run)

Runs the opened project

Description

Runs the simulation(s) as defined in the solution and project files. There is no accessible MEMORY output, but one can load the CSV or database output.

Usage

runProject(simplace)

Arguments

Value

No return value, called for the side effect of running opened project

Examples

## Not run: 
simplace <- initSimplace(SimplaceInstallationDir,SimplaceWorkDir,SimplaceOutputDir)
openProject(simplace, Solution, Project)
runProject(simplace)
closeProject(simplace)   
## End(Not run)

Run the created simulations

Description

Run the created simulations from the queue. If the queue is empty, the last created simulation will be run.

Usage

runSimulations(simplace, selectsimulation = FALSE)

Arguments

Value

No return value, called for the side effect of running the simulation

See Also

createSimulation, resetSimulationQueue

Examples

## Not run: 
simplace <- initSimplace(SimplaceInstallationDir,SimplaceWorkDir,SimplaceOutputDir)
openProject(simplace, Solution)
parameters <- list()
parameters$vBaseLUE <- 3.0
s1 <- createSimulation(simplace, parameters,queue=TRUE)
parameters$vBaseLUE <- 3.2
s2 <- createSimulation(simplace, parameters,queue=TRUE)
runSimulations(simplace)
parameters$vBaseLUE <- 2.8
s3 <- createSimulation(simplace, parameters,queue=TRUE)
runSimulations(simplace)

closeProject(simplace)   
## End(Not run)

Changes values of the all simulations in queue

Description

Sets values of arbitrary SimVariables in a simplace simulation. Useful if you want to couple simplace with another simulation and interchange values daily.

Usage

setAllSimulationValues(simplace, parameterLists = NULL)

Arguments

Value

No return value, called for the side effect of changing parameters in all simulations

Examples

## Not run: 
for(i in 1:365)
{
  params <- list()
  params[[1]] <- list(vBaseLUE=3.0 + i/2000)
  params[[2]] <- list(vBaseLUE=3.0 - i/2000)
  setAllSimulationValues(simplace,params)
  stepAllSimulations(simplace)
}

## End(Not run)

Sets the check level of the framework

Description

Sets the check level. OFF does no check at all, STRICT the most severe. You have to call initSimplace first.

Usage

setCheckLevel(simplace, level)

Arguments

Value

No return value, called for the side effect of setting the check level

Examples

## Not run: 
setCheckLevel(simplace, "STRICT")
## End(Not run)

Sets the log level of the framework

Description

Sets the level of logger output - FATAL is least verbose, TRACE most verbose. You have to call initSimplace first.

Usage

setLogLevel(level)

Arguments

Value

No return value, called for the side effect of setting the log level

Examples

## Not run: 
setLogLevel("INFO")
## End(Not run)

Sets the lines of the project data files that should be used when running a project.

Description

You have to call the function after initSimplace but before openProject.

Usage

setProjectLines(simplace, lines)

Arguments

Value

No return value, called for the side effect of selecting project to be run

Examples

## Not run: 
setProjectLines(simplace, "1,3,6,9-17,33")
setProjectLines(simplace, c(1,2,3,9:17,33))
## End(Not run)

Set working-, output-, projects- and data-directory

Description

One can specify all or only some of the directories. Only the directories specified will be set.

Usage

setSimplaceDirectories(
  simplace,
  WorkDir = nullString,
  OutputDir = nullString,
  ProjectsDir = nullString,
  DataDir = nullString
)

Arguments

Value

No return value, called for the side effect of setting framework directories

See Also

getSimplaceDirectories

Changes values of the current simulation

Description

Sets values of arbitrary SimVariables in a simplace simulation. Useful if you want to couple simplace with another simulation and interchange values daily.

Usage

setSimulationValues(simplace, parameterList = NULL, simulationNumber = 1)

Arguments

Value

No return value, called for the side effect of changing parameters in the current simulation

Examples

## Not run: 
for(i in 1:365)
{
  param <- list(vBaseLUE=3.0 + i/2000)
  setSimulationValues(simplace,param)
  stepSimulation(simplace)
}

## End(Not run)

Sets number of used CPUs

Description

Sets the number of processors that are used parallel. The function can be used only after initSimplace has been called.

Usage

setSlotCount(count)

Arguments

Value

No return value, called for the side effect of setting the number of processors used for simulation runs

Run all simulations in queue stepwise

Description

Performs count steps of the simulation and returns the values from the actual variable map. Can be called consecutively.

Usage

stepAllSimulations(simplace, count = 1, filter = NULL, parameterLists = NULL)

Arguments

Value

handle to an array of data containers which has to be processed afterwards

Examples

## Not run: 
simplace <- initSimplace(SimplaceInstallationDir,SimplaceWorkDir,SimplaceOutputDir)
openProject(simplace, Solution)
createSimulation(simplace)
vm <- stepAllSimulations(simplace,count=22)
vm_s <- stepAllSimulations(simplace,filter=c("CURRENT.DATE","LintulBiomass.sWSO"),count=18)
closeProject(simplace)   
## End(Not run)

Run simulation stepwise

Description

Performs count steps of the simulation and returns the values from the actual variable map. Can be called consecutively.

Usage

stepSimulation(
  simplace,
  count = 1,
  filter = NULL,
  parameterList = NULL,
  simulationNumber = 1
)

Arguments

Value

handle to the data container which has to be processed afterwards

Examples

## Not run: 
simplace <- initSimplace(SimplaceInstallationDir,SimplaceWorkDir,SimplaceOutputDir)
openProject(simplace, Solution)
createSimulation(simplace)
vm <- stepSimulation(simplace,count=22)
vm_s <- stepSimulation(simplace,filter=c("CURRENT.DATE","LintulBiomass.sWSO"),count=18)
closeProject(simplace)   
## End(Not run)

Converts the varmap to a list

Description

Converts the varMap to a list. All elements are converted to appropriate R objects. Arrays are expanded to vectors by default.

Usage

varmapToList(varmap, expand = TRUE)

Arguments

Value

list with parameter name as key and parameter value as value

Examples

## Not run: 
simplace <- initSimplace(SimplaceInstallationDir,SimplaceWorkDir,SimplaceOutputDir)
openProject(simplace, Solution)
createSimulation(simplace)
varmap <- stepSimulation(simplace,count=22)
closeProject(simplace)   
varlist <- varmapToList(varmap)
varlist$startdate - 365
varlist$LintulBiomass.sWSO
## End(Not run)