Multiple smaller updates in docs and docstrings (#49)

NEWS.md

@@ -1,6 +1,6 @@
 # Release notes
 
-## Unversioned
+## Version 0.8.2 (2024-11-27)
 
 ### Restructuring of function calls
 
@@ -26,6 +26,11 @@
 * The majority of changes are incorporated through filter functions and require the user to define new methods for the included functions (*i.e.*, `has_opex`, `has_emissions`, and `has_capacity`)
 * Inclusion of variables follows principle of additional node variables.
 
+### Minor updates
+
+* Updated som docstrings.
+* Updated some minor changes in the documentation.
+
 ## Version 0.8.1 (2024-10-16)
 
 ### Bugfixes

Project.toml

@@ -1,7 +1,7 @@
 name = "EnergyModelsBase"
 uuid = "5d7e687e-f956-46f3-9045-6f5a5fd49f50"
 authors = ["Lars Hellemo <[email protected]>, Julian Straus <[email protected]>"]
-version = "0.8.1"
+version = "0.8.2"
 
 [deps]
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"

README.md

@@ -9,25 +9,6 @@
 It is designed to model the basic operations of various generation, conversion and storage technologies.
 `EnergyModelsBase` is designed to enable optimization of operations, and to be be easily extendible to investment models, and/or to include new technologies or more detailed models of key technologies.
 
-## Error in stable documentation
-
-The stable documentation (based on the registered version) has currently the following error.
-In the description of the variables, we wrote in the [Section on capacity variables](https://energymodelsx.github.io/EnergyModelsBase.jl/stable/manual/optimization-variables/#man-opt_var-cap):
-
-```julia
-for t_inv ∈ 𝒯ᴵⁿᵛ, n ∈ 𝒩ˢᵘᵇ
-    insertvar!(stor_level_Δ_sp, n, t_inv)
-end
-```
-
-The correct solution is
-
-```julia
-for t_inv ∈ 𝒯ᴵⁿᵛ, n ∈ 𝒩ˢᵘᵇ
-    insertvar!(m[:stor_level_Δ_sp], n, t_inv)
-end
-```
-
 ## Usage
 
 The usage of the package is best illustrated through the commented [`examples`](examples).

docs/src/nodes/networknode.md

@@ -20,7 +20,7 @@ The fields of a [`RefNetworkNode`](@ref) are given as:
   Hence, it is directly related to the specified `input` and `output` ratios.
   The variable operating expenses can be provided as `OperationalProfile` as well.
 - **`opex_fixed::TimeProfile`**:\
-  The fixed operating expenses are relative to the installed capacity (through the field `cap`) and the chosen duration of a strategic period as outlined on *[Utilize `TimeStruct`](@ref how_to-utilize_TS)*.\
+  The fixed operating expenses are relative to the installed capacity (through the field `cap`) and the chosen duration of an investment period as outlined on *[Utilize `TimeStruct`](@ref how_to-utilize_TS)*.\
   It is important to note that you can only use `FixedProfile` or `StrategicProfile` for the fixed OPEX, but not `RepresentativeProfile` or `OperationalProfile`.
   In addition, all values have to be non-negative.
 - **`input::Dict{<:Resource,<:Real}`** and **`output::Dict{<:Resource,<:Real}`**:\
@@ -74,7 +74,7 @@ A qualitative overview of the individual constraints can be found on *[Constrain
 This section focuses instead on the mathematical description of the individual constraints.
 It omits the direction inclusion of the vector of network nodes (or all nodes, if nothing specific is implemented).
 Instead, it is implicitly assumed that the constraints are valid ``\forall n ∈ N^{\text{NetworkNode}}`` (for all [`NetworkNode`](@ref) types) if not stated differently.
-In addition, all constraints are valid ``\forall t \in T`` (that is in all operational periods) or ``\forall t_{inv} \in T^{Inv}`` (that is in all strategic periods).
+In addition, all constraints are valid ``\forall t \in T`` (that is in all operational periods) or ``\forall t_{inv} \in T^{Inv}`` (that is in all investment periods).
 
 The following standard constraints are implemented for a [`NetworkNode`](@ref) node.
 [`NetworkNode`](@ref) nodes utilize the declared method for all nodes 𝒩.
@@ -120,7 +120,7 @@ Hence, if you do not have to call additional functions, but only plan to include
 
   !!! tip "Why do we use `first()`"
       The variable ``\texttt{cap\_inst}`` is declared over all operational periods (see the section on *[Capacity variables](@ref man-opt_var-cap)* for further explanations).
-      Hence, we use the function ``first(t_{inv})`` to retrieve the installed capacity in the first operational period of a given strategic period ``t_{inv}`` in the function `constraints_opex_fixed`.
+      Hence, we use the function ``first(t_{inv})`` to retrieve the installed capacity in the first operational period of a given investment period ``t_{inv}`` in the function `constraints_opex_fixed`.
 
 - `constraints_opex_var`:
 
@@ -129,7 +129,7 @@ Hence, if you do not have to call additional functions, but only plan to include
   ```
 
   !!! tip "The function `scale_op_sp`"
-      The function [``scale\_op\_sp(t_{inv}, t)``](@ref scale_op_sp) calculates the scaling factor between operational and strategic periods.
+      The function [``scale\_op\_sp(t_{inv}, t)``](@ref scale_op_sp) calculates the scaling factor between operational and investment periods.
       It also takes into account potential operational scenarios and their probability as well as representative periods.
 
 - `constraints_data`:\

docs/src/nodes/sink.md

@@ -64,7 +64,7 @@ A qualitative overview of the individual constraints can be found on *[Constrain
 This section focuses instead on the mathematical description of the individual constraints.
 It omits the direction inclusion of the vector of sink nodes (or all nodes, if nothing specific is implemented).
 Instead, it is implicitly assumed that the constraints are valid ``\forall n ∈ N^{\text{Sink}}`` for all [`Sink`](@ref) types if not stated differently.
-In addition, all constraints are valid ``\forall t \in T`` (that is in all operational periods) or ``\forall t_{inv} \in T^{Inv}`` (that is in all strategic periods).
+In addition, all constraints are valid ``\forall t \in T`` (that is in all operational periods) or ``\forall t_{inv} \in T^{Inv}`` (that is in all investment periods).
 
 The following standard constraints are implemented for a [`Sink`](@ref) node.
 [`Sink`](@ref) nodes utilize the declared method for all nodes 𝒩.
@@ -118,7 +118,7 @@ Hence, if you do not have to call additional functions, but only plan to include
   ```
 
   !!! tip "The function `scale_op_sp`"
-      The function [``scale\_op\_sp(t_{inv}, t)``](@ref scale_op_sp) calculates the scaling factor between operational and strategic periods.
+      The function [``scale\_op\_sp(t_{inv}, t)``](@ref scale_op_sp) calculates the scaling factor between operational and investment periods.
       It also takes into account potential operational scenarios and their probability as well as representative periods.
 
 - `constraints_data`:\

docs/src/nodes/source.md

@@ -20,7 +20,7 @@ The fields of a [`RefSource`](@ref) node are given as:
   Hence, it is directly related to the specified `output` ratios.
   The variable operating expenses can be provided as `OperationalProfile` as well.
 - **`opex_fixed::TimeProfile`**:\
-  The fixed operating expenses are relative to the installed capacity (through the field `cap`) and the chosen duration of a strategic period as outlined on *[Utilize `TimeStruct`](@ref how_to-utilize_TS)*.\
+  The fixed operating expenses are relative to the installed capacity (through the field `cap`) and the chosen duration of an investment period as outlined on *[Utilize `TimeStruct`](@ref how_to-utilize_TS)*.\
   It is important to note that you can only use `FixedProfile` or `StrategicProfile` for the fixed OPEX, but not `RepresentativeProfile` or `OperationalProfile`.
   In addition, all values have to be non-negative.
 - **`output::Dict{<:Resource,<:Real}`**:\
@@ -78,7 +78,7 @@ A qualitative overview of the individual constraints can be found on *[Constrain
 This section focuses instead on the mathematical description of the individual constraints.
 It omits the direction inclusion of the vector of source nodes (or all nodes, if nothing specific is implemented).
 Instead, it is implicitly assumed that the constraints are valid ``\forall n ∈ N^{\text{Source}}`` for all [`Source`](@ref) types if not stated differently.
-In addition, all constraints are valid ``\forall t \in T`` (that is in all operational periods) or ``\forall t_{inv} \in T^{Inv}`` (that is in all strategic periods).
+In addition, all constraints are valid ``\forall t \in T`` (that is in all operational periods) or ``\forall t_{inv} \in T^{Inv}`` (that is in all investment periods).
 
 The following standard constraints are implemented for a [`Source`](@ref) node.
 [`Source`](@ref) nodes utilize the declared method for all nodes 𝒩.
@@ -117,7 +117,7 @@ Hence, if you do not have to call additional functions, but only plan to include
 
   !!! tip "Why do we use `first()`"
       The variable ``\texttt{cap\_inst}`` is declared over all operational periods (see the section on *[Capacity variables](@ref man-opt_var-cap)* for further explanations).
-      Hence, we use the function ``first(t_{inv})`` to retrieve the installed capacity in the first operational period of a given strategic period ``t_{inv}`` in the function `constraints_opex_fixed`.
+      Hence, we use the function ``first(t_{inv})`` to retrieve the installed capacity in the first operational period of a given investment period ``t_{inv}`` in the function `constraints_opex_fixed`.
 
 - `constraints_opex_var`:
 
@@ -126,7 +126,7 @@ Hence, if you do not have to call additional functions, but only plan to include
   ```
 
   !!! tip "The function `scale_op_sp`"
-      The function [``scale\_op\_sp(t_{inv}, t)``](@ref scale_op_sp) calculates the scaling factor between operational and strategic periods.
+      The function [``scale\_op\_sp(t_{inv}, t)``](@ref scale_op_sp) calculates the scaling factor between operational and investment periods.
       It also takes into account potential operational scenarios and their probability as well as representative periods.
 
 - `constraints_data`:\

docs/src/nodes/storage.md

@@ -1,6 +1,6 @@
 # [Storage](@id nodes-storage)
 
-[`Storage`](@ref) nodes are subtypes of [`Storage`](@ref) as they have in general an input and output (except for permanent CO2 storage).
+[`Storage`](@ref) nodes are subtypes of [`Storage`](@ref) as they have in general an input and output (except for permanent CO₂ storage).
 Storages require additional variables and parameters.
 As a consequence, a new abstract type is specified.
 
@@ -16,15 +16,15 @@ As `TimeStruct`, and hence, `EnergyModelsBase` supports the inclusion of both re
 The structure of the level balance calculation is explained on *[Storage level constraints](@ref man-con-stor_level)* while you can find the mathematical description in the Section *[Level constraints](@ref nodes-storage-math-con-level)*.
 
 We differentiate between [`Accumulating`](@ref) and [`Cyclic`](@ref) storage behaviors.
-The former allows for a net change of the storage level within a strategic period, while the latter requires a cyclic behavior for the level balance.
+The former allows for a net change of the storage level within an investment period, while the latter requires a cyclic behavior for the level balance.
 
 A single concrete type is included for `Accumulating` using [`AccumulatingEmissions`](@ref). This type was introduced for [`ResourceEmit`](@ref) resources to represent a permanent storage node.
 It was initially utilized for CO₂ storage.
 
 Two concrete types are included for [`Cyclic`](@ref), [`CyclicRepresentative`](@ref) and [`CyclicStrategic`](@ref).
 These two types differ only if the time structure includes representative periods.
 If not, they are equivalent.
-In the case of inclusion of representative periods, [`CyclicRepresentative`](@ref) enforces the cyclic constraint within a representative period while [`CyclicStrategic`](@ref) enforces the cyclic constraint within the strategic period.
+In the case of inclusion of representative periods, [`CyclicRepresentative`](@ref) enforces the cyclic constraint within a representative period while [`CyclicStrategic`](@ref) enforces the cyclic constraint within the investment period.
 In the case of [`CyclicStrategic`](@ref), we hence allow for a net change in the storage level within a representative period.
 This net change is then used for the scaling.
 
@@ -61,11 +61,10 @@ The fields of a [`RefStorage`](@ref) are given as:
 
 - **`id`**:\
   The field `id` is only used for providing a name to the node.
-- **`charge::UnionCapacity`**:\
-  The charge storage parameters must include a capacity for charging.
-  More information can be found on *[storage parameters](@ref lib-pub-nodes-stor_par)*.
+- **`charge::AbstractStorageParameters`**:\
+    More information can be found on *[storage parameters](@ref lib-pub-nodes-stor_par)*.
 - **`level::UnionCapacity`**:\
-  The level storage parameters must include a capacity for charging.
+  The level storage parameters must include a capacity.
   More information can be found on *[storage parameters](@ref lib-pub-nodes-stor_par)*.
   !!! note "Permitted values for storage parameters in `charge` and `level`"
       If the node should contain investments through the application of [`EnergyModelsInvestments`](https://energymodelsx.github.io/EnergyModelsInvestments.jl/), it is important to note that you can only use `FixedProfile` or `StrategicProfile` for the capacity, but not `RepresentativeProfile` or `OperationalProfile`.
@@ -115,10 +114,10 @@ The variables of [`Storage`](@ref)s include:
 
 - [``\texttt{opex\_var}``](@ref man-opt_var-opex)
 - [``\texttt{opex\_fixed}``](@ref man-opt_var-opex)
+- [``\texttt{stor\_level\_inst}``](@ref man-opt_var-cap)
 - [``\texttt{stor\_level}``](@ref man-opt_var-cap)
-- [``\texttt{stor\_level\_inst}``](@ref man-opt_var-cap) if the `Storage` has the field `charge` with a capacity
+- [``\texttt{stor\_charge\_inst}``](@ref man-opt_var-cap) if the `Storage` has the field `charge` with a capacity
 - [``\texttt{stor\_charge\_use}``](@ref man-opt_var-cap)
-- [``\texttt{stor\_charge\_inst}``](@ref man-opt_var-cap)
 - [``\texttt{stor\_discharge\_inst}``](@ref man-opt_var-cap) if the `Storage` has the field `discharge` with a capacity
 - [``\texttt{stor\_discharge\_use}``](@ref man-opt_var-cap)
 - [``\texttt{flow\_in}``](@ref man-opt_var-flow)
@@ -133,7 +132,7 @@ A qualitative overview of the individual constraints can be found on *[Constrain
 This section focuses instead on the mathematical description of the individual constraints.
 It omits the direction inclusion of the vector of network nodes (or all nodes, if nothing specific is implemented).
 Instead, it is implicitly assumed that the constraints are valid ``\forall n ∈ N^{\text{Storage}}`` for all [`Storage`](@ref) types if not stated differently.
-In addition, all constraints are valid ``\forall t \in T`` (that is in all operational periods) or ``\forall t_{inv} \in T^{Inv}`` (that is in all strategic periods).
+In addition, all constraints are valid ``\forall t \in T`` (that is in all operational periods) or ``\forall t_{inv} \in T^{Inv}`` (that is in all investment periods).
 
 The following standard constraints are implemented for a [`Storage`](@ref) node.
 [`Storage`](@ref) nodes utilize the declared method for all nodes 𝒩.
@@ -215,7 +214,7 @@ Hence, if you do not have to call additional functions, but only plan to include
 
   !!! tip "Why do we use `first()`"
       The variables ``\texttt{stor\_level\_inst}`` are declared over all operational periods (see the section on *[Capacity variables](@ref man-opt_var-cap)* for further explanations).
-      Hence, we use the function ``first(t_{inv})`` to retrieve the installed capacities in the first operational period of a given strategic period ``t_{inv}`` in the function `constraints_opex_fixed`.
+      Hence, we use the function ``first(t_{inv})`` to retrieve the installed capacities in the first operational period of a given investment period ``t_{inv}`` in the function `constraints_opex_fixed`.
 
 - `constraints_opex_var`:
 
@@ -229,7 +228,7 @@ Hence, if you do not have to call additional functions, but only plan to include
   ```
 
   !!! tip "The function `scale_op_sp`"
-      The function [``scale\_op\_sp(t_{inv}, t)``](@ref scale_op_sp) calculates the scaling factor between operational and strategic periods.
+      The function [``scale\_op\_sp(t_{inv}, t)``](@ref scale_op_sp) calculates the scaling factor between operational and investment periods.
       It also takes into account potential operational scenarios and their probability as well as representative periods.
 
 - `constraints_data`:\
@@ -308,7 +307,7 @@ It is calculated through the function `previous_level`.
 
 We can distinguish the following cases:
 
-1. The first operational period (in the first representative period) in a strategic period (given by ``typeof(t_{prev}) = typeof(t_{rp, prev}) = = nothing``).
+1. The first operational period (in the first representative period) in an investment period (given by ``typeof(t_{prev}) = typeof(t_{rp, prev}) = = nothing``).
    In this situation, the previous level is dependent on the chosen storage behavior.
    In the default case of a [`Cyclic`](@ref) behaviors, it is given by the last operational period of either the strategic or representative period:
 
@@ -330,15 +329,15 @@ We can distinguish the following cases:
    \end{aligned}
    ```
 
-   ``t_{rp,last}`` corresponds in this situation to the last representative period in the current strategic period.
+   ``t_{rp,last}`` corresponds in this situation to the last representative period in the current investment period.
 
    If the storage behavior is instead given by [`CyclicStrategic`](@ref), the previous level is set to 0:
 
    ```math
    prev\_level = 0
    ```
 
-2. The first operational period in subsequent representative periods in any strategic period (given by ``typeof(t_{prev}) = nothing``).
+2. The first operational period in subsequent representative periods in any investment period (given by ``typeof(t_{prev}) = nothing``).
    The previous level is again dependent on the chosen storage behavior.
    The default approach calculates it as:
 

examples/network.jl

@@ -102,7 +102,7 @@ function generate_example_network()
             StorCapOpex(
                 FixedProfile(60),       # Charge capacity in t/h
                 FixedProfile(9.1),      # Storage variable OPEX for the charging in EUR/t
-                FixedProfile(0)        # Storage fixed OPEX for the charging in EUR/(t/h 8h)
+                FixedProfile(0)         # Storage fixed OPEX for the charging in EUR/(t/h 8h)
             ),
             StorCap(FixedProfile(600)), # Storage capacity in t
             CO2,                        # Stored resource

ext/EMIExt/checks.jl

@@ -153,15 +153,15 @@ function check_inv_data(
         end
     else
         submessage =
-            "are not allowed for the capacity of the investment data" * message *
+            "are not allowed for the capacity of the investment data " * message *
             ", if investments are allowed and the chosen investment type is `NoStartInvData`."
         bool_sp = EMB.check_strategic_profile(capacity_profile, submessage)
         if bool_sp
             @assert_or_log(
                 sum(capacity_profile[t_inv] ≤ EMI.max_installed(inv_data, t_inv) for t_inv ∈ 𝒯ᴵⁿᵛ) ==
                     length(𝒯ᴵⁿᵛ),
                 "The existing capacity can not be larger than the maximum installed value in " *
-                "all strategic periods for the capacity coupled to the investment data" *
+                "all strategic periods for the capacity coupled to the investment data " *
                 message * "."
             )
         end
@@ -171,7 +171,7 @@ function check_inv_data(
     if isa(EMI.investment_mode(inv_data), Union{ContinuousInvestment,SemiContiInvestment})
         @assert_or_log(
             sum(EMI.min_add(inv_data, t) ≤ EMI.max_add(inv_data, t) for t ∈ 𝒯) == length(𝒯),
-            "`min_add` has to be less than `max_add` in the investment data" *
+            "`min_add` has to be less than `max_add` in the investment data " *
             message * "."
         )
     end