Restore Point
In some contexts it is useful to conduct a sequence of optimization runs, each of which involves an optimization policy whose initial portion is the same for each run. A Restore Point allows RiverWare to perform the computations for the initial, shared portion of the policy once, save the state of the optimization problem after the last common goal, then use that saved state as an advanced start for subsequent runs in the sequence. Thus a Restore Point can be used to reduce the overall solution time for the sequence of runs.
You want to execute three optimization runs that all use the same input data and have the same high priority constraints. They differ only in a lowest priority objective function. • Run 1 (Baseline) solves for expected operations using an objective to maximize economic value. • Run 2 determines the upper bound on hydropower generation with an objective to maximize generation. • Run 3 determines the lower bound on hydropower generation with an objective to minimize generation. Assume the following goal set: 1. Soft constraints: Pool Elevation Max 2. Soft constraints: Pool Elevation Min 3. Soft constraints: Outflow Max 4. Soft constraints: Outflow Min 5. Soft constraints: Target Ending Elevations 6. Create Restore Point 7. Objective: Maximize Economic Value 8. Objective: Maximize Hydropower Generation 9. Objective: Minimize Hydropower Generation The Restore Point could be used to reduce the run time for the three runs in the following manner. • Run 1: Turn off goals 8 and 9. The optimization will solve goals 1-5 as normal. In goal 6, it will create a Restore Point to save the state of the optimization problem after goal 5 (see Create a Restore Point.) Then it will continue on and solve through the objective in goal 7 as normal. • Run 2: Turn off goal 7, and turn on goal 8. Run using the Restore Point (see Use a Restore Point). The optimization will restore the optimization problem at goal 6 then advance directly to solving goal 8. • Run 3: Turn off goal 8, and turn on goal 9. Run using the Restore Point. The optimization will restore the optimization problem at goal 6 then advance directly to solving goal 9. For runs 2 and 3, the optimization has to solve a single goal only. For large models with extensive goal sets, the ability to skip over many of the goals can significantly reduce the solution time. |
Optimization runs that use a Restore Point still follow the complete Simulation, Optimization, Rulebased Simulation controller sequence (see Standard Controller Sequence). The Restore Point only affects the run with the Optimization controller.
Optimization Restore Points can also be used in combination with Multiple Run Management when the various runs in the concurrent multiple runs differ only in lower priorities. See About Multiple Runs in Solution Approaches.
Note: An Optimization Restore Point would not be used with MRM when the differences across the multiple runs are different input traces, such as different inflow time series for each run. The use of a Restore Point would only be appropriate when the differences across the multiple runs affect only lower priorities in the optimization. See Restrictions on Restore Point Use for more information on the limitations when using a Restore Point.
The Optimization Restore Point preserves all information about the optimization problem at the time the Restore Point is created, including solution analysis information. A run that starts by using a Restore Point will report all information in the Priority-oriented Optimization Solution Analysis Tool (POSAT) as for a normal optimization run that solves all priorities. (See Priority-oriented Optimization Solution Analysis Tool.)
Create a Restore Point
An Optimization Restore Point is created via a Create Restore Point statement in an optimization goal.
To create a Restore Point
1. Add a goal to the goal set at the desired priority for the Restore Point.
2. Open the new goal, and from the Statement menu select Add Create Restore Point.
3. Double-click the <string expr> to edit it.
4. Type a name for the Restore Point, then Enter.
5. Run the optimization. When the goal with the Create Restore Point statement executes, it will save a representation of the optimization problem at the end of the previous goal internally in memory with the name specified. Otherwise the optimization will execute as normal.
Tip: Like all RPL statements, a Create Restore Point statement can be included within other statements. For example, you could add the Create Restore Point statement inside an If statement if you only want it to execute if certain conditions are true. An Execution Constraint can also be used in the goal with the Create Restore Point statement to control its execution (see Execution Constraint / Execute Block Only When in RiverWare Policy Language (RPL)).
Note: When a Restore Point is created from a RPL statement, it automatically overwrites any existing Restore Point with the same name.
Note: A Create Restore Point statement should not be included in a goal with a Soft Constraint set or Minimize or Maximize Objective. The Create Restore Point statement should be in its own goal.
Once a Restore Point has been created, the details can be viewed in the Optimization Restore Point Manager.
Restore Points are not saved in the model file. When a model is loaded, there will be no Restore Points present. To saved a Restore Point for use after reloading the model or in a different RiverWare session, see Export a Restore Point and Import a Restore Point.
Use a Restore Point
Use of a Restore Point as an advanced start for an optimization run can be specified either from the Run Control dialog or from the Set Controller script action.
Specify a Restore Point from the Run Control dialog
The use of a Restore Point can be specified interactively from the Run Control dialog.
1. When the Optimization controller is selected, select the box for Run From Restore Point.
2. The menu at the right will list all Restore Points currently available in the Optimization Restore Point Manager. Select the desired Restore Point.
Alternatively, type the name of the desire Restore Point. This approach can be used to specify a Restore Point that does not yet exist in the Restore Point Manager. Specification of the Restore Point to use is saved in the model file.
Note: Although the Restore Point does not have to be present in the Optimization Restore Point Manager in order to specify it in the Run Control dialog, the specified Restore Point must be present in the Restore Point Manager when the Optimization controller is started. See Import a Restore Point for instructions to import a Restore Point previously saved to a file. The import of the Restore Point must occur prior to starting the Optimization controller.
3. Start the Optimization run sequence.
When the Optimization controller starts, it will skip all goals prior to the goal with the specified Restore Point. At the Restore Point goal, it will re-instate the optimization problem using the Restore Point then solve all remaining goals as normal. The diagnostic output will include a message indicating that the run started with the Restore Point. In the image below, the diagnostic message indicates, that goals 1-17 were skipped, and the run started by re-instating the Blue River Restore Point at priority 18. It then solved priorities 19 and 20 as normal.
Specify a Restore Point from a script action
The use of a Restore Point can also be specified from the Set Controller script action so that it can be automated. See Set Controller in Automation Tools for details of how to configure the script action. The script action changes the state of the controller. Then the optimization run can be started either manually or via the Execute Run script action. Once the run is started, the behavior is the same as when the Restore Point is specified via the Run Control dialog.
Optimization Restore Point Manager
The Optimization Restore Point Manager provides information about all Restore Points currently available.
The Optimization Restore Point Manager can be accessed by selecting Optimization Restore Point Manager... from one of the following three menus.
• The Workspace menu on the main workspace
• The Set menu from the Optimization Goal Set Editor
• The View menu on the Run Control dialog box
Restore Points are not saved in the model file. When model is loaded, the Restore Point Manager will be empty until either a Restore Point is created in an optimization run (see Create a Restore Point) or a Restore Point is imported (see Import a Restore Point).
For each Restore Point, the Restore Point Manager provides the following pieces of information.
• Name of the Restore Point
• The priority and name of the goal that created the Restore Point
• The time at which the Restore Point was created
• The number of constraints in the optimization problem represented by the Restore Point
• The number of variables in the optimization problem represented by the Restore Point
The Restore Point Manager supports the following actions for Restore Points
• Rename a selected Restore Point
These actions can be selected from the File menu of the Optimization Restore Point Manager or from buttons on the right side of the Optimization Restore Point Manager dialog box.
Export a Restore Point
Optimization Restore Points are not saved in the model file. To preserve a Restore Point for use when the model is reloaded or in another RiverWare session, it must be exported to a file and then imported into the model in which it will be used. (For instructions to import a Restore Point, see Import a Restore Point.) Restore Points can be exported to a file in three ways.
• Export a Restore Point via the Restore Point Manager
• Export a Restore Point with a script action
• Export a Restore Point with a RCL batch script command
Export from the Restore Point Manager
To export a Restore Point via the Optimization Restore Point Manager, use the following steps.
1. Open the Optimization Restore Point Manager from one of the following locations.
– The Workspace menu on the main workspace
– The Set menu on the Optimization Goal Set Editor
– The View menu on the Run Control dialog box
2. Select the name of the desired Restore Point. (If the desired Restore Point has not yet been created and thus is not shown in the Restore Point Manager, see Create a Restore Point.)
3. Select the Export button on the right side of the Restore Point Manager (or select Export Selected Restore Point... from the File menu).
4. In the resulting file chooser, navigate to the desired folder and type the desired file name. Then select Save.
Optimization Restore Point files are saved with the .orp extension by default.
Note: The exporting of a Restore Point to a file can take a noticeable amount of time, particularly for large optimization models with numerous timesteps and a large number of optimization goals, in other words, when the optimization problem has a large number of constraints and variables. However, the time to export and import a Restore Point is generally much less than the time required to repeat the portion of the optimization run represented by the Restore Point.
Automate Restore Point export via script
A Restore Point can be exported to a file by the Export Optimization Restore Point script action. See Export Optimization Restore Point in Automation Tools for details.
When running RiverWare in batch mode, a Restore Point can be exported by using the ExportOptRestorePoint command in the RCL script. See ExportOptRestorePoint in Automation Tools for details.
Import a Restore Point
Optimization Restore Points are not saved in the model file. To use a Restore Point that was created before the model is loaded, it must be exported to a file. (For instructions to export a Restore Point, see Export a Restore Point.) The Restore Point can then can be imported for use when the model is reloaded or in another RiverWare session. Restore Points can be imported from a file in three ways.
• Import a Restore Point via the Restore Point Manager
• Import a Restore Point with a script action
• Import a Restore Point with a RCL batch script command
Note: In order to use a Restore Point in an optimization run, the Restore Point must be imported before starting the Optimization controller.
Import from the Restore Point Manager
To use the Optimization Restore Point Manager to import a Restore Point that was previously saved to a file, use the following steps.
1. Open the Optimization Restore Point Manager from one of the following locations.
– The Workspace menu on the main workspace
– The Set menu on the Optimization Goal Set Editor
– The View menu on the Run Control dialog box
2. Select the Import button on the right side of the Restore Point Manager (or select Import Restore Point... from the File menu).
3. In the resulting file chooser, navigate to the desired Restore Point file, and select it. Then select Open.
4. If there is already an existing Restore Point with the same name as the Restore Point being imported from a file, you will be presented with three options.
– Replace the existing Restore Point
– Rename the existing Restore Point so that it can be preserved - RiverWare will give the existing Restore Point a new, default name; the Restore Point being imported will maintain its name from the file.
– Cancel the import operation
Select the appropriate option.
At this point, the Restore Point is ready to use in an Optimization run (see Use a Restore Point).
Note: The importing of a Restore Point from a file can take a noticeable amount of time, particularly for large optimization models with numerous timesteps and a large number of optimization goals, in other words, when the optimization problem represented by the Restore Point has a large number of constraints and variables. However, the time to export and import a Restore Point is generally much less than the time required to repeat the portion of the optimization run represented by the Restore Point.
Automate Restore Point import via script
A Restore Point can be imported from a file by the Import Optimization Restore Point script action. See Import Optimization Restore Point in Automation Tools for details. The script action provides options to rename the Restore Point on import and options for handling name conflicts similar to when importing via the Restore Point Manager.
When running RiverWare in batch mode, a Restore Point can be imported by using the ImportOptRestorePoint command in the RCL script. See ImportOptRestorePoint in Automation Tools for details.
Delete Restore Points
Restore Points currently stored in the Optimization Restore Point Manager can be deleted in three manners
• Delete Restore Points via the Restore Point Manager
In the Optimization Restore Point Manager select the desired Restore Point. Then select the Delete button on the right of the Restore Point Manager. Alternatively select Delete Selected Restore Point from the File menu, or select the option to Delete All Restore Points from the File menu.
• Use a script action to delete all Restore Points
The Delete Optimization Restore Points script action can be used to delete all Restore Points. This script action deletes all Restore Points; it does not support deleting individual Restore Points. See Delete Optimization Restore Points in Automation Tools for details.
• Use a RCL command to delete Restore Points in a batch run.
When running RiverWare in batch mode, the DeleteAllOptRestorePoints command can be added to the RiverWare Command Language (RCL) script to delete all Restore Points. See DeleteAllOptRestorePoints in Automation Tools for details.
Restore Points are not saved in the model file, so closing RiverWare, loading a new model or reloading the same model will also delete all Restore Points.
Restore Point Informational Diagnostics
Informational diagnostics related to Optimization Restore Points can be issued from the Optimization diagnostics and Workspace diagnostics. (See Diagnostics Manager in Debugging and Analysis for instructions to access the Optimization and Workspace Diagnostic Configuration.) In either Diagnostic Configuration dialog, select the Opt. Restore Point Management diagnostic category.
Optimization diagnostics for Restore Points are issued during a run with the Optimization controller that creates a Restore Point and include information about the time to create the Restore Point.
Workspace diagnostics for Restore Points are issued during Restore Point import and export and include the file imported/exported and information on the timing of the steps in the import/export.
Restrictions on Restore Point Use
An Optimization Restore Point preserves the state of the complete optimization problem at the time the Restore Point is created. As such, when the Restore Point is used as an advanced start for an optimization run, it assumes that nothing has changed in the model or optimization goal set that would change the optimization for any priorities prior to the Restore Point. This means that the following conditions must be true.
• The model configuration when using the Restore Point in a run must not have changed from the run in which the Restore Point was created. This includes objects, method selections, links, and slot configurations, including lower and upper bounds on slots that are optimization variables.
• The Run Range and timestep size must be the same as the run in which the Restore Point was created.
• The optimization goal set for all priorities prior to and including the priority with the Create Restore Point statement must be identical to the goal set used for the run that created the restore point. This includes goal names, RPL logic, and goal activation. (Goals at priorities after the goal that created the restore point can differ when using the Restore Point.)
• All input slot data that impacts priorities prior to the creation of the Restore Point must be identical to the run in which the Restore Point was created. This includes input data on series slots used in physical process methods, static parameter data on table, scalar, and periodic slots used in physical process methods, and all slot values referenced by optimization goal RPL logic. (Slot values that are referenced only by RPL logic in goals after the Restore Point can differ from the values in the run in which the Restore Point was created and are often the components of the model that change for alternative runs that start with the Restore Point.)
If any of these conditions is not true, the run using the Restore Point could result in an infeasible solution, could fail with other errors, or could produce unintended results.
In addition, a Restore Point can be used only when running with a RiverWare version that is in the same minor release series as the RiverWare version that created the restore point. For example, a Restore Point created with RiverWare 8.5 can be used with the RiverWare 8.5.2 Patch Release, but attempting to use it with RiverWare 8.6.2 or RiverWare 9.0 would result in an error.
Revised: 01/05/2024