Running GoldSim from the Command Line

In some cases, it may be useful to bypass GoldSim user interface and run GoldSim directly from the command line.

This, for example, could be done by selecting Run from the Windows Start menu, which displays the following dialog:

You must enter the full path to the GoldSim executable (which may, of course, be different than that shown above), followed by the GoldSim file that you want to open. If no filename is specified, GoldSim opens a new file.

Note: If no path is specified for a filename, GoldSim looks in the last directory from which a GoldSim file was opened. Hence, it is highly recommended that you provide a full path for the filename.

The primary reason for running GoldSim from the command line is to take advantage of a number of command line parameters that cause GoldSim to execute in a specific manner.

The command line parameters are summarized in the following table. Note that the parameters are entered after the executable and before the model file name.

Parameter	Description	Comments
-show name	Opens GoldSim and jumps to the specified Container or Dashboard	Used if you want a GoldSim model to simply open immediately and display the contents of a specific Container or Dashboard. If this parameter is used to reference a Container name that is used multiple times within a model (within localized Containers), GoldSim opens the first Container with the specified name found while searching downward through the containment hierarchy.
-r -run	Opens the GoldSim file and immediately runs the simulation.	In this situation, GoldSim automatically skips the “Ready” state and starts the simulation.
-getdb [date]	Executes a global database download for all elements linked to databases.	The date is only required for Extended GoldSim databases. The date must be specified in local format and be enclosed in quotes (e.g., “7 March 2013”).
-x	Closes GoldSim after all other options have been executed.	Note that unless auto-save is enabled (in the Options dialog), or the –sv parameter was used, the GoldSim model file will NOT be saved when the application is closed.
-sv [filename] -save [filename]	Saves the model file using either the optionally provided output filename, or the input filename (if an output file is not provided).	This option can be used to run and save a model, or to open a model and save it in a newer version of GoldSim.
-dpclient	Opens GoldSim in Client Mode.	Used when running models on multiple processors using GoldSim’s distributed processing features (GoldSim Distributed Processing Module). This command cannot be used with any other parameters.
-d “element.input=expression” -data “element.input=expression”	Inserts the provided expression into the specified input for the specified element.	This parameter allows you to change the contents of an input field for any element in GoldSim using the command line. The input can be omitted (only the element name needs to be specified) if the input name is “Definition” (e.g., for Data and Expression elements). This parameter is particularly useful if you want to stack a number of runs in a batch file, with each run changing one or more element definitions.
-starttime “date[time]”	Resets the Start Time	The time is optional. The date/time string can take on any of the following formats: "25 January 1996" "January 25, 1996 8:30:00" "8:30:00 Jan. 25, 1996" "1/25/1996 8:30:00" Time can be specified in military (24 hour time) or 12 hour time using PM and AM.
-endtime “date[time]”	Resets the End Time	-endtime and -duration are mutually exclusive (only one can be set). The -endtime flag must be used in conjunction with the -starttime flag. The time is optional. The date/time string can take on any of the following formats: "25 January 1996" "January 25, 1996 8:30:00" "8:30:00 Jan. 25, 1996" "1/25/1996 8:30:00" Time can be specified in military (24 hour time) or 12 hour time using PM and AM.
-duration “time expression”	Resets the Duration using the provided expression	-endtime and -duration are mutually exclusive (only one can be set). Time expression should use GoldSim’s built-in units, and must have dimensions of Time.

Examples of how some of these parameters would commonly be used are provided below. Note that these parameter strings would follow the name (and path) of the GoldSim executable (goldsim.exe).

Command line	Comments
-x –sv test1.gsm	Opens test1.gsm, saves it, and closes GoldSim. Useful, for example, if you want to convert test1.gsm to the latest GoldSim version.
-x –sv test2.gsm test1.gsm	Opens test1.gsm, saves it as test2.gsm, and closes GoldSim. Only the destination model (test2 in this case) is saved. Useful, for example, if you want to convert test1.gsm to the latest GoldSim version, but preserve the original file.
-r test1.gsm	Opens test1.gsm, executes pre-run checks and starts the simulation. GoldSim remains open after the simulation. The model file is only saved if auto-save is enabled in the Options dialog.
-r –sv test1.gsm	Opens test1.gsm, executes pre-run checks and starts the simulation. At the end of the simulation, the model file is saved. GoldSim remains open after the simulation.
-r –sv –x test1.gsm	Opens test1.gsm, executes pre-run checks and starts the simulation. At the end of the simulation, the model file is saved. GoldSim is then closed.
-r –sv test1res.gsm test1.gsm	Opens test1.gsm, executes pre-run checks and starts the simulation. At the end of the simulation, the model file is saved to test1res.gsm. GoldSim remains open after the simulation.
-dpclient	Starts GoldSim in Client mode. This command cannot be used with any other parameters.

