Using the command line for Insight
Insight can be configured, set up (using a settings file) and run using the command line.
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 required | Example |
---|---|
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 parameters | Example |
---|---|
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 optional | Example |
---|---|
Seed | Seed 0.5 |
Real Var Crossover Probability | GAExpert RealVarCrossoverProb 0.9 |
Real Var Mutation Probability | GAExpert RealVarMutationProb 0.5 |
Integer Var Crossover Probability | GAExpert IntegerVarCrossoverProb 0.9 |
Integer Var Mutation Probability | GAExpert IntegerVarMutationProb 0.5 |
Crossover Distribution Index | GAExpert 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.
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 required | Example |
---|---|
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 information | Example |
---|---|
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 | --progressFormat "##Progress##:{0}:{1}:{2}:{3}:{4}" |
Suppress message to StdOut other than formatted progress messages and results (if output not specified) | --quiet |
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.
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.
- 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;
- In the command prompt, change the directory to the location of Source (ie. where Source in installed); and
- 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.
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.
Complete the following on every machine that you wish to set up as an endpoint/s:
- Ensure that the RunSourceServersForInsight.ps1 file is in the same folder as RiverSystems.CommandLine.exe;
- Open PowerShell (Click on the Start menu (Windows 7), search for PowerShell, and press Enter);
- 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;
- Change the directory to the location of the RunSourceServersForInsight.ps1 file;
- Run the PowerShell script with ./RunSourceServersForInsight.ps1; and
- 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.
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.