Interface to executable Simile models

Description

This package loads, parameterizes, executes and interrogates executable models saved by Simile.

Details

The package loads some Simile libraries into R's tcltk extension, so you need Simile installed to use it. Initialize the package by calling use.simile.at() to tell it where to find Simile in the file system. Tell it where to find the saved executable model with load.model() which returns a handle to the loaded model. This can be used to interrogate static model info via list.objects() and get.model.property(), and to create executable instances with create.model(), which returns their handles.

An executable instance can be parameterized either by loading a Simile parameter metafile with consult.parameter.metafile(), or directly from R arrays with create.param.array() and set.model.parameter(). The functions set.model.step(), reset.model() and execute.model() control execution. get.model.time() returns the time at which execution finished. Use get.value.array() to get the values from any model component as an R array, or get.value.list() to get them as an R list.

This version works with Simile versions 6.0 on.

Author(s)

Simulistics Ltd

References

Simile modelling environment: http://simulistics.com

Examples

require("Simile")
exec.extn <- as.character(tcl("info","sharedlibextension"))
if (interactive()) {
  path.to.installation <- tcl("tk_chooseDirectory", "-title",
  		       "Folder where Simile is installed:")

  path.to.spiro <- tcl("tk_getOpenFile",
		       "-title", "Compiled binary for Spiro example:",		
                       "-initialfile", paste("spiro",exec.extn,sep=""))
} else { 
  path.to.installation <- "dummy/path"
  path.to.spiro <- "dummy.dll"
}

use.simile.at(path.to.installation)
mHandle <- load.model(path.to.spiro)
objs <- list.objects(mHandle)

for (obj in objs) {
  print(c(obj, get.model.property(mHandle, obj, "Class")))
}

iHandle <- create.model(mHandle)
# model step is 0.1 by default but spiro only needs 1.0
set.model.step(iHandle, 1, 1)

# initialize the model, including default slider values
reset.model(iHandle, -2)

xs <- list(get.value.list(iHandle, "/runs/x"))
ys <- list(get.value.list(iHandle, "/runs/y"))
for (count in 1:1739) {
  execute.model(iHandle, count)
  xs[[count+1]] <- get.value.list(iHandle, "/runs/x")
  ys[[count+1]] <- get.value.list(iHandle, "/runs/y")
}
xs <- mapply(c,xs)
ys <- mapply(c,ys)
print("View default pattern -- now try to plot dancer")
plot(xs, ys, type="l")

# now we are going to parameterize it using a state file for the slider helper
# -- to make this work we load the mime library, which is needed only because
# the dancer.spf in Simile v6 is an older v4.x format file. No need to load 
# if testing, and will always be available if live because required for Simile.

if (!is.dummy(iHandle)) {
   tcl("package","require","mime")
}
pFile  <- tcl("file", "join", path.to.installation, "Examples", "dancer.spf")
consult.parameter.metafile(iHandle, pFile)

# also the file from the v6 distribution has no value for "Wheel outside?"
# so we set this boolean directly
pHandle <- create.param.array(iHandle, "/start/Wheel outside?")
set.model.parameter(pHandle, FALSE)

# apply reset at level 0 to propagate input values
reset.model(iHandle, 0)

xs <- list(get.value.list(iHandle, "/runs/x"))
ys <- list(get.value.list(iHandle, "/runs/y"))
for (count in 1:419) {
  execute.model(iHandle, count)
  xs[[count+1]] <- get.value.list(iHandle, "/runs/x")
  ys[[count+1]] <- get.value.list(iHandle, "/runs/y")
}
xs <- mapply(c,xs)
ys <- mapply(c,ys)
plot(xs, ys, type="l")

print("OK, but that's not how it looks on Simile is it? Try this...")
xs <- aperm(xs, c(2,1))
ys <- aperm(ys, c(2,1))
plot(xs, ys, type="l")

Set a model's parameters from a file saved by Simile

Description

Parameter metafiles (.spf) saved from within Simile can contain information about a model's parameter values, either locally or as references to other files. They may refer to the whole model or a submodel.

Usage

consult.parameter.metafile(instance.handle,param.file,target.submodel="")

Arguments

Value

None

Author(s)

Jasper Taylor

Examples

