The Simple Script Wrapper (SSW) is a software component developed at Kansas State University. It provides a simple way to link models written in scripting languages such as MATLAB, Scilab, and Python to Open Modeling Interface (OpenMI) components. Creating a linkable script requires 2 steps: (1) write a properties file that describes the model and (2) add 3 functions to the model script that are responsible for initializing the model, performing a single time step, and shutting down the model.
Bulatewicz, T., A. Allen, J.M. Peterson, S. Staggenborg, S.M. Welch, and D.R. Steward, The Simple Script Wrapper for OpenMI: Enabling interdisciplinary modeling studies, Environmental Modelling & Software, 39, 283-294, 2013. https://krex.k-state.edu/dspace/handle/2097/15288
The sample consists of 3 models, each written in a different scripting language. The models are simplifications meant only for demonstration. The models represent weather, crop production, and groundwater. The weather model is implemented in Python and generates random precipitation data that is provided to the agricultural model. The agricultural model is implemented in MATLAB and calculates crop water consumption based on a constant need and variable precipitation. The agricultural model calculates the groundwater pumping rate as the difference between the crop water need and the precipitation received. This pumping rate is provided to the groundwater model. The groundwater model is written in Scilab and calculates the total groundwater storage. The models are configured to operate on an annual time step over a 4-county area (i.e. 4 elements in the element set).
To run the sample linked model, the following software is required: OpenMI Configuration Editor 1.4, MATLAB R2010 or later, Scilab 5.4 or later, and Python 2.7. If these applications are not installed to their default locations, it is necessary to specify the install path in the Component.omi files.
Each model consists of 3 core functions: sswInitialize, sswPerformTimeStep, and sswFinish. For MATLAB and Scilab each of these is in a separate script file and for Python they are combined into a single Model.py file. These functions contain the scripting statements that setup the model, perform a single time step, and clean up. Global variables can be shared among the functions (although be sure to use different global variable names if you are using multiple Scilab models within a single composition).
The 3 functions obtain the input from other models, and provide output to other models (as well as obtain state information such as the current simulation time) by calling a special set of SSW functions:
sswGetInput(quantityName) Returns values from other componentssswSetOutput(quantityName, value) Saves values for other componentssswGetCurrentTime() Returns the current simulation timesswGetScriptFolder() Returns the path to the script folderThe quantityName is the name of the quantity as it appears in the Component.xml file. The Component.xml file contains metadata about the model, such as the time span that it can simulate and the list of input and output exchange quantities.
The sswPerformTimeStep() function typically has 3 parts that (1) call sswGetInput() to obtain inputs from other components, (2) calculates new values of its state variables for the current simulation time, and then (3) calls sswSetOutput() to save the new state variable values so that they will be available to other components.
The API script functions in Table 1 are automatically generated by the SSW when a model script is loaded into the Configuration Editor. When writing and testing a model, it is helpful to be able to run the model by itself, outside of the Configuration Editor. This is possible through the use of placeholder functions that take the place of the API functions. Each of the models has a set of placeholder functions in the Solo folder of each model, and the Solo script file can be executed to run the model from the console of MATLAB, Scilab, or Python. The Solo script mimics the way that the SSW calls the 3 core functions.