Once you have set up your Antares study with the candidates.ini and settings.ini files, you are ready to launch the Antares-Xpansion package to solve the investment problem.
Antares-Xpansion includes an experimental graphical interface but it is optimally used as a command line prompt.
Command line usage
Quick start
Open a command prompt in your Antares-Xpansion install directory (by default it is named
antaresXpansion-x.y.z-win64wherex.y.zis the version number).You can launch a command line prompt by typing
cmdin the path.
- Run
antares-xpansion-launcher.exeand choose the path to the Antares study with the-iparameter:antares-xpansion-launcher.exe -i examples\SmallTestFiveCandidates
The
-iparameter can also be replaced by--dataDir.
Command line parameters
-h, --help
Show a help message and exit.
--step {full, antares, problem_generation, benders, study_update, sensitivity, presolve, resume}
Default value: full.
The execution of Antares-Xpansion consists of several steps that can be run separately. The --step parameter allows to select the steps to execute:
| Step | Description |
|---|---|
antares | Launch Antares-Simulator once to get the Antares problem. |
problem_generation | Generate the full Antares-Xpansion problem using the user input and the output of the Antares-Simulator run. |
benders | Solve the investment optimization problem of Antares-Xpansion, using the Benders decomposition. |
study_update | Update the Antares study with the solution returned by the Benders decomposition algorithm. |
full | Launch all steps in order: antares > problem_generation > benders > study_update |
sensitivity | Launch sensitivity analysis, see Sensitivity analysis. |
presolve | Launch a presolver on the decomposed problem (only available with Xpress solver). See Calling the presolve |
resume | resume benders step of a study in accordance with --simulationName, by default last study is resumed. |
-i, --dataDir
Specifies the Antares study folder path. Use quotes “antares study path” in case of a space in the path.
--simulationName {last, your-antares-output-directory}
Default value: last.
Defines the name of the Antares-Simulator output archive that Antares-Xpansion uses to generate the expansion problem. If the value is last, the most recent run will be used. This option only has an effect when --step is among {problem_generation, benders, study_update, sensitivity}. In a step by step workflow keep both .zip file and -Xpansion corresponding folder.
-m, --method {benders, mergeMPS, adequacy_criterion}
Default value: benders.
Sets the optimization method used by Antares-Xpansion.
| Option | Description |
|---|---|
benders | Launch the classical Benders decomposition or the Benders by batch algorithm depending on batch_size. |
mergeMPS | Launch a frontal resolution of the investment problem (i.e. without decomposition). This is much more time-consuming than using Benders decomposition. |
adequacy_criterion | Launch Antares-Xpansion with reliability constraints, see Adequacy criterion. |
--problem-format {MPS, OPTIMIZED}
Default value: OPTIMIZED.
Selects the storage format of the generated mathematical problems (master + subproblems):
OPTIMIZED(default) : use underlying solver to write problems in an optimized format to reduce disk space usage and I/O time. The underlying format depends on the solver used.- XPRESS :
svfformat: compressed binary format. - COIN : unsupported. Falls back to
MPS.
- XPRESS :
MPS: write the problems in MPS format, which is a standard format for mathematical programming problems.
-n, --np
Default value: 2.
Sets the number of MPI processes to use for the Benders decomposition. This option only has an effect when -m is set to benders.
--antares-n-cpu
Default value: 1.
Sets the number of threads to use for Antares-Simulator in the initial antares step.
--keepMps
Default value: False.
If set to True, keeps mps files that encodes the problems solved by the optimizer. This option must be set to True if the user intends to launch the optimization several times on the same study (--step benders) without doing the other steps of Antares-Xpansion.
--presolve
Default value: False.
If set to True, runs the presolve step before calling the benders step
-v, --version
Show the Antares-Xpansion version.
--antares-version
Show the Antares-Simulator version (used in the antares step).
--cache_problems
Enable "cache mode" for benders. Problems are not preloaded but loaded on demand. This is useful when hitting memory limitation during benders at the cost of some processing time.
Output of Antares-Xpansion
Results
When the Antares-Xpansion algorithm terminates, i.e. when an optimal investment combination has been found, the package produces an archive simulation-name.zip located in the output folder of the Antares study.
Once you unzip the archive, the files lp/reportbenders.txt and the expansion/out.json log information for each iteration:
- The investment combination that has been evaluated,
- The operational, investment and overall costs,
- The current lower and upper bounds (no upper bound for the Benders by batch),
- The absolute and relative gap,
- The resolution time for the subproblems and the master problem.
There is also information on the iteration number which has led to the best solution. The file out.json also gives the parameters that are used by the optimization algorithm (some of them are defined by the user in settings.ini).
Updates of candidate links
At the end of the run, Antares-Xpansion updates the Antares study by replacing the capacities of investment candidate links with their optimal value taking into account the link-profile, the already-installed-capacity and the already-installed-link-profile, see Figure 15.
The user can therefore immediately launch an Antares simulation using the results of the best iteration.
!!! Advice It is recommended to relaunch an Antares study with the optimal solution returned by Antares-Xpansion for further analysis. Antares-Xpansion relaxes some constraints (see link-profile and uc_type parameters for example), therefore the total cost may be a bit different.
Figure 15 – Update of the Antares study.
Logs
During the simulation, logs are displayed on the console to give information on the current iteration, corresponding to the data written in the reportbenders.txt text file.
Errors
Xpansion will not work if the initial Antares study is not running. The user must therefore check beforehand that the Antares simulations do not contain any errors.
Be careful to check the consistency between the names of the links in the candidates.ini file and in the Antares study and to use a unique index and name per candidate.
In case of a problem, put an issue on Github:
