The easiest way to create a simple model in JaamSim is to use the Graphical User Interface. However, once a model becomes more complex, it is often easier to edit the configuration file (CFG file) in a text editor. The configuration file is saved in plain text and has been designed to be human readable.
There are many advantages to a readable input file in plain text:
· Inputs can be easily reviewed and audited.
· Standard software for change control such as GIT can be used to track model inputs.
· Software for performing simulation experiments and optimisation can be developed by third-parties in other programming languages such as Python.
The recommended text editor is Notepad++, an open-source editor available for download at www.notepad-plus-plus.org.
A JaamSim input configuration file consists of a series of lines, akin to a scripting language. Each line consists of a combination of object names, keywords, and values contained within braces. One or more spaces are used to separate these elements. Braces are also used to denote sets of arguments within the outer braces required for arguments in general. Blank lines are ignored by JaamSim.
Lines beginning with a hash mark ('#') can be used to create comments to document the input files. If a comment extends for several lines, each line must start with a hash mark.
In JaamSim, an object is initialized by a Define statement. The statement contains Define followed by the object type, and the object name enclosed by braces. Multiple objects can be defined at the same time, provided that they are of the same type. For instance, the following two lines define respectively a single Arrow object and three Arrow objects.
Define Arrow { SingleArrow }
Define Arrow { Arrow1 Arrow2 Arrow3 }
Object instances can only be referenced after they have been defined.
Once an object is defined, its keyword values can be set using a command of the following form:
<object name> <keyword> { <value1> <value2> … }
where value1, value2, … is the list of values for the keyword separated by one or more spaces. For instance, the following line sets the colour of the Arrow1 object to be black:
Arrow1 Colour { black }
Multiple parameters for an object can be set in one line containing the object name followed by keyword and value pairs.
Arrow1 Colour { black } Width { 2 }
Inner braces are used for keywords that accept multiple input values.
Arrow1 Points { { 0 0 0 m } { 1 1 1 m } }
The readability of a configuration file can often be improved by spreading lengthy inputs over multiple lines. This can be done for an input that accepts an expression and for inputs that use inner braces, such as the RunOutputList keyword for Simulation and the Value keyword for TimeSeries.
For inputs that accept an expression, only the contents of the expression within the single quote marks can be spread over multiple lines. For example,
Server1 ServiceTime { 'this.obj.type == 1 ? 5[s] #some comment#
: 2[s] #another comment#' }
For inputs that use inner braces, new lines can start only between on pair of inner braces and the next. For example:
Simulation RunOutputList { { [Simulation].RunNumber }
{ [Server1].Utilisation }
{ [Queue1].AverageQueueTime/1[h] } }
The user can store input data in multiple files and then refer to these files in an input configuration file using Include statements. These statements refer to other input configuration files by filename and path, surrounded by single quotes:
Include '..\Base File\InputFile.cfg'
Include statements are particularly useful when only a few inputs are varied across many simulation runs. Include statements can be used to create incremental configuration files for additional runs that contain a base case configuration file :
Include '..\Base File\Basecase.cfg'
Arrow1 Width { 2.0 }
This example includes the contents of Basecase.cfg and modifies the already-defined object Arrow1’s keyword Width value to 2.0. Note that the changes from the base case configuration must appear after the Include statement. These simple configuration files are useful because it is easy to tell exactly how the configuration differs from the base case configuration.
Group objects bundle multiple objects together to simplify inputs. Instead of referring to a long list of objects, a single Group can be used instead. The Group may be used to set the value for a keyword for all members instead of setting the value for each member of the Group. Certain keywords also accept Group objects as values.
Table 8‑1 Group Inputs
Keyword |
Description |
List |
A list of names of the objects included in this list, enclosed by braces. |
The following example demonstrates the use of Groups:
Define Arrow { Arrow1 Arrow2 Arrow3 }
Define Group { ArrowList }
ArrowList List { Arrow1 Arrow2 Arrow3 }
ArrowList Colour { black }
In this example, a Group of three Arrow objects is created and each Arrow is set to the colour black.
By using the List keyword, a fourth Arrow can be added to the Group:
Define Arrow { Arrow4 }
ArrowList List { ArrowList Arrow4 }
ArrowList Colour { black }
The RecordEdits statement is used to preserve the organisation and formatting of a configuration file that has been prepared manually by the user.
It is usually best to construct a complex model manually using a text editor. These inputs are carefully formatted and organised, and include comments to document model design. However, once this material has been created, the easiest way to position the objects and to add graphics such as titles, labels, etc. is through the graphical user interface. If the model is then saved, all the formatting and comments would normally be lost.
JaamSim avoids this predicament with the RecordEdits statement. On saving, JaamSim copies all inputs before the RecordEdits statement line-by-line to the saved file, and then saves all the changes to the model using computer-written inputs. The following example illustrates this structure:
# Manually prepared inputs:
# - Everything before the RecordEdits statement is unchanged when JaamSim saves a file.
RecordEdits
# Computer written inputs:
# - Everything that appears after the RecordEdits statement is written by the computer.
The Save functionality in JaamSim is disabled when an input file is loaded without a RecordEdits statement. In this case, the Save As operation adds a RecordEdits statement to the end of the original configuration file and then writes out the new inputs.