VMGSim Script Runner

VMGSim is well known for its clear and intuitive interface. This is highly appreciated during the model building stages but working with a user interface is sometimes limiting when analysing bulk results and the information has to be processed and laid out in very specific formats.

Imagine you have a case, in Steady State or Dynamics, that needs to be run in one hundred different scenarios. The “Case Study” tool is really powerful for this, but it may not provide the desired layout of results if hundreds of variables are being changed or tracked from one scenario to another. Take the example from Flow Assurance, in which large amounts of data in very long pipes need to be initialised for each scenario.  Another example is when many cases need to be run for a long time in order to obtain a representative set of results in a Dynamic simulation.


Luckily, VMGSim exposes a variety of ways to customize and automate the simulation runs outside the user interface such as COM Automation, a powerful Excel Add-In and a command line. This article focuses on the command line and the input files that can be used to interact with VMGSim.

Being command driven means that virtually every action done with the mouse in front of the screen is converted to a command and sent to the Simulation Engine in the background. This also means that a list of commands can be wrapped into a text file (usually with .tst extension) and be sent to the Simulation Engine to perform complex tasks. We refer to these text files as “Script Files”.

At this moment the reader should have already guessed that various Script Files might be put in a queue and request VMGSim to process them one after the other. This is what the small application presented in this article does.

“VMGSim Script Runner” is an application that will let you build and run a sequence of Script Files and automatically put the results in text files and/or save the generated VMGSim cases. It is so simple that a single screenshot captures it all, however, it has access to all the power provided by VMGSim programmatically.


What It Does

Everything in this application happens around the Main Script Sequence. This sequence should always start loading an existing VMGSim case or creating a new blank VMGSim case. After that, any number of Script Files (.tst) may be added or another (blank or not) VMGSim case loaded. Each entry in the main sequence may be duplicated, removed and/or reordered using the corresponding buttons to easily create repetitive tasks with the minimum number of clicks.

Each entry in the Main Sequence has a few simple, yet powerful, options:

  • Save VMGSim Output - Will create a text file (.out) containing all the messages returned by VMGSim.
  • Save VMGSim Case - Will save the currently loaded VMGSim after running the Script File on it. This way, you can open the case as it was right after the Script had been run on it.
  • VMGSim StripCharts - For cases in Dynamics, this option will populate the Strip Charts inside VMGSim. This option is only useful if the VMGSim case is also saved (previous option) and the Strip Charts need to be inspected later.
  • External StripCharts - For cases in Dynamics, this option will populate the Strip Charts in external text files (.csv). This option is useful if you don’t really want to save the case after running it but still want to inspect the transients captured during the simulation.

Once the Main Sequence is built, the destination folder for all the files generated needs to be specified. The “Settings” tab contains a few default options for this destination folder to save you a few more clicks.

Now, with a correct script sequence and a destination folder, the button “RUN SCRIPT SEQUENCE” may be clicked. The “Log” will provide information as the sequence goes on and report of any problem encountered during the run. The “Settings” tab let you select what messages are displayed in the log, but the more messages displayed, the longer it takes to run the sequence. This may have a strong impact on Dynamic cases if the log needs to report something on every single step of the simulation.


Let’s take the screenshot shown above and describe what the ScriptRunner would do in that case:

  1. An empty blank case in VMGSim is created.
  2. A script called “Script_BuildSSCase.tst” is run. This script will add a few pipes, a pump and a reactor with the appropriate specs to the previous blank case and tell VMGSim to solve it. The “Save VMGSim Case” option is checked, so the case will be saved as a VMGSim file when the script finishes.
  3. A script called “Script_Results.tst” is run. This script simply contains the names of some variables we are interested in. Upon reading the name of a variable in a script, VMGSim simply returns its value and units as text. We call this type of scripts “Results Scavenger” and it will not change the case but simply get numbers from it –that is why we don’t need to save the VMGSim case here. However, since the “Save VMGSim Output” option is checked, we will get all these figures in a text file.
  4. A case called “Dyn_Case.vmp” will be loaded in this step of the sequence.
  5. A script called “RunTo5000s.tst” is run. This script will tell VMGSim to run the model for 5000 seconds. We do not really want to save the case after running it as we have not changed anything. However, we want to keep the generated StripCharts in a text file for later analysis of this base case.
  6. The same case called “Dyn_Case.vmp” will be loaded again in this step of the sequence. This way, we have the case before running it (in step 5).
  7. A script called “Script_ChangeInletConditions.tst” is run. This script changes some inlet conditions in our dynamics model. Since we want to keep the case before running the integrator, the “Save VMGSim case” option is checked. We can reuse this case with the new inlet conditions anytime later.
  8. The same script called “RunTo5000s.tst” is run again, but now with the modified inlet conditions. This time we want to keep the case after the run (“Save VMGSim Case” checkbox), we want the Strip Charts to be generated inside the VMGSim case (“VMGSim StripCharts” checkbox) and we also want the same Strip Charts to be put in a text file (“External StripCharts” checkbox).

Upon hitting the “RUN SCRIPT SEQUENCE” button, all the files will be generated in the specified folder without any user intervention at all. Even if there’s an error in any of the files, the ScriptRunner will skip the file and try to go on with the sequence and leave traces of the error in the log.

Final Comments

This simple application can be used for several different tasks:

  • Create many complex cases with huge amounts of data input with ease.
  • Run simulations and extract the results without generating new VMGSim files.
  • In Dynamics, long run cases may be left unattended overnight and the result files will be waiting for you on your hard drive the next day.
  • Export your results to external software with a few clicks.

Finally, note that this application has been built following the recommendations in the documentation folder of VMGSim. The tools available in any regular VMGSim installation allow anyone to build an application like this one. Furthermore, only simple commands are needed inside the Script Files to assign values to variables and read results from them in the shape of:

/FlowsheetName.VariablePath.VariableName = XXXX Units

Explore the “VMGSimCOMAutomation” manual shipped with your VMGSim installation and learn how easy is to programmatically run VMGSim from a custom created application or from other applications.

 Please contact your local VMG office for more information.

Nicolau Goula i Masllorens, MSc., BSc., VMG Europe

To Top