...
...
...
...
...
...
...
...
...
...
...
...
...
...
The RiverSystem.CommandLine.exe provides a mechanism to run existing projects without the Source interface. It is possible to modify or change the behaviour of the project from the command line, by changing the values of functions. Results can be returned for recorded items or functions within the project.
...
...
...
Functions can be used to manipulate the model in this way, either before the start of the simulation, or before each time-step.
Figure 1. Manipulating functions
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.
| Info | ||
|---|---|---|
| ||
| Note: All characters in the command line are case-sensitive. |
Loading and running
You can run a project in the following modes:
- Standalone mode – the project loads; the simulation runs with a single line command:
| Code Block |
|---|
RiverSystem.CommandLine.exe -p C:\Temp\ExampleProject.rsproj |
- Client/server mode – one command line runs projects. It does anything except for loading a project until a second command line is run in client mode. In this way, multiple runs can be completed with the server loading the project only once. It also enables the server to run on a different machine to the client. The examples provided assume a client/server mode, illustrating the calls made by the client. They could also work in standalone mode. Refer to Advanced configuration options for two options available in this mode.
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:
| Code Block |
|---|
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.):
| Code Block |
|---|
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.
| Info | ||
|---|---|---|
| ||
Note: When working with functions in the command line, ensure that functions are referenced by their full name to avoid errors or run failures. The syntax for referencing a function by its full name is $Folder.Function. For example, use: RiverSystem.CommandLine.exe -v "$Folder1.Function1=10" |
Use the -v argument to assign parameter values:
Set the values:
Code Block RiverSystem.CommandLine.exe -m Client -v "$metaParam=2.5"- Set multiple
...
...
Server
This command starts a basic server on the same machine as the client:
| Code Block |
|---|
>RiverSystem.CommandLine.exe --mode server |
...
...
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":
| Code Block |
|---|
>RiverSystem.CommandLine.exe --mode server --d "C:\ProjectDir" |
...
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/):
| Code Block |
|---|
>RiverSystem.CommandLine.exe --mode server -d "C:\Users\man25n\Documents\eWater Source Projects" -a "net.tcp://192.168.1.5:8080/myWaterService/" |
...
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:
| Code Block |
|---|
> RiverSystem.CommandLine.exe --mode client --d "C:\ProjectDir" |
...
Additional examples of running Source using a DOS batch file, a Python script or an R script can be found here.
...
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):
| Code Block |
|---|
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):
| Code Block |
|---|
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.
...
...
Display option commands
...
Function
...
Example
...
-a, --address...
-a "net.pipe://localhost/PipeReverse" or "net.tcp://localhost:8523/eWater/Services/RiverSystemService"
...
-b, --baseSIUnits...
--baseSIUnits...
-c, --recording...
-c "c:\StateFiles\state.txt"...
-d, --directory...
-d "c:\ProjectFiles"...
-e, --timeout...
-e 2000...
-f, --settingFile...
-f "settings.txt"...
-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...
Path to the project, or project name on server and optional scenario within that project, DateTime values to override the default start and end times of the loaded scenario and data source input set to run.
...
-p "projectName.rsproj", or to specify the scenario within the project
-p "c:\somePath\projectName.rsproj;someScenarioName", or to set the run period
-p "c:\somePath\projectName.rsproj;;1/1/2011;31/12/2011", or to specify a Scenario Input Set
-p "c:\somePath\projectName.rsproj;;;;ScenarioInputSetName" or when using child input sets
-p "c:\somePath\projectName.rsproj;;;;ScenarioInputSetName\ChildInputSetName"
...
-r, --results...
Which results to return. This can appear multiple times.
| Info | ||
|---|---|---|
| ||
| Note: By default, all recorded results are saved into the specified output file. When this options is used, it only allows you to reduce the number of results saved out. Requested results must be set to record in the project file. To specify the output file name, save the result to a file with a .res.csv extension. Use the column name for the time series. |
...
-r "someResult" -r "someOtherResult"...
-s, --step...
--step 1...
-t, --reset...
--reset...
-u, --current...
--current...
-v, --value...
Set the value of a Function (also called meta-parameter for calibration)
...
-v "$metaparam=25", or -v "$anotherMetaParam=2.3"...
-y, --saveAs...
...
...