consult.parameter.metafile("dummy_ih", "../data/base_vals.spf")

Create an executable model instance

Description

A script can create many independent instances of the same model description, each with its own execution state.

Usage

create.model(model.handle)

Arguments

Value

A handle to a new instance of the model, which will have its own component values, parameter values and execution settings

Author(s)

Jasper Taylor

Examples

instance.handle <- create.model("dummy_mh")

Allocates memory for interactively loading model parameters

Description

If a script is to provide values directly for a Simile model parameter, this command must be called first to set up a location for the parameters to be held

Usage

create.param.array(instance.handle,param.name)

Arguments

Value

A handle to the location that has been created.

Author(s)

Jasper Taylor

Examples

param.handle <- create.param.array("dummy_ih", "/submodel1/trees/larch")

Execute a Simile model to a given time point

Description

The model will be executed using the time steps specified by earlier calling set.model.step until either the finish.time is reached or an exception occurs.

Usage

execute.model(instance.handle, finish.time, integration.method,
start.time, error.limit, pause.on.event)

Arguments

Value

Result code: value of system error (-ve), user-defined interruption (+ve) or 0 if model runs to finish.time

Author(s)

Jasper Taylor

Examples

for (count in 0:1738) {
  execute.model("dummy_ih", count+1, "Euler", count, 0, FALSE)
}

Get properties of model components

Description

This function can return any of several pieces of static information about a component in a loaded Simile model

Usage

get.model.property(model.handle,caption.path,requested.property)

Arguments

Value

Form of returned value depends on the requested.property as described above.

• For Class it is one of SUBMODEL VARIABLE COMPARTMENT FLOW CONDITION CREATION REPRODUCTION IMMIGRATION LOSS ALARM EVENT SQUIRT STATE

• For Type: one of VALUELESS REAL INTEGER FLAG EXTERNAL or ENUM(n), where n is the index of a set of enumerated type values.

• For Eval: one of EXOGENOUS DERIVED TABLE INPUT SPLIT GHOST. Fixed parameters have TABLE and variable parameters INPUT for this property.

• For Dims it is a list containing integers or the special types RECORDS MEMBERS SEPARATE START_VM END_VM for components in submodels without a preset member count.

• For MinVal and MaxVal it is a number of the same type as the component.

• For Desc and Comment it is a character string.

Author(s)

Jasper Taylor

Examples

get.model.property("dummy_mh","/sector/output","Class")
# [1] "COMPARTMENT"
get.model.property("dummy_mh","/sector/output","Dims")
# [1] 2 5

Gets the time in the simulation.

Description

The simulation time is initialized by the reset.model command, and incremented by the execute.model command. After execute.model it may not be the expected end time because the model may stop executing before that point for various reasons.

Usage

get.model.time(instance.handle)

Arguments

Value

The current model time

Author(s)

Jasper Taylor

Examples

get.model.time("dummy_ih")

Get values from model components

Description

Retrieves data from the model, as either a single quantity or an array of values with the appropriate dimensions

Usage

get.value.array(instance.handle, value.name, as.enum.types)

Arguments

Value

A value or array of values, from the model

Note

Will not work on components inside variable-membership submodels. For these you should use get.value.list instead, as R's list structure is more appropriate than the array structure when not all values exist.

Author(s)

Jasper Taylor

See Also

get.value.list

Examples

get.value.array("dummy_ih", "/sector/output", FALSE)
# [1]  0.8414710  0.9092974  0.1411200 -0.7568025 -0.9589243 -0.2794155
# [7]  0.6569866  0.9893582  0.4121185 -0.5440211

Get values from model components

Description

Retrieves data from the model, as either a single quantity or a possibly nested list of values

Usage

get.value.list(instance.handle, value.name, as.enum.types)

Arguments

Value

A value or index-value list, from the model

Author(s)

Jasper Taylor

See Also

get.value.array

Examples

get.value.list("dummy_ih", "/runs/x", "FALSE")
# [[1]]
# [1] 40.76668
# 
# [[2]]
# [1] 37.52907
# 
# [[3]]
# [1] 33.82021
# 
# [[4]]
# [1] 29.69413

Test if a path or handle is a 'dummy' whose only purpose is to allow tests to run.

Description

When any of the functions in the package are called, if this returns 'true' on their first argument, no actual Simile interaction will be attempted but some sample output may be returned.

Usage

is.dummy(path.or.handle)

Arguments

Value

A boolean which is true in the case of a dummy argument.

Author(s)

Jasper Taylor

Examples

is.dummy("dummy.dll")
# [1] TRUE
is.dummy("~/.simile/Examples/spiro.so")
# [1] FALSE

List Simile model components

Description

Lists all the model components with values. Components are specified by path, i.e., a string made from their caption preceded by the caption of their parent submodel, its parent and so on, separated by forward-slashes like a directory path.

Usage

list.objects(model.handle)

Arguments

Value

List of component paths as described above, in tree traversal order

Author(s)

Jasper Taylor

Examples

list.objects("dummy_mh")
# [1] "/sector"           "/sector/output"    "/sector/flow1"    
# [4] "/sector/variation"

Load a Simile executable model

Description

Loads a simile model saved as a compiled binary ( a .dll, .so or .dylib file depending on platform)

Usage

load.model(path.to.binary)

Arguments

Value

Handle to be used for querying or instantiating model, as a Tcl object

Author(s)

Jasper Taylor

Examples

model.handle <- load.model("dummy.dll")

resets the model to its initial state.

Description

A Simile model instance must be reset before it is first run, whenever the parameters are changed, and in order to run it again with new values for random constants.

Usage

reset.model(instance.handle, depth, integration.method, starting.time)

Arguments

Value

None

Author(s)

Jasper Taylor

Examples

reset.model("dummy_ih", -2)

Sets a model parameter with data in an array

Description

A model parameter may be a single value or an array of values. This function allows it to be set.

Usage

set.model.parameter(param.handle,data, as.enum.types)

Arguments

Value

None

Author(s)

Jasper Taylor

Examples

set.model.parameter("dummy_ph", array(c(4,4,3,4,2,5,5,2,1,5), c(2,5)))

Sets the time step used to execute a model.

Description

The time step is the amount by which the model time advances each time the state variables are updated. A model may have more than one time step.

Usage

set.model.step(instance.handle,step.index,step.size)

Arguments

Value

None

Author(s)

Jasper Taylor

Examples

set.model.step("dummy_ih", 1, 0.1)

Re-format model value array

Description

Convert a set of values from a Simile model component from a nested list of alternating indices and values to an R array structure

Usage

tcl.paired.to.array(paired, dims, as.enum.types)

Arguments

Value

A numerical value or array of numerical values, from the Tcl value or array

Note

Note that the dimensions of the array returned will be in the opposite order from those supplied in the 'dims' argument. This is because Simile's convention is to list the outermost dimension first, whereas R's is to list the outermost dimension last.

Author(s)

Jasper Taylor

See Also

tcl.paired.to.list

Examples

Simile:::tcl.paired.to.array("1 {1 7 2 4} 2 {1 8 2 6} 3 {1 9 2 1}",
c(3,2), FALSE)
#     [,1] [,2] [,3]
#[1,]    7    8    9
#[2,]    4    6    1

Re-format model value array

Description

Convert a set of values from a Simile model component from a nested list of alternating indices and values to an R nested list structure

Usage

tcl.paired.to.list(paired, as.enum.types)

Arguments

Value

A numerical value or nested list of numerical values, from the Tcl value or array

Author(s)

Jasper Taylor

See Also

tcl.paired.to.array

Examples

Simile:::tcl.paired.to.list("1 {1 7 2 4} 2 {1 8} 3 {2 1}", FALSE)
# [[1]]
# [[1]][[1]]
# [1] 7
# 
# [[1]][[2]]
# [1] 4
# 
# 
# [[2]]
# [[2]][[1]]
# [1] 8
# 
# 
# [[3]]
# [[3]][[1]]
# NULL
# 
# [[3]][[2]]
# [1] 1

Initialize the Simile interface

Description

This tells the package where to find an installed copy of Simile. It then loads the Tcl command implementations in the Simile installation to enable R's tcltk package to communicate with Simile's saved executable models. It should be called only once in a session.

Usage

use.simile.at(path.to.installation)

Arguments

Value

undefined.

Author(s)

Simulistics Ltd

Examples

use.simile.at("dummy/path")