Merge pull request #435 from Spine-project/MGA_implementation

Mga implementation

docs/make.jl

@@ -58,6 +58,7 @@ makedocs(
             "Lossless nodal DC power flows" => joinpath("advanced_concepts", "Lossless_DC_power_flow.md"),
             "Representative days with seasonal storages" => joinpath("advanced_concepts", "representative_days_w_seasonal_storage.md"),
             "Imposing renewable energy targets" => joinpath("advanced_concepts", "cumulated_flow_restrictions.md"),
+            "Modelling to generate alternatives" => joinpath("advanced_concepts", "mga.md"),
         ],
         "Library" => "library.md",
     ],

docs/src/advanced_concepts/decomposition.md

@@ -49,13 +49,13 @@ on that variable, one can add an output object with the variable name prepended
 Finally, if any constraint duals or reduced_cost values are requested via a report, calculate_duals is set to true and the final fixed LP solve is triggered.
 
 ## Using Decomposition
-The decomposition framework creates a master problem where the investment variables are optimised. The decomposition framework is invoked when a model object with the parameter [model\_type](@ref) set to `:spineopt_operations` is found and a second model object with `model_type` set to `:spineopt_master`. Once these conditions are met, all investment decisions in the model are automatically decomposed and optimised in the master problem. This behaviour may change in the future to allow some investment decisions to be optimised in the operations problem and some optimised in the master problem as desired.
+The decomposition framework creates a master problem where the investment variables are optimised. The decomposition framework is invoked when a model object with the parameter [model\_type](@ref) set to `:spineopt_standard` is found and a second model object with `model_type` set to `:spineopt_benders_master`. Once these conditions are met, all investment decisions in the model are automatically decomposed and optimised in the master problem. This behaviour may change in the future to allow some investment decisions to be optimised in the operations problem and some optimised in the master problem as desired.
 
 **Steps to involke decomposition in an investments problem**  
 Assuming one has set up a conventional investments problem as described in [Investment Optimization](@ref) the following additional steps are required to utilise the decomposition framework:
   - Create a new [model](@ref) object to representent the benders master problem
-  - Set the [model\_type](@ref) parameter for the master problem model to `spineopt_master`.
-  - Set the [model\_type](@ref) parameter for the existing conventional, operations problem model to `spineopt_operations`.
+  - Set the [model\_type](@ref) parameter for the master problem model to `spineopt_benders_master`.
+  - Set the [model\_type](@ref) parameter for the existing conventional, operations problem model to `spineopt_standard`.
   - Specify the master problem [model](@ref) parameter, `max_gap` - This determines the master problem convergence criterion for the relative benders gap. A value of 0.05 will represent a relative benders gap of 5%.
   - Specify the master problem [model](@ref) parameter `max_iterations` - This determines the master problem convergence criterion for the number of iterations. A value of 10 could be appropriate but this is highly dependent on the size and nature of the problem
   - Specify appropriate `model_report` relationships to determine which reports are written for which model

docs/src/advanced_concepts/mga.md

