diff --git a/docs/src/how-to/contribute.md b/docs/src/how-to/contribute.md index fa576da..6d66bbe 100644 --- 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/library/public.md b/docs/src/library/public.md index e662afc..94eac85 100644 --- a/docs/src/library/public.md +++ b/docs/src/library/public.md @@ -1,6 +1,6 @@ -# [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. @@ -8,7 +8,7 @@ Constraints related to the area keep track of a resource's export and import to 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`: diff --git a/docs/src/manual/constraint-functions.md b/docs/src/manual/constraint-functions.md index 1a79fb8..97353ef 100644 --- 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) @@ -38,7 +38,7 @@ This functions is also used to subsequently dispatch on model type for the intro ``` 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 index fea0675..3697705 100644 --- a/docs/src/manual/investments.md +++ b/docs/src/manual/investments.md @@ -16,7 +16,7 @@ Transmission mode investments utilize the same data type [`SingleInvData`] as th 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]* of `EnergyModelsInvestments`. -Investments require the application of an [`InvestmentModel`](@ref) instead of an [`OperationalModel`](@ref). +Investments require the application of an [`InvestmentModel`](@extref) 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]*), `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) diff --git a/docs/src/manual/optimization-variables.md b/docs/src/manual/optimization-variables.md index 349339c..e499433 100644 --- a/docs/src/manual/optimization-variables.md +++ b/docs/src/manual/optimization-variables.md @@ -1,4 +1,4 @@ -# [Optimization variables](@id optimization_variables) +# [Optimization variables](@id man-opt_var) `EnergyModelsGeography` adds additional variables to `EnergyModelsBase`. These variables are required for being able to extend the model with geographic information. @@ -9,7 +9,7 @@ The additional variables can be differentiated between `Area` variables and `Tra Variables that are energy/mass based have that property highlighted in the documentation below. This is only the case for the storage level in a `PipeLinepackSimple`. -## [`Area`](@ref) +## [`Area`](@id man-opt_var-area) `Area`s create only a single additional variable: @@ -21,14 +21,14 @@ The exchange resources are automatically deduced from the coupled `TransmissionM The area exchange is negative when exporting energy/mass and positive when importing. This implies that for ``\texttt{area\_exchange}[a, t, p_\texttt{ex}] > 0``, the area imports product ``p``, and for ``\texttt{area\_exchange}[a, t, p_\texttt{ex}] < 0``, the area exports product ``p_\texttt{ex}``. -## [`TransmissionMode`](@ref) +## [`TransmissionMode`](@id man-opt_var-transmission_mode) !!! warning "'Inheritance' of optimization variables" Note that for all subtypes of [`TransmissionMode`](@ref) the variables created for the parent `TransmissionMode`-type will be created, in addition to the variables created for that type. This means that the type [`PipeLinepackSimple`](@ref) will not only have access to the optimization variable ``\texttt{linepack\_stor\_level}[m, t]``, but also all the optimization variables created for [`TransmissionMode`](@ref). -### General variables for all `TransmissionMode` +### [General variables for all `TransmissionMode`](@id man-opt_var-transmission_mode-gen) All variables described in this section are included for all subtypes of [`TransmissionMode`](@ref). In general, we can differentiate between capacity variables, flow variables, cost variables, and helper variables. @@ -67,7 +67,7 @@ In addition, both ``\texttt{trans\_in}[m, t]`` and ``\texttt{trans\_out}[m, t]`` If the energy/mass is transported **opposite to the direction** of the `Transmission` corridor, then both variables are negative and ``\texttt{trans\_in}[m, t]`` corresponds to the **outlet** to the `TransmissionMode`. -### [`PipeLinepackSimple`](@ref) <: `Pipeline` <: `TransmissionMode` +### [[`PipeLinepackSimple`](@ref) <: `Pipeline` <: `TransmissionMode`](@id man-opt_var-transmission_mode-linepack) `PipeLinepackSimple` adds one additional variable: diff --git a/docs/src/manual/philosophy.md b/docs/src/manual/philosophy.md index b84401b..f675069 100644 --- a/docs/src/manual/philosophy.md +++ b/docs/src/manual/philosophy.md @@ -1,6 +1,6 @@ -# Philosophy +# [Philosophy](@id man-phil) -## General design philosophy +## [General design philosophy](@id man-phil-gen) This package extends `EnergyModelsBase` with geographical functionalities. The geographical representation is achieved through individual `Area`s coupled with `Transmission` corridors. @@ -24,7 +24,7 @@ This can be beneficial for the case of power lines *vs.* pipelines which may req We included in an internal version one approach to extend the emission constraints, but are not yet satisfied with the exact implementation. This implies that including emissions in mass/energy transport is on the agenda for future improvements. -## Extensions to the model +## [Extensions to the model](@id man-phil-ext) `EnergyModelsGeography` is also designed to be extended by the user. Extensions of `EnergyModelsGeography` are possible through @@ -32,14 +32,14 @@ Extensions of `EnergyModelsGeography` are possible through 1. specialized [`Area`](@ref)s (like the [`LimitedExchangeArea`](@ref)) and 2. new [`TransmissionMode`](@ref)s. -### Specialized `Area`s +### [Specialized `Area`s](@id man-phil-ext-area) Specialized [`Area`](@ref)s are areas with additional constraints. In general, it is possible to import and export as much as possible through the connected `Transmission` corridors. Introducing specialized [`Area`](@ref)s allow the introduciton of additional constraints within an `Area`. These constraints can include, among others, limits on the CO₂ emissions within an `Area`, export limits both on, *e.g.* operational or strategic periods as well as many other modifications. -### New [`TransmissionMode`](@ref)s +### [New [`TransmissionMode`](@ref)s](@id man-phil-ext-transmissioN_mode) New [`TransmissionMode`](@ref)s may be relevant for describing a dynamic transport mechanism or for adding a distinctive description for an energy carrier. [`TransmissionMode`](@ref)s can be developed similar to new `Node`s as described in `EnergyModelsBase`. diff --git a/docs/src/manual/quick-start.md b/docs/src/manual/quick-start.md index 85b9200..ae3c642 100644 --- a/docs/src/manual/quick-start.md +++ b/docs/src/manual/quick-start.md @@ -1,13 +1,16 @@ -# [Quick Start](@id quick_start) +# [Quick Start](@id man-quick) -> 1. Install the most recent version of [Julia](https://julialang.org/downloads/) -> 2. Install the package [`EnergyModelsBase`](https://energymodelsx.github.io/EnergyModelsBase.jl/) and the time package [`TimeStruct`](https://sintefore.github.io/TimeStruct.jl/), by running: -> ``` -> ] add TimeStruct -> ] add EnergyModelsBase -> ``` -> These packages are required as we do not only use them internally, but also for building a model. -> 3. Install the package [`EnergyModelsGeography`](https://energymodelsx.github.io/EnergyModelsGeography.jl/) -> ``` -> ] add EnergyModelsGeography -> ``` +> 1. Install the most recent version of [Julia](https://julialang.org/downloads/) +> 2. Install the package [`EnergyModelsBase`](https://energymodelsx.github.io/EnergyModelsBase.jl/) and the time package [`TimeStruct`](https://sintefore.github.io/TimeStruct.jl/), by running: +> +> ```julia +> ] add TimeStruct +> ] add EnergyModelsBase +> ``` +> +> These packages are required as we do not only use them internally, but also for building a model. +> 3. Install the package [`EnergyModelsGeography`](https://energymodelsx.github.io/EnergyModelsGeography.jl/) +> +> ```julia +> ] add EnergyModelsGeography +> ``` diff --git a/docs/src/manual/simple-example.md b/docs/src/manual/simple-example.md index f906ca4..8f6b130 100644 --- a/docs/src/manual/simple-example.md +++ b/docs/src/manual/simple-example.md @@ -1,4 +1,4 @@ -# Examples +# [Examples](@id man-exampl) For the content of the example, see the *[examples](https://github.com/EnergyModelsX/EnergyModelsGeography.jl/tree/main/examples)* directory in the project repository. diff --git a/docs/src/manual/transmission-mode.md b/docs/src/manual/transmission-mode.md index 9a9d14b..c50654b 100644 --- a/docs/src/manual/transmission-mode.md +++ b/docs/src/manual/transmission-mode.md @@ -22,4 +22,4 @@ TransmissionMode The leaf `TransmissionMode`s of the above type hierarchy tree are `composite type`s, while the inner vertices are `abstract type`s. -The individual `TransmissionMode` and their fields are explained in *[the public library](@ref sec_lib_public)*. +The individual `TransmissionMode` and their fields are explained in *[the public library](@ref lib-pub)*.