Support EMB-independent EMI (#23)

* Move support for EMI to extension in EMG (from EMGExt in EMI) - Move example and test from EMI to EMG - Added TransInvData constructor - Included parts in docs * Included redirect of output for examples in tests --------- Co-authored-by: Julian Straus <[email protected]>
EnergyModelsX · Aug 20, 2024 · e34f545 · e34f545
1 parent 02fec52
commit e34f545
Show file tree

Hide file tree

Showing 25 changed files with 1,225 additions and 62 deletions.
diff --git a/NEWS.md b/NEWS.md
@@ -1,5 +1,13 @@
 # Release notes
 
+## Unversioned
+
+### Introduced `EnergyModelsInvestments` as extension
+
+* `EnergyModelsInvestments` was switched to be an independent package in [PR #28](https://github.com/EnergyModelsX/EnergyModelsInvestments.jl/pull/28).
+* This approach required `EnergyModelsGeography` to include all functions and type declarations internally.
+* An extension was introduced to handle these problems.
+
 ## Version 0.9.1 (2024-05-24)
 
 ### Bugfix

diff --git a/Project.toml b/Project.toml
@@ -1,15 +1,24 @@
 name = "EnergyModelsGeography"
 uuid = "3f775d88-a4da-46c4-a2cc-aa9f16db6708"
 authors = ["Espen Flo Bødal <[email protected]>"]
-version = "0.9.1"
+version = "0.10.0"
 
 [deps]
 EnergyModelsBase = "5d7e687e-f956-46f3-9045-6f5a5fd49f50"
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
+SparseVariables = "2749762c-80ed-4b14-8f33-f0736679b02b"
 TimeStruct = "f9ed5ce0-9f41-4eaa-96da-f38ab8df101c"
 
+[weakdeps]
+EnergyModelsInvestments = "fca3f8eb-b383-437d-8e7b-aac76bb2004f"
+
+[extensions]
+EMIExt = "EnergyModelsInvestments"
+
 [compat]
-EnergyModelsBase = "^0.7"
+EnergyModelsBase = "^0.8"
+EnergyModelsInvestments = "0.7"
+SparseVariables = "0.7.3"
 JuMP = "1.5"
-julia = "^1.6"
 TimeStruct = "^0.8"
+julia = "1.9"
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,6 +1,8 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
 EnergyModelsBase = "5d7e687e-f956-46f3-9045-6f5a5fd49f50"
 EnergyModelsGeography = "3f775d88-a4da-46c4-a2cc-aa9f16db6708"
+EnergyModelsInvestments = "fca3f8eb-b383-437d-8e7b-aac76bb2004f"
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
 TimeStruct = "f9ed5ce0-9f41-4eaa-96da-f38ab8df101c"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,28 +1,41 @@
 using Documenter
+using DocumenterInterLinks
 
 using EnergyModelsGeography
+using EnergyModelsBase
+using EnergyModelsInvestments
 
 const EMG = EnergyModelsGeography
 
+# Copy the NEWS.md file
+cp("NEWS.md", "docs/src/manual/NEWS.md"; force=true)
+
+links = InterLinks(
+    "TimeStruct" => "https://sintefore.github.io/TimeStruct.jl/stable/",
+    "EnergyModelsBase" => "https://energymodelsx.github.io/EnergyModelsBase.jl/stable/",
+    "EnergyModelsInvestments" => "https://energymodelsx.github.io/EnergyModelsInvestments.jl/stable/",
+)
+
 DocMeta.setdocmeta!(
     EnergyModelsGeography,
     :DocTestSetup,
     :(using EnergyModelsGeography);
     recursive = true,
 )
 
-# Copy the NEWS.md file
-news = "docs/src/manual/NEWS.md"
-cp("NEWS.md", news; force=true)
-
 makedocs(
-    modules = [EnergyModelsGeography],
     sitename = "EnergyModelsGeography",
     format = Documenter.HTML(
         prettyurls = get(ENV, "CI", "false") == "true",
         edit_link = "main",
         assets = String[],
     ),
+    modules = [
+        EMG,
+        isdefined(Base, :get_extension) ?
+        Base.get_extension(EMG, :EMIExt) :
+        EMG.EMIExt
+    ],
     pages = [
         "Home" => "index.md",
         "Manual" => Any[
@@ -32,17 +45,21 @@ makedocs(
             "Constraint functions" => "manual/constraint-functions.md",
             "TransmissionMode structure" => "manual/transmission-mode.md",
             "Example" => "manual/simple-example.md",
+            "Investment options"=>"manual/investments.md",
             "Release notes" => "manual/NEWS.md",
         ],
         "How to" => Any[
             "Contribute to EnergyModelsGeography" => "how-to/contribute.md",
         ],
         "Library" => Any[
             "Public" => "library/public.md",
-            "Internals" => Any[
-                "Reference" => "library/internals/reference.md"]
-        ]
-    ]
+            "Internals"=>Any[
+                "Reference"=>"library/internals/reference.md",
+                "Reference EMIExt"=>"library/internals/reference_EMIExt.md",
+            ],
+        ],
+    ],
+    plugins=[links],
 )
 
 deploydocs(;

diff --git a/docs/src/how-to/contribute.md b/docs/src/how-to/contribute.md
@@ -1,8 +1,8 @@
-# Contribute to EnergyModelsGeography
+# [Contribute to EnergyModelsGeography](@id how_to-con)
 
 Contributing to `EnergyModelsGeography` can be achieved in several different ways.
 
-## Creating new extensions
+## [Create new extensions](@id how_to-con-ext)
 
 The main focus of `EnergyModelsGeography` is to provide [`EnergyModelsBase`](https://energymodelsx.github.io/EnergyModelsBase.jl/stable/) with geographical representation using the concepts of [`Area`](@ref)s, [`Transmission`](@ref) corridors, or [`TransmissionMode`](@ref)s.
 Hence, a first approach to contributing to `EnergyModelsGeography` is to create a new package with, _e.g._, the introduction of new `Area`, `Transmission`, or `TransmissionMode` descriptions.
@@ -12,9 +12,9 @@ These descriptions can, _e.g._, include constraints for an `Area` or provide the
     We are currently working on guidelines for the best approach for `EnergyModelsGeography`, similar to the section [_Extensions to the model_](https://energymodelsx.github.io/EnergyModelsBase.jl/stable/manual/philosophy/#sec_phil_ext) in `EnergyModelsBase`.
     This section will provide you eventually with additional information regarding to how you can develop new `Area`, `Transmission`, or `TransmissionMode` descriptions.
 
-## File a bug report
+## [File a bug report](@id how_to-con-bug_rep)
 
-Another approach to contributing to `EnergyModelsGeography` is through filing a bug report as an _[issue](https://github.com/EnergyModelsX/EnergyModelsGeography.jl/issues/new)_ when unexpected behaviour is occuring.
+Another approach to contributing to `EnergyModelsGeography` is through filing a bug report as an [_issue_](https://github.com/EnergyModelsX/EnergyModelsGeography.jl/issues/new) when unexpected behaviour is occuring.
 
 When filing a bug report, please follow the following guidelines:
 
@@ -39,10 +39,10 @@ When filing a bug report, please follow the following guidelines:
 
     In order to improve the code, we welcome any reports of potential method ambiguities to help us improving the structure of the framework.
 
-## Feature requests
+## [Feature requests](@id how_to-feat_req)
 
 Although `EnergyModelsGeography` was designed with the aim of flexibility, it sometimes still requires additional features to account for potential extensions.
-Feature requests for `EnergyModelsGeography` should follow the guidelines developed for [`EnergyModelsBase`](https://energymodelsx.github.io/EnergyModelsBase.jl/stable/how-to/contribute/).
+Feature requests for `EnergyModelsGeography` should follow the guidelines developed for [_`EnergyModelsBase`_](https://energymodelsx.github.io/EnergyModelsBase.jl/stable/how-to/contribute/).
 
 !!! note
     `EnergyModelsGeography` should not include everything.

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -17,6 +17,7 @@ Pages = [
     "manual/optimization-variables.md",
     "manual/constraint-functions.md",
     "manual/transmission-mode.md",
+    "manual/investments.md",
     "manual/simple-example.md"
 ]
 Depth = 1

diff --git a/docs/src/library/internals/reference_EMIExt.md b/docs/src/library/internals/reference_EMIExt.md
@@ -0,0 +1,31 @@
+# Internals - EnergyModelsInvestment extensions
+
+## Index
+
+```@index
+Pages = ["reference_EMIExt.md"]
+```
+
+## Types
+
+```@autodocs
+Modules = [
+    isdefined(Base, :get_extension) ?
+    Base.get_extension(EMG, :EMIExt) :
+    EMG.EMIExt
+]
+Public = false
+Order = [:type]
+```
+
+## Methods
+
+```@autodocs
+Modules = [
+    isdefined(Base, :get_extension) ?
+    Base.get_extension(EMG, :EMIExt) :
+    EMG.EMIExt
+]
+Public = false
+Order = [:function]
+```
diff --git a/docs/src/library/public.md b/docs/src/library/public.md
@@ -1,14 +1,14 @@
-# [Public interface](@id sec_lib_public)
+# [Public interface](@id lib-pub)
 
-## `Area`
+## [`Area`](@id lib-pub-area)
 
 A geographical `Area` consist of a location and a connection to a local energy system *via* a specialized `Availability` node called `GeoAvailability`.
 The specialized `Availability` node is required to modify the energy/mass balance to allow for imports and exports.
 Constraints related to the area keep track of a resource's export and import to the local system and exchange with other areas.
 Multiple dispatch is used on the `Area` type for imposing specific constraints.
 Hence, other restrictions can be applied on a area level, such as electricity generation reserves, CO₂ emission limits or resource limits (wind power, natural gas etc.).
 
-### `Area` types
+### [`Area` types](@id lib-pub-area-types)
 
 The following types are inmplemented:
 
@@ -19,7 +19,7 @@ LimitedExchangeArea
 GeoAvailability
 ```
 
-### Functions for accessing fields of `Area` types
+### [Functions for accessing fields of `Area` types](@id lib-pub-area-fun_field)
 
 The following functions are defined for accessing fields from an `Area`:
 
@@ -32,21 +32,21 @@ exchange_resources
 getnodesinarea
 ```
 
-## `Transmission`
+## [`Transmission`](@id lib-pub-transmission)
 
 `Transmission` occurs on specified transmission corridors `from` one area `to` another. On each corridor, there can exist several `TransmissionMode`s that are transporting resources using a range of technologies.
 
 It is important to consider the `from` and `to` `Area` when specifying a `Transmission` corridor.
 The chosen direction has an influence on whether the variables ``\texttt{trans\_in}[m, t]`` and ``\texttt{trans\_out}[m, t]`` are positive or negative for exports in the case of bidirectional transport.
-This is also explained on the page *[Optimization variables](@ref optimization_variables)*.
+This is also explained on the page *[Optimization variables](@ref man-opt_var)*.
 
-### `Transmission` types
+### [`Transmission` types](@id lib-pub-transmission-types)
 
 ```@docs
 Transmission
 ```
 
-### Functions for accessing fields of `Transmission` types
+### [Functions for accessing fields of `Transmission` types](@id lib-pub-transmission-fun_fields)
 
 The following functions are defined for accessing fields from a `Transmission` as well as finding a subset of `Transmission` corridors:
 
@@ -59,7 +59,7 @@ corr_from_to
 modes_of_dir
 ```
 
-## `TransmissionMode`
+## [`TransmissionMode`](@id lib-pub-transmission_mode)
 
 `TransmissionMode` describes how resources are transported, for example by dynamic transmission modes on ship, truck or railway (represented generically by `RefDynamic`, although not implemented in the current version) or by static transmission modes on overhead power lines or gas pipelines (respresented generically by `RefStatic`).
 `TransmissionMode`s includes capacity limits (`trans_cap`), losses (`trans_loss`) and directions (`directions`) for the generic transmission modes `RefDynamic` and `RefStatic`.
@@ -74,7 +74,7 @@ All `TransmissionMode`s can also include both fixed (`opex_fixed`) and variable
     They are independent of the distance.
     The reasoning for this approach is that it allows the modeller to have a non-linear, distance dependent OPEX or loss function for providing the input to the model.
 
-### `TransmissionMode` types
+### [`TransmissionMode` types](@id lib-pub-transmission_mode-types)
 
 The following `TransmissionMode`s are implemented and exported:
 
@@ -87,7 +87,7 @@ PipeSimple
 PipeLinepackSimple
 ```
 
-### Functions for accessing fields of `TransmissionMode` types
+### [Functions for accessing fields of `TransmissionMode` types](@id lib-pub-transmission_mode-fun_fields)
 
 The following functions are defined and exported for accessing fields from a `TransmissionMode`:
 
@@ -98,3 +98,18 @@ directions
 consumption_rate
 energy_share
 ```
+
+## [Investment data](@id lib-pub-inv_data)
+
+### [`InvestmentData` types](@id lib-pub-inv_data-types)
+
+Transmission mode investmentments utilize the same investment data type ([`SingleInvData](@extref EnergyModelsBase.SingleInvData)) as investments in node capacities.
+
+### [Legacy constructors](@id lib-pub-inv_data-leg)
+
+We provide a legacy constructor, `TransInvData`, that uses the same input as in version 0.5.x.
+If you want to adjust your model to the latest changes, please refer to the section *[Update your model to the latest version of EnergyModelsInvestments](@extref EnergyModelsInvestments how_to-update-05)*.
+
+```@docs
+TransInvData
+```
diff --git a/docs/src/manual/constraint-functions.md b/docs/src/manual/constraint-functions.md
@@ -1,11 +1,11 @@
-# [Constraint functions](@id constraint_functions)
+# [Constraint functions](@id man-con)
 
 The package provides standard constraint functions that can be use for new developed `TransmissionMode`s.
 The general approach is similar to `EnergyModelsBase`.
 Bidirectional transport requires at the time being the introduciton of an *if*-loop.
 In later implementation, it is planned to also use dispatch for this analysis as well.
 
-## Capacity constraints
+## [Capacity constraints](@id man-con-cap)
 
 ```julia
 constraints_capacity(m, tm::TransmissionMode, 𝒯::TimeStructure, modeltype::EnergyModel)
@@ -34,11 +34,11 @@ This functions is also used to subsequently dispatch on model type for the intro
     ```
     without adding a function for
     ```julia
-    constraints_capacity_installed(m, tm::TransmissionMode, 𝒯::TimeStructure, modeltype::EMI.AbstractInvestmentModel)
+    constraints_capacity_installed(m, tm::TransmissionMode, 𝒯::TimeStructure, modeltype::EMB.AbstractInvestmentModel)
     ```
     as this can lead to a method ambiguity error.
 
-## Transmission loss functions
+## [Transmission loss functions](@id man-con-trans_loss)
 
 ```julia
 constraints_trans_loss(m, tm::TransmissionMode, 𝒯ᴵⁿᵛ, modeltype::EnergyModel)
@@ -49,7 +49,7 @@ It is implemented for both the `TransmissionMode` and `PipeMode` abstract types.
 The key difference between the two is related that `PipeMode` does not allows for bidirectional transport.
 The loss is calculated for the provided `TransmissionMode`s as relative loss of the transported energy.
 
-## Balance functions
+## [Balance functions](@id man-con-balance)
 
 ```julia
 constraints_trans_balance(m, tm::TransmissionMode, 𝒯ᴵⁿᵛ, modeltype::EnergyModel)
@@ -66,7 +66,7 @@ The standard approach only relies on the conservation of mass/energy, while stor
     The implementation is working with the assumption that the initial level in a representative period is equal to the final level in the last representative period of a strategic period.
     This implies that it does not account correctly for the remaining level at the end of a representative period.
 
-## Operational expenditure constraints
+## [Operational expenditure constraints](@id man-con-opex)
 
 ```julia
 constraints_opex_fixed(m, tm::TransmissionMode, 𝒯ᴵⁿᵛ, modeltype::EnergyModel)

diff --git a/docs/src/manual/investments.md b/docs/src/manual/investments.md
@@ -0,0 +1,27 @@
+# [Adding investments](@id man-emi)
+
+Investment options are added through loading the package [`EnergyModelsInvestments`](https://energymodelsx.github.io/EnergyModelsInvestments.jl/).
+`EnergyModelsInvestments` was previously seen as extension package to `EnergyModelsBase`, that it was dependent on `EnergyModelsBase` and only allowed investment options in `EnergyModelsBase`.
+This approach was reversed from version 0.7 onwards and `EnergyModelsInvestments` is now a standalone package and provides an extension to `EnergyModelsBase`.
+
+As a consequence, it was not also necessary to move the `EnergyModelsGeography` extension of `EnergyModelsInvestments` to an `EnergyModelsInvestments` extension of `EnergyModelsGeography`.
+
+## [General concept](@id man-emi-gen)
+
+Investment options are added separately to each individual transmission mode through the field `data`.
+This is similar to the approach used in
+Hence, it is possible to use different prices for the same technology in different regions or allow investments only in a limited subset of technologies.
+
+Transmission mode investments utilize the same data type [`SingleInvData`](@extref EnergyModelsBase.SingleInvData) as the majority of the node investments.
+This type inludes as fields [`AbstractInvData`](@extref EnergyModelsInvestments.AbstractInvData) which can be either in the form of [`StartInvData`](@extref EnergyModelsInvestments.StartInvData) or [`NoStartInvData`](@extref EnergyModelsInvestments.NoStartInvData).
+The exact description of the individual investment data and their fields can be found in the *[public library](@extref EnergyModelsInvestments lib-pub)* of `EnergyModelsInvestments`.
+
+Investments require the application of an [`InvestmentModel`](@extref EnergyModelsBase.InvestmentModel) instead of an [`OperationalModel`](@extref EnergyModelsBase.OperationalModel).
+This allows us to provide two core functions with new methods, `constraints_capacity_installed` (as described on *[Constraint functions](@ref man-con)*), `variables_trans_capex`, a function previously not declaring any variables, and the update to the objective functoin `update_objective`.
+
+## [Added variables](@id man-emi-var)
+
+Investment options increase the number of variables.
+The individual variables are described in the *[documentation of `EnergyModelsInvestments`](@extref EnergyModelsInvestments man-opt_var)*.
+
+All transmission modes with investments use the prefix `:trans`.