Note: This is documentation for version 5.4 of Source. For a different version of Source, select the relevant space by using the Spaces menu in the toolbar above

Using the command line for Insight

Insight can be configured, set up (using a settings file) and run using the command line. 

When using the command line, you must keep the command prompt open until the optimisation has been run and is complete.

Additional help for the command line is also available. Once in the Insight directory, enter the following:

Insight.Optimiser.Console.exe --help

Creating the settings file

The settings file can be created in a text editor, such as Notepad, saved as a .txt file (such as Example_InsightSettings.txt) and must include the information shown in Table 1.

Table 1. Information required to create a settings file
Information requiredExample
Location of the Source project file
project C:\Insight\test\Example_project.rsproj
List of the objectives, using the Functions in the Source project
ExportedOutput $reliabilityNeg
ExportedOutput $unitcost
ExportedOutput $Yieldneg
List of decision variables, using the Functions in the Source project, along with their constraints
real $pipecapacity 0 200
real $demand 0 100
real $treatmentcapacity 0 100
Optional parametersExample
Cache results file from previous run(s) to avoid re-running runs using the same decision variables as previously
cache C:\Insight\test\Example_Cache.csv
Constraints
constraint $costConstraint
Advanced options - also optionalExample
SeedSeed 0.5

Real Var Crossover Probability

GAExpert RealVarCrossoverProb 0.9
Real Var Mutation ProbabilityGAExpert RealVarMutationProb 0.5
Integer Var Crossover ProbabilityGAExpert IntegerVarCrossoverProb 0.9
Integer Var Mutation ProbabilityGAExpert IntegerVarMutationProb 0.5
Crossover Distribution IndexGAExpert CrossoverDistribIndex 5
Mutation Distribution Index

GAExpert MutationDistribIndex 10

The values above are the default values. They should only be changed by expert users who know what they are doing. Invalid values may cause NSGA to fail.


Note: To view a list of all available Functions in a Source project, use the following command:

-configurationOption :C:\Insight\test\Example_InsightSettings.txt

Configuring the optimisation run

Once a settings file has been created, specify the following (shown in Table 2) in the command line to configure the optimisation run.

Table 2.  Information required to configure an optimisation run
Information requiredExample
Run the Insight executable file
Insight.Optimiser.Console.exe
Location of Insight settings file
--configurationOption "C:\Insight\test\Example_InsightSettings.txt”
Number of cores / endpoints to use
--source 2
Number of generations
--generations 6
Population size
--population 100
Output file name
--output "C:\Insight\test\Example_CommandLineResults_6x100.csv"

There are a number of optional parameters which may be specified on the command line as shown in Table 3.

Table 3.  Optional parameters for an optimisation run
Optional informationExample

Output cache file name

File can be used as an input to subsequent runs by specifying the cache option in the Insight configuration file

--cacheOutput "C:\Insight\test\Example_Cache.csv"
Seed
--seed 0.5

Progress message format string for
string.Format(fmt, CurrentGeneration, IndividualsCompleted, TotalGenerations, PopulationSize, ProgressPercentage)

--progressFormat "##Progress##:{0}:{1}:{2}:{3}:{4}"
Suppress message to StdOut other than formatted progress messages and results (if output not specified)
--quiet
Note: Whenever specifying a file outside the Insight folder, you must include the full path.

Setting up server endpoints 

Server endpoints allow you to run the optimisation across several machines simultaneously. It is recommended to discuss the use of endpoints with your IT department should you wish to choose this option. They can be set up either manually, or using the Powershell script. These are discussed separately next.

Note the following about server endpoints:

  • Each individual machine must have Source installed; and
  • The project file will need to be located on a server where all machines can access it.
  • If you are using a Windows 7 machine as an endpoint, you may need to relocate Source out of the Program Files folder to avoid folder access issues. For example, move Source to C:\Source 4.1.

Manual setup of individual machines as endpoints

For each individual computer you wish to use in the optimisation, you will need to set it up as an endpoint(s). This is setup using the command line on each machine.

  1. Locate the IP address (type ipconfig in the command prompt) or machine name (in the Properties section of My Computer) for each computer you are going to use in the optimisation;
  2. In the command prompt, change the directory to the location of Source (ie. where Source in installed); and
  3. Setup the endpoint using the endpoint setup command. For example, in the following case, 8593 is the unique identifier for the endpoint: 
RiverSystem.CommandLine.exe -m server -a net.tcp://localhost:8593/insight

A message will then appear indicating that setup is complete.

Note: Windows may request permission to allow access to the endpoint. Click OK to grant permission.

To use additional cores on an individual machine, you will need to set up multiple endpoints. 

If you wish to open up another endpoint for the same machine, open up another command prompt, change to the Source directory, and enter a similar command, this time with a different endpoint identifier. For example: 

RiverSystem.CommandLine.exe -m server -a net.tcp://localhost:8594/insight 

Setting up endpoints using PowerShell script

You can also set up endpoints using the included PowerShell script.

Note: If Source is installed in your Program Files folder, you will need to run PowerShell as administrator every time you set up endpoints. In the Start menu, right click on the PowerShell icon and choose Run as Administrator.

Complete the following on every machine that you wish to set up as an endpoint/s:

  1. Ensure that the RunSourceServersForInsight.ps1 file is in the same folder as RiverSystems.CommandLine.exe;
  2. Open PowerShell (Click on the Start menu (Windows 7), search for PowerShell, and press Enter);
  3. This method of setting up endpoints requires a change to the execution policy for each machine you wish to use as an endpoint. At the PowerShell command prompt, enter Set-ExecutionPolicy RemoteSigned. You will be asked to confirm the change (you can read more about this by selecting the relevant help topic). Choose Yes. This needs to be done only once;
  4. Change the directory to the location of the RunSourceServersForInsight.ps1 file;
  5. Run the PowerShell script with ./RunSourceServersForInsight.ps1; and
  6. The PowerShell script has automatically set up endpoints for you. Make a note of each endpoint, as these will be required when running the optimisation. Repeat this step across every machine that you wish to use as an endpoint. By default, the PowerShell script sets up two endpoints. To change the number of endpoints on the same computer, add the number of endpoints after the run command. For example: ./RunSourceServersForInsight.ps1 4 indicates 4 endpoints.
Note: To find out more about execution policies, enter help about_execution_policy at the PowerShell command prompt.

 Finally, create an endpoints setting file using a text editor. Using the IP addresses or machine names (as located previously), specify the endpoints manually or via PowerShell. An example of such as file is shown below:

net.tcp://192.168.1.2:8593/insight
net.tcp://192.168.1.2:8594/insight
net.tcp://192.168.1.73:8595/insight
net.tcp://192.168.1.73:8596/insight

Running the optimisation

Once the settings file has been configured (along with endpoints if you are using them), you set up the optimisation run using the command line.

The location of the Source project must be in a location accessible to all endpoints. For example, a local server with a mapped drive x:\projects, or be in the same location on each machine e.g. C:\projects

Ensure that the parameters listed in Table 2 are entered. Then, press enter to begin the optimisation run.

As Insight computes the optimisation for each popluation, a completion notification is displayed in the command line.