Several points should be noted regarding the use of the –d (-data) command:

• The argument to this command must be enclosed in quotes.

• Units must be specified if the input has dimensions.

• More than one input can be defined in a command line. Note, however, that Windows limits the length of a command string (to 8191 characters).

• If a Data element is connected to a Dashboard control, the Dashboard will always take precedence. As a result, if you want to control an element via a command line, it should not be connected to a Dashboard control.

• The –d parameter will only find global elements. If an element is located within a localized Container, it will not be found.

Examples of the use of the –data command are provided below:

Command line	Comments
-d “Data1=5m3”	Puts the value of 5 m3 into the input of element Data1. This would only be valid if Data1 had an input named Definition (e.g., if it was a Data element or Expression element).
-d “Pond.Initial Value = 10m3”	Puts the value of 10 m3 into the Initial Value input of element Pond (in this case, a Reservoir).
-d “X = if(etime>5day,1,2)”	Puts the expression if(etime>5day,1,2) into the input of element X. This would only be valid if X had an input named Definition (e.g., if it was a Data element or Expression element).
-d “Data1=5m3” –d “Data2=5sec”	Puts the value of 5 m3 into the input of element Data1, and 5 sec into the input of element Data2. This would only be valid if Data1 and Data2 had an input named Definition (e.g., if they were Data or Expression elements).

Several points should be noted regarding the use of the –starttime, -endtime and -duration commands:

• The arguments to these commands must be enclosed in quotes.

• Units must be specified if the input has dimensions.

• The commands can only be used in the following combinations:

o -starttime only (Elapsed Time, Calendar Time or Static models)

o -starttime and -duration (Elapsed Time or Calendar Time models)

o -starttime and -endtime (Calendar Time models only)

o -duration only (Elapsed Time or Calendar Time models)

Examples of the use of the –starttime, -endtime and -duration commands are provided below:

Command line	Comments
-starttime “1/1/2021”	Sets the Start Time to 1 January 2021
-starttime "25 January 2021 18:30:00"	Sets the Start Time to 25 January 2021 at 6:30 PM
-starttime "25 January 2021 6:30:00 PM"	Sets the Start Time to 25 January 2021 at 6:30 PM
-starttime “1/1/2021” -duration “100 days”	Sets the Start Time to 1 January 2021and the Duration to 100 days
-starttime “1/1/2021” -endtime “1/1/2022”	Sets the Start Time to 1 January 2021 and the End Time to 1 January 2022
-duration “100 days”	Set the Duration to 100 days (using the defined Start Time and replacing the End Time

In most cases, it is likely that you will want to “stack” a number of GoldSim runs by creating a batch file that you run from the command line. However, if you simply stack command lines and then run a batch file, all GoldSim calls would be launched in parallel (e.g., if you had 10 command lines that ran GoldSim, 10 instances of GoldSim would open and run simultaneously).

To avoid this problem and force the commands to run in series, you can use the Start/Wait command provided by Windows. An example batch file that utilizes this is shown below:

CD c:\Program Files (x86)\GTG\GoldSim 11.1

Start /wait GoldSim.exe -r -sv r1.gsm -d "InputA=10m" -x “c:\runs\input.gsm”

Start /wait GoldSim.exe -r -sv r2.gsm -d "InputA=20m" -x “input.gsm”

Start /wait GoldSim.exe -r -sv r3.gsm -d "InputA=30m" -x “input.gsm”

Start /wait GoldSim.exe -r -sv r4.gsm -d "InputA=40m" -x “input.gsm”

The first line simply sets the directory to the location of the GoldSim executable. The next line opens a GoldSim model called input.gsm. By specifying the path here, this sets the path for all input and output files in the remainder of the batch file. GoldSim changes the value of InputA to 10m, runs the model and saves it as r1.gsm. GoldSim then closes. After closing, the next GoldSim command is implemented (open input.gsm again, change InputA to 20m, run and save the model to r2.gsm). This continues until all four GoldSim runs are complete.