@@ -0,0 +1,13 @@
+# [Modelling to generate alternatives](@id mga-advanced)
+
+Through modelling to generate alternatives (short MGA), near-optimal solutions can be explored under certain conditions.
+The idea is that an orginal problem is solved, and subsequently solved again under the condition that the realization of variables should be maximally different from the previous iteration(s), while keeping the objective function within a certain threshold (defined by [max\_mga\_slack](@ref)).
+
+In SpineOpt, we choose [units\_invested\_available](@ref), [connections\_invested\_available](@ref), and [storages\_invested\_available](@ref) as variables that can be considered for the maximum-difference-problem. The implementation is based on [Modelling to generate alternatives: A technique to explore uncertainty in energy-environment-economy models](https://doi.org/10.1016/j.apenergy.2017.03.065).
+
+## How to set up an MGA problem
+- [model](@ref): In order to explore an MGA model, you will need one model of type [spineopt\_mga](@ref model_type_list). You should also define the number of iterations ([max\_mga\_iterations](@ref), and the maximum allowed deviation from the original objective function ([max\_mga\_slack](@ref)).
+- at least one investment candidate of type [unit](@ref), [connection](@ref), or [node](@ref). For more details on how to set up an investment problem please see: [Investment Optimization](@ref).
+- To include the investment decisions in the MGA difference maximization, the parameter [units\_invested\_mga](@ref), [connections\_invested\_mga](@ref), or [storages\_invested\_mga](@ref) need to be set to true, respectively.
+- The original MGA formulation is non-convex (maximization problem of an absolute function), but has been linearized through big M method. For this purpose, one should always make sure that [units\_invested\_big\_m\_mga](@ref), [connections\_invested\_big\_m\_mga](@ref), or [storages\_invested\_big\_m\_mga](@ref), respectively, is sufficently large to always be larger the the maximum possible difference per MGA iteration. (Typically the number of candidates could suffice.)
+- As [output](@ref)s are used to intermediately store solutions from different MGA runs, it is important that `units_invested`, `connections_invested`, or `storages_invested`, respectively, are defined as [output](@ref) objects in your database.

docs/src/concept_reference/connections_invested_big_m_mga.md

@@ -0,0 +1,3 @@
+The [connections\_invested\_big\_m\_mga](@ref) parameter is used in combination with the MGA algorithm (see [mga-advanced](@ref)).
+It defines an upper bound on the maximum difference between any MGA iteration. The big M should be chosen always sufficiently large. (Typically, a value equivalent to
+[candidate\_connections](@ref) could suffice.)

docs/src/concept_reference/connections_invested_mga.md

@@ -0,0 +1,2 @@
+The [connections\_invested\_mga](@ref) is a boolean parameter that can be used in combination with the MGA algorithm (see [mga-advanced](@ref)). As soon as
+the value of [connections\_invested\_mga](@ref) is set to `true`, investment decisions in this connection, or group of connections, will be included in the MGA algorithm.

docs/src/concept_reference/max_iterations.md

@@ -1 +1 @@
-When the [model](@ref) in question is of type `:spineopt_master`, this determines the maximum number of Benders iterations.
+When the [model](@ref) in question is of type `:spineopt_benders_master`, this determines the maximum number of Benders iterations.

docs/src/concept_reference/max_mga_iterations.md

@@ -0,0 +1 @@
+In the MGA algorithm the original problem is reoptimized (see also [mga-advanced](@ref)), and finds near-optimal solutions. The parameter [max\_mga\_iterations](@ref) defines how many MGA iterations will be performed, i.e. how many near-optimal solutions will be generated.

docs/src/concept_reference/max_mga_slack.md

@@ -0,0 +1 @@
+In the MGA algorithm the original problem is reoptimized (see also [mga-advanced](@ref)), and finds near-optimal solutions. The parameter [max\_mga\_slack](@ref) defines how far from the optimum the new solutions can maximally be (e.g. a value of 0.05 would alow for a 5% increase of the orginal objective value).

docs/src/concept_reference/mga_diff_relative.md

@@ -0,0 +1 @@
+Currently, the MGA algorithm (see [mga-advanced](@ref)) only supports absolute differences between MGA variables (e.g. absolute differences between [units\_invested\_available](@ref) etc.). Hence, the default for this parameter is `false` and should not be changed for now.

docs/src/concept_reference/model_type.md

@@ -1,3 +1,3 @@
-This parameter is used, generally, to control [model](@ref) dependent functionality and specify [model](@ref)-level parameters for different [model](@ref)s. Currently, the main use is to identify the [model](@ref) objects that represent the master and operational sub problems within a decomposed investment problem structure. To trigger the decomposed structure, a [model](@ref) object with `model_type`=`:spineopt_master` must exist and another with `model_type`=`:spineopt_operations` must also be present. To deactivate the decomposition functionality, the `model_type` of the master problem can be set to `:spineopt_other`.
+This parameter is used, generally, to control [model](@ref) dependent functionality and specify [model](@ref)-level parameters for different [model](@ref)s. Currently, the main use is to identify the [model](@ref) objects that represent the master and operational sub problems within a decomposed investment problem structure. To trigger the decomposed structure, a [model](@ref) object with `model_type`=`:spineopt_benders_master` must exist and another with `model_type`=`:spineopt_standard` must also be present. To deactivate the decomposition functionality, the `model_type` of the master problem can be set to `:spineopt_other`.
 
-See also [Decomposition](@ref).
+See also [Decomposition](@ref).

docs/src/concept_reference/storages_invested_big_m_mga.md

@@ -0,0 +1,3 @@
+The [storages\_invested\_big\_m\_mga](@ref) parameter is used in combination with the MGA algorithm (see [mga-advanced](@ref)).
+It defines an upper bound on the maximum difference between any MGA iteration. The big M should be chosen always sufficiently large. (Typically, a value equivalent to
+[candidate\_storages](@ref) could suffice.)

docs/src/concept_reference/storages_invested_mga.md

@@ -0,0 +1,2 @@
+The [storages\_invested\_mga](@ref) is a boolean parameter that can be used in combination with the MGA algorithm (see [mga-advanced](@ref)). As soon as
+the value of [storages\_invested\_mga](@ref) is set to `true`, investment decisions in this connection, or group of storages, will be included in the MGA algorithm.

docs/src/concept_reference/units_invested_big_m_mga.md

@@ -0,0 +1,3 @@
+The [units\_invested\_big\_m\_mga](@ref) parameter is used in combination with the MGA algorithm (see [mga-advanced](@ref)).
+It defines an upper bound on the maximum difference between any MGA iteration. The big M should be chosen always sufficiently large. (Typically, a value equivalent to
+[candidate\_units](@ref) could suffice.)

docs/src/concept_reference/units_invested_mga.md

@@ -0,0 +1,2 @@
+The [units\_invested\_mga](@ref) is a boolean parameter that can be used in combination with the MGA algorithm (see [mga-advanced](@ref)). As soon as
+the value of [units\_invested\_mga](@ref) is set to `true`, investment decisions in this connection, or group of units, will be included in the MGA algorithm.