Command Line Runner

RiverSystem.CommandLine.exe is included with Source.

The command line is used where it is impractical to run Source from the main user interface, such as:

• For batch runs, where Source is run many times with a range of different parameter values; or
• Optimisation scenarios; and 
• When integrating Source with other models or business systems.

The command line can be used in either a standalone (in-process) mode or in a client/server configuration. When run in client/server mode, the Source project is loaded and run at the server side, with parameters provided by and results returned through the client. In this way, the server can be used for many runs of the same project, without needing to reload the project file each time.

Configuring a scenario from the command line

Any valid Source project can be used with the command line. To modify behaviour of the model, you must configure functions, which can be achieved using the command line.

Figure 1 illustrates the process of manipulating the operating target for a storage from the command line, in this case, manipulating a function, $x. This must first be specified in terms of a function, which must reference $x. Functions can be used to manipulate the model in this way, either before the start of the simulation, or before each time-step.

The MetaParameter Explorer can be used to attach functions directly to model variables for situations where the Function Editor has not been enabled by default.

Working with the command line

This section describes how to load, run, retrieve results, and modify parameters using the command line.

Loading and running

You can run a project in the following modes:

RiverSystem.CommandLine.exe -p C:\Temp\ExampleProject.rsproj

Retrieving results

By default, all recorded items are returned, as configured from within the Source application (Running scenarios). Alternatively, you can specify specific items to record by using a command line argument:

RiverSystem.CommandLine.exe -m Client -r "Inflow 1/Inflow Volume"

The command after -r refers to the exact name of the recordable item as it appears in Source, ie Node Name/Variable. In this case, the variable, Inflow Volume, of the inflow node will be recorded.

In client/server mode, results are always computed on the server, but returned through the client. By default, results are displayed on the console (in both standalone and client modes), but it is possible to save the results directly to a file using the following command (file name is resultsfilename.res.csv.):

RiverSystem.CommandLine.exe -m Client -o resultsfilename.res.csv

Modifying parameters

To modify parameters in the model, they need to be set up as functions. This can be done in one of three ways:

• Using the Function Manager directly;
• Creating a function and Adding function usages manually; or
• Using the Calibration Wizard. Refer to Working with metaparameters for more information.

RiverSystem.CommandLine.exe -v "$Folder1.Function1=10"

Use the -v argument to assign parameter values:

• Set the values: 

  RiverSystem.CommandLine.exe -m Client -v "$metaParam=2.5" 

• Set multiple parameter values:

RiverSystem.CommandLine.exe -m Client -v "$metaParam=2.5" -v "$anotherMetaParam=3.0".

Examples

The following set of examples indicate the type of commands used to run projects in the two modes.

Inprocess

The next example runs the project from start to finish and puts all recorded values in the file ‘test.res.csv’.

>RiverSystem.CommandLine.exe -p "C:\ProjectDir\test.rsproj" -o test.res.csv
Loading 100%
Meta-Parameters:
+ $inflow
-r "Forest\Catchment for node #2\Quick Flow\Flow"
+ Straight-Through Routing\Default Link #1\Upstream Flow Volume
+ Straight-Through Routing\Default Link #1\Downstream Flow Volume
+ Straight-Through Routing\Default Link #1\Mass Balance
+ Inflow\Inflow 1\Upstream Flow Volume
+ Inflow\Inflow 1\Downstream Flow Volume
+ Inflow\Inflow 1\Inflow Volume
+ Inflow\Inflow 1\Mass Balance
+ Gauge\Gauge 2\Upstream Flow Volume
+ Gauge\Gauge 2\Mass Balance
+ Global Expressions\$inflow\Value
Running 100%

Server

This command starts a basic server on the same machine as the client:

>RiverSystem.CommandLine.exe --mode server

The service is ready at net.tcp://localhost:8523/eWater/Services/RiverSystemService
Press Enter to stop the service.

In this command, a basic server runs on the same machine as the client. This server will look for project files passed from the client in the directory "C:\ProjectDir":

>RiverSystem.CommandLine.exe --mode server --d "C:\ProjectDir"

The service is ready at net.tcp://localhost:8523/eWater/Services/RiverSystemService
Press Enter to stop the service.

The following command will start up a server, load a project from the directory C:\Users\man25n\Documents\eWater Source Projects using the address specified (net.tcp://192.168.1.5:8080/myWaterService/):

>RiverSystem.CommandLine.exe --mode server -d "C:\Users\man25n\Documents\eWater Source Projects" -a "net.tcp://192.168.1.5:8080/myWaterService/"

Press Enter to stop the service.

The address consists of the communication protocol (net.tcp) and the name of the end-point. For a machine that runs both the client and server, the address of the end-point must match.

Client

The following command assumes that the server is already running from the previous example:

> RiverSystem.CommandLine.exe --mode client --d "C:\ProjectDir"

The service is ready at net.tcp://localhost:8523/eWater/Services/RiverSystemService.

Additional examples of running Source using a DOS batch file, a Python script or an R script can be found here.

Client Server interaction

The service will keep the current state after the client command completes. Projects that are loaded, steps executed and parameters set are still in effect on the server until changed. The client can change this by loading another project or changing state in some other way. This allows for very complicated interactions. 

A simple situation is to load a project and run it multiple times with changing values. This would be accomplished by first starting a server

> RiverSystem.CommandLine.exe -mode server 

Then loading the project in the server from the client in another window while the server is running.

> RiverSystem.CommandLine.exe -mode client -p c:\test.rsproj -s 0 

NOTE: the "-s 0" in the command above will stop the project from running by default. The project will load and wait, not performing any timesteps ("-s 0")

Next we set some parameter on the loaded project

> RiverSystem.CommandLine.exe -mode client -v "$metaParam=2.5" -s 0

Then run the project (running is the default action of the commandline so no extra paramaters need to be specified)

> RiverSystem.CommandLine.exe -mode client 

Executing the project again with a different value for the parameter can be performed as follows.

> RiverSystem.CommandLine.exe -mode client -v "$metaParam=7.5" -s 0
> RiverSystem.CommandLine.exe -mode client 

OR just

> RiverSystem.CommandLine.exe -mode client -v "$metaParam=7.5" 

which will set the parmeter and execute the model (the default operation because no "-s 0" is present to stop the execution)

Advanced configuration options

In the client/server mode, there are two command line windows and RiverSystem.CommandLine.exe is run twice:

• XML file: RiverSystem.CommandLine.exe.config – This file contains a section called <system.serviceModel> that can configure hundreds of options for the services and client including transport types, maximum data size, security etc. These are the default options used when running in client or server mode. The location of the server defined in this file, by default, is "localhost" which means the server and client are configured to run on the same machine.
  Option A - A project is loaded when the server starts (first command line) and is run in response to a client call (second command line):

RiverSystem.CommandLine.exe -p C:\Temp\ExampleProject.rsproj -m Server
RiverSystem.CommandLine.exe -m Client

• For testing purposes and ad-hoc configuration, two main command line options are also provided to configure the location/type of the server and message time out. When run in this mode the <system.serviceModel> section of the RiverSystem.CommandLine.exe.config file may need to be deleted as creating two servers of the same type is not supported. This means that the net.tcp server on localhost defined in the exe.config file will stop you creating an adhoc server of the same type.
  Option B – In the example below, the server starts without loading any project (first command line). The client then specifies the project, which gets loaded onto the server and runs immediately (second command line):

RiverSystem.CommandLine.exe -m Server
RiverSystem.CommandLine.exe -m Client -p C:\Temp\ExampleProject.rsproj

Option descriptions

Notice in the examples that the command line contains various options, which result in different outputs. The function of these options is provided in Table 1. Note that these are optional extras.

Table 1. Command Line Runner Single Analysis (options)

-a, --address

-a "net.pipe://localhost/PipeReverse" or "net.tcp://localhost:8523/eWater/Services/RiverSystemService"

-b, --baseSIUnits

--baseSIUnits

-c, -rec, --recording

-c "c:\StateFiles\state.txt"

--cp, --configurationproperty

--configurationproperty "name=value"

-d, --directory

-d "c:\ProjectFiles"

-e, --timeout

-e 2000

-et, -endtime

--endtime "1/1/2011"

-f, --settingFile

-f "settings.txt"

-?, --help

-?

--is, --inputset

--inputset "ScenarioInputSetName"

--inputset "ScenarioInputSetName.ChildInputSetName"

--ip, --inputSetProperty 

-l, --loadPlugin

-l "plugin.dll"

-m, --mode

-m Client or -m Server

-o, --output

-o "output.res.csv" for CSV or -o "output.nc" for NetCDF etc.

-p, --project

-p "projectName.rsproj", or to specify the scenario within the project

-md, --ProjectMetadata

-r, --results

-r "someResult" -r "someOtherResult"

--resultsOutputMode

ClientNamedFormat

ServerNamedFormat

NoOutput

--resultsOutputMode NoOutput

-o "..\cmdlineResult.res.csv" --resultsOutputMode ServerNamedFormat

-rc, --runconfiguration

-rc "Flow Calibration"

--scenario

--scenario "New Scenario"

--starttime

--starttime "1/1/2011"

-s, --step

--step 1

-t, --reset

--reset

-u, --current

--current

-y, --saveAs

-y "C:\ProjectFiles\newProject.rsproj"

--saveAnalytics

--saveAnalytics
--saveAnalytics "C:\\foldername\\analyticsfilename.anl.xml"