Defining data

Follow these steps to specify the inputs and outputs for a package.

In the previous article we added a transformer to the helloworld package, but there is still one thing missing: we have not yet specified the format of the data that goes in to and out of this package; as a result we cannot yet manage the data within SyncroSim.

Step 1: Add inputs and outputs to the XML Configuration File

To provide the transformer with model inputs and outputs, in this example we will add two datasheets to our existing XML configuration file for the helloworld package: one for inputs (i.e. values of x and a in our R or Python Scripts) and one for outputs (i.e. calculated values of y). Here is the revised package.xml file:

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

  <!--Scenario Datasheets-->

  <!--Model Inputs-->
  <dataSheet name="InputDatasheet" displayName="Inputs">
    <column name="x" dataType="Double" displayName="Value for x"/>
    <column name="a" dataType="Integer" displayName="Value for a"/>
  </dataSheet>

  <!--Model Outputs-->
  <dataSheet name="OutputDatasheet" displayName="Outputs">
    <column name="y" dataType="Double" displayName="Value for y"/>
  </dataSheet>

  <!--Transformers-->

  <transformer 
    name="Main" 
    displayName="Run Hello World (R)" 
    programArguments="model.R">
      <dataSheet name="InputDatasheet" type="Input"/>
      <dataSheet name="OutputDatasheet" type="Output"/>
  </transformer>

  <!--Layouts-->

  <!--Scenario Datasheets Layout-->
  <layout type="Scenario">
    <item name="InputDatasheet"/>
    <item name="OutputDatasheet"/>
  </layout>

</package>

Datasheets

Notice that we have added a <dataSheet> element to our <package>.

Along with familiar attributes like name and displayName, each dataSheet has a dataScope attribute. The dataScope attribute defines the position of the dataSheet in the library object hierarchy. By default, dataScope is automatically set to Scenario. Since we have not specified a dataScope for either of our datasheets, the values for these datasheets will be specified for every scenario in our library. Other options for dataScope are Project (when values specified once for each project) and Library (when values specified once for the entire library).

Each <dataSheet> must contain one or more <column> elements, where a column is defined by its name and dataType. You can define any number of additional columns, as required by your model.

Layouts

If you are only interested in using your package from the console, through the rsyncrosim R package or through the pysyncrosim Python Package, then your XML configuration file is complete. However if you would like your model inputs and outputs to appear automatically in the SyncroSim Library Explorer then you must update the <layout> element.

The <layout> element tells SyncroSim where to display all of the package's datasheets. In general you should include a <layout> element to contain each of your library, project and scenario datasheets by specifying the layout type as either Library, Project, or Scenario, respectively. Here we have added a layout to display our two new scenario-level datasheets.

Step 2: Modify the model script

You will now need to modify the R script from the previous article in order to both read your inputs into R from your SyncroSim library, and write your outputs from R back to your library. Below is a modified version of the model.R file to be included in your package's helloworld subfolder (from the previous article):

library(rsyncrosim)       # Load SyncroSim R package
myScenario <- scenario()  # Get the SyncroSim scenario that is currently running

# Load Scenario's input Datasheet from SyncroSim Library into R dataframe
myInputDataframe <- datasheet(myScenario, name="helloworld_InputDatasheet")

# Extract model inputs from this R dataframe and then do calculations
x <- myInputDataframe$x
a <- myInputDataframe$a
y <- x * a

# Setup an empty R dataframe ready to accept output in SyncroSim datasheet format
myOutputDataframe <- datasheet(myScenario, name="helloworld_OutputDatasheet")

# Copy output into this R dataframe
myOutputDataframe[1:length(y), "y"] <- y

# Save this R dataframe back to the SyncroSim library's output datasheet
saveDatasheet(myScenario,
              data=myOutputDataframe,
              name="helloworld_OutputDatasheet")

Step 3: Rebuild the package

Use the package Manager to rebuild the package using the new package.xml and model.R or model.py files shown above (see Step 4 in the Building a Package article).

Step 4: Set model inputs

  1. Start SyncroSim Studio.
  2. Install the helloworldTime package by navigating to File > Local Packages > Install from File... and select your helloworld.ssimpkg file. Click Open to install the package you built.
  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, double click on the helloworld library. Navigate to the Systems tab, and expand the Tools node. Select either the R or Python configuration options to check and/or set the location of your R or Python program executable. In this tab, also ensure that the Run directly option is selected.
  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. Edit the scenario inputs. Navigate to the Hello World (R/Python) tab. Select the Inputs tab and enter pairs of values for your Value for x and Value for a model inputs in the grid.

alt text

Step 5: Run the model

In the Library Explorer, right-click on this New Scenario and select Run again to run this scenario.

Step 6: View the results

  1. Once the run is complete, return to the Library Explorer. Expand the node beside the New Scenario to reveal a Results folder containing your results, then expand the node beside the Results folder to show the newly generated date/time stamped results scenario. Each results scenario contains a read-only snapshot copy of all your inputs at the time of your run, along with values for your model generated outputs.

alt text

  1. To view the details of the results scenario, double-click on it and navigate to the Hello World (R/Python) tab; you will find your calculated outputs in the Outputs window.

alt text

What's next?