Adding a model

Follow these steps to add a model (i.e. calculations) to a package.

Note

While models can be written in just about any programming language, this article demonstrates the concepts using scripts written in both the R Programming Language and the Python Programming Language. In order to run the following example you will need to first install the R Programming Language if you are creating an R model or the Python Programming Language if you are creating a Python model.

Step 1: Add a transformer to your configuration file

Although the helloworld package created in the previous article is a complete package, it does not yet do any model calculations and so is not yet runnable in SyncroSim. To make the package runnable we must first add at least one transformer element to the package.

Transformers are the executable units of a SyncroSim package - in other words, the calculations associated with your package.

In the example below we will add a single transformer to the helloworld package; this transformer will take the form of an R or Python script.

Note

As is the case in all of the helloworld examples, the package.xml file below has been formatted for demonstration purposes. Most real packages use more typical XML formatting to save vertical space. For example, each attribute for an element normally appears on the same line.

Start by uninstalling the helloworld package created in the previous article before introducing changes to the package. Next, we will update the package.xml file:

<?xml version="1.0" encoding="utf-8"?>
<package name="helloworld" displayName="Hello World (R)" version="1.0.0">

  <!--Transformer-->  
  <transformer 
    name="Main" 
    displayName="Run Hello World (R)" 
    programArguments="model.R"/>

</package>

Notice that we have added to our previous example a new <transformer> element as a child of the <package> element.

In this simple example we have specified our transformer element with the following attributes:

  • name specifies the internal name of the transformer.
  • displayName specifies the name of the transformer as seen in the SyncroSim Studio user interface.
  • programArguments="model.R" or "model.py" to specify a string to pass to the external program as the console argument: in this case we specify model.R as the name of our R Script, or model.py as the name of our Python script.
Note

The example XML configuration file above assumes your transformer calls an R Script. Because R is used so frequently with SyncroSim, entering the keyword RScript for the ProgramName argument allows SyncroSim to try to find your R installation automatically, and/or to specify it directly in the SyncroSim Studio.

Replace your existing package.xml file in the helloworld subfolder (from the previous article) with the text above.

Step 2: Create the model script

Of course, the model.R file does not exist yet. You must create it and add it to the package. Below is a very simple example script in R that multiplies two numbers together and saves the results to a file:

x <- 5.0                                 # Set first model input
a <- 2                                   # Set second model input

y <- a * x                               # Calculate output

# Save output to file
write.csv(y, file = "c:/temp/helloworld.csv", row.names=F)

Before closing R, make sure you have installed the rsyncrosim package.

install.packages("rsyncrosim")
Note

The example model.R script above assumes you are using c:\temp as your working folder for this tutorial. If you are using a different folder then you will need to modify the last line of this example accordingly.

Save the text above to a file called model.R in your helloworld subfolder (from the previous article)

Step 3: Rebuild the package

Next use the Package Manager to rebuild the package (see Step 2-3 in the Building a package article).

Step 4: Run the model

You are now ready to run your model from SyncroSim.

alt text

  1. Start SyncroSim Studio.
  2. Install the helloworld package by navigating to File > Local Packages > Install from File... and select your helloworld.ssimpkg file.
  3. Create a new library by navigating to File > New.... Save your library with the default name and location, or specify your own library name and location. Select Save.
  4. Add the helloworld package by navigating to File > Library Datafeeds > General > Packages. Click Add... and select the helloworld package.
  5. Check your executable location. In the Library Explorer, click on the helloworld library, and then double-click on the library or right-click and choose Open from the context menu. Then select System > Tools > R or System > Tools > Python tab to check and/or set the location of your R or Python Program Executable. Note that if you installed R in its default location then SyncroSim will have found it automatically (shown as Default), in which case you can leave this screen blank.
  6. Set the pipeline stage. In the Library Explorer, double-click on the auto-generated empty New Scenario and navigate to the General tab. Click on the Pipeline option, and set the pipeline stage to Run Hello World. It should have a default Run Order of 1.
  7. Run the scenario. In the Library Explorer, click on the auto-generated New Scenario, and then select Run from the Scenario menu.

Your scenario should run without error; the results of your run can be found in the CSV file (e.g. C:\temp\helloworld.csv) generated by your script above.

Note

You can optionally run your R or Python script interactively (i.e. line by line) from within SyncroSim; this can be very helpful for testing and debugging a new script.

Using an IDE

To run your script interactively from an Integrated Development Environment (IDE) such as (R Studio) or (Visual Studio Code), return to System > Tools > R or System > Tools > Python tab and select the button beside Run using IDE. In the filepath, point to the IDE program executable (e.g. by default for RStudio this would be C:\Program Files\RStudio\bin\rstudio.exe); this ensures SyncroSim opens the IDE each time your model is run. You can then run your R or Python script line-by-line as you would normally in your IDE.

What's next?