diff --git a/NEWS.md b/NEWS.md index 28ceda9..c8df10b 100644 --- a/NEWS.md +++ b/NEWS.md @@ -4,6 +4,8 @@ * Updated the variable page description to improve clarity regarding inclusion of scaling. * Included `OperationalScenarios` in the page on utilizing `TimeStruct`. +* Corrected stale docstrings. +* Corrected typos in both docstrings and documentation. ## Version 0.10.7 (2026-08-11) diff --git a/docs/src/how-to/contribute.md b/docs/src/how-to/contribute.md index b746b89..7366c23 100644 --- a/docs/src/how-to/contribute.md +++ b/docs/src/how-to/contribute.md @@ -16,7 +16,7 @@ This is explained in *[How to create a new node](@ref how_to-create_node)*. ## [File a bug report](@id how_to-con-bug_rep) -Another approach to contributing to `EnergyModelsBase` is through filing a bug report as an *[issue](https://github.com/EnergyModelsX/EnergyModelsBase.jl/issues/new)* when unexpected behaviour is occuring. +Another approach to contributing to `EnergyModelsBase` is through filing a bug report as an *[issue](https://github.com/EnergyModelsX/EnergyModelsBase.jl/issues/new)* when unexpected behaviour is occurring. When filing a bug report, please follow the following guidelines: @@ -55,7 +55,7 @@ Feature requests can be achieved through two approaches: Creating a new *[issue](https://github.com/EnergyModelsX/EnergyModelsBase.jl/issues/new)* for a feature request is our standard approach for extending `EnergyModelsBase`. Due to the extendibility of `EnergyModelsBase`, it is not necessarily straight forward to understand how to best incorporate required features into the framework without breaking other packages. -When creating a new issue as feature request, please follow the the following guidelines. +When creating a new issue as feature request, please follow the following guidelines. 1. **Reason for the feature**: Please describe the reasoning for the feature request. What functionality do you require in the core structure of `EnergyModelsBase`? 2. **Required outcome**: What should be the outcome when including the feature and what should be the minimum requirements of the outcome? diff --git a/docs/src/how-to/create-new-node.md b/docs/src/how-to/create-new-node.md index 0c87296..e2c7cfd 100644 --- a/docs/src/how-to/create-new-node.md +++ b/docs/src/how-to/create-new-node.md @@ -46,12 +46,12 @@ This is however only advised if you do not need to access the value of the varia The function is used for dispatching on the constraints for investments while the field `data` is used for providing the `InvestmentData`. 2. Emissions can be included in any way. It is however beneficial to reutilize the [`EmissionsData`](@ref) type to improve usability with other packages. - This requries again the inclusion of the field `data` in `NewNodeType`. + This requires again the inclusion of the field `data` in `NewNodeType`. It is possible to also create new subtypes for `EmissionsData` as well as dispatch on the function [`constraints_ext_data(m, n::Node, ๐’ฏ, ๐’ซ, modeltype, data::ExtensionData)`](@ref man-data_fun). 3. It is in a first stage not important to include functions for handling all possible `TimeStructure`s, that is, *e.g.*, `RepresentativePeriods`. - Instead, and error can be provided if an unsupported `TimeStructure` is chosen. + Instead, an error can be provided if an unsupported `TimeStructure` is chosen. 4. The existing reference nodes and their respective *[constraint functions](@ref man-con)* can serve as idea generators. -5. It is possible to include constraints that are coupled to another `Node` by introduing a field with the `Node` as type in the `NewNodeType`, *e.g.*, a field `node::Storage` when you plan to include additional constraints including a `Storage` node. +5. It is possible to include constraints that are coupled to another `Node` by introducing a field with the `Node` as type in the `NewNodeType`, *e.g.*, a field `node::Storage` when you plan to include additional constraints including a `Storage` node. 6. `EnergyModelsBase` utilize functions for accessing the fields of the individual nodes. These functions can be found in *[Functions for accessing fields of `Node` types](@ref lib-pub-nodes-fun_field)*. In general, these functions dispatch on `abstract type`s. diff --git a/docs/src/how-to/create_new_element.md b/docs/src/how-to/create_new_element.md index 9b9fb78..01e5436 100644 --- a/docs/src/how-to/create_new_element.md +++ b/docs/src/how-to/create_new_element.md @@ -68,10 +68,10 @@ You have to be aware of the following requirements. The latter can be inspired by [`get_nodes`](@ref) and [`get_links`](@ref). !!! danger "Couplings with existing elements" - Coupling a new element with existing elements is highly dangereous. + Coupling a new element with existing elements is highly dangerous. A major problem is that you can create additional constraints that result in the problem being unfeasible. As an example, consider the function `constraints_couple` for nodes and links. In this function, we incorporate the coupling between the different links and nodes. - In practice, a link can only have a single input and output, while a node can be connected to an arbirtrary number of links. + In practice, a link can only have a single input and output, while a node can be connected to an arbitrary number of links. If you now want to include a new element coupled to a `Node` *via* the flow variables, it is necessary that you only allow these couplings with a novel introduced node, in which the internal energy balance is adjusted to account for the new coupling. diff --git a/docs/src/how-to/update-models.md b/docs/src/how-to/update-models.md index 5769495..3950f0c 100644 --- a/docs/src/how-to/update-models.md +++ b/docs/src/how-to/update-models.md @@ -1,7 +1,7 @@ # [Update your model to the latest versions](@id how_to-update) `EnergyModelsBase` is still in a pre-release version. -Hence, there are frequently breaking changes occuring, although we plan to keep backwards compatibility. +Hence, there are frequently breaking changes occurring, although we plan to keep backwards compatibility. This document is designed to provide users with information regarding how they have to adjust their models to keep compatibility to the latest changes. We will as well implement information regarding the adjustment of extension packages, although this is more difficult due to the vast majority of potential changes. diff --git a/docs/src/index.md b/docs/src/index.md index 6a96478..93682c2 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -11,7 +11,7 @@ For running a basic energy system model, only the base technology package `Energ The main package provides simple descriptions for energy sources, sinks, conversion, and storage units. It corresponds to an operational model without geographic features. -Other packages can the optionally be added if specific functionality or technology nodes are needed. The most important packages are +Other packages can optionally be added if specific functionality or technology nodes are needed. The most important packages are - [`EnergyModelsGeography`](https://energymodelsx.github.io/EnergyModelsGeography.jl/): this package makes it possible to easily extend your energy model with different diff --git a/docs/src/library/public/case_element.md b/docs/src/library/public/case_element.md index 65e075e..b84dac0 100644 --- a/docs/src/library/public/case_element.md +++ b/docs/src/library/public/case_element.md @@ -37,7 +37,7 @@ It contains all information for building a model using the [`create_model`](@ref The fields of the case dictionary correspond to: 1. **`T::TimeStructure`** is the time structure for which the model should be constructed. - Time structures are created using the the [`TimeStruct`](https://sintefore.github.io/TimeStruct.jl/stable/) package. + Time structures are created using the [`TimeStruct`](https://sintefore.github.io/TimeStruct.jl/stable/) package. `EnergyModelsBase` supports all time structures included in `TimeStruct`. However, storage balances may violate the upper and lower bound when the time structure includes [`OperationalScenarios](@extref TimeStruct.OperationalScenarios). In general, it is preferable to utilize either a [`TwoLevel`](@extref TimeStruct.TwoLevel) or [`TwoLevelTree`](@extref TimeStruct.TwoLevelTree) to properly calculate the operational costs and the emissions. diff --git a/docs/src/nodes/source.md b/docs/src/nodes/source.md index f2d56df..cd5d8e8 100644 --- a/docs/src/nodes/source.md +++ b/docs/src/nodes/source.md @@ -32,7 +32,7 @@ The fields of a [`RefSource`](@ref) node are given as: - **`data::Vector{ExtensionData}`**:\ An entry for providing additional data to the model. In the current version, it is used for both providing `EmissionsData` and additional investment data when [`EnergyModelsInvestments`](https://energymodelsx.github.io/EnergyModelsInvestments.jl/) is used. - When using `EmissionsData`, only process emissions can be considered, that is the types [`EmissionsProcess`](@ref) and that is the types [`EmissionsProcess`](@ref) and [`CaptureProcessEmissions`](@ref). + When using `EmissionsData`, only process emissions can be considered, that is the types [`EmissionsProcess`](@ref) and [`CaptureProcessEmissions`](@ref). Specifying energy related emissions will not have an impact as there is no energy conversion within a `Source` node. !!! note "Constructor for `RefSource`" The field `data` is not required as we include a constructor when the value is excluded. diff --git a/docs/src/nodes/storage.md b/docs/src/nodes/storage.md index c59e6d9..6276478 100644 --- a/docs/src/nodes/storage.md +++ b/docs/src/nodes/storage.md @@ -31,7 +31,7 @@ This net change is then used for the scaling. ### [Capacities](@id nodes-storage-phil-capacities) Storage nodes can have up to three capacities, `charge`, storage `level`, and `discharge`. -In practice, a storage allways requires a level capacity corresponding to the maximum amount of stored energy. +In practice, a storage always requires a level capacity corresponding to the maximum amount of stored energy. However, it is not necessary to include `charge` and `discharge` capacities if they are 1. not representing an additional cost and diff --git a/ext/EMIExt/checks.jl b/ext/EMIExt/checks.jl index 369a051..c506e49 100644 --- a/ext/EMIExt/checks.jl +++ b/ext/EMIExt/checks.jl @@ -89,7 +89,7 @@ Performs various checks on investment data introduced within EnergyModelsInvestm - The field `:min_add` has to be less than `:max_add` if the investment mode is given by `ContinuousInvestment` or `SemiContiInvestment`. - Existing capacity cannot be larger than `:max_inst` capacity in the beginning. - If `NoStartInvData` is used, it also checks that the the `TimeProfile` `capacity_profile` + If `NoStartInvData` is used, it also checks that the `TimeProfile` `capacity_profile` is not including `OperationalProfile`, `RepresentativeProfile`, or `ScenarioProfile` to avoid indexing problems. """ diff --git a/ext/EMIExt/variables_capex.jl b/ext/EMIExt/variables_capex.jl index ba098e6..57ca414 100644 --- a/ext/EMIExt/variables_capex.jl +++ b/ext/EMIExt/variables_capex.jl @@ -30,9 +30,9 @@ user with two individual methods for both `๐’ฉ::Vector{<:EMB.Node}` and ๐’ฉ::V - `**prefix**_current` is the capacity of node `n` in investment period `t_inv`. It is introduced in addition to `cap_inst` to simplify the model design. - `**prefix**_add` are the additions in the installed capacity of node `n` in investment - period `t_inv`. Capacity additions are occuring at the beginning of an investment period. + period `t_inv`. Capacity additions are occurring at the beginning of an investment period. - `**prefix**_rem` are the reduction in the installed capacity of node `n` in investment - period `t_inv`. Capacity reductions are occuring at the end of an investment period. + period `t_inv`. Capacity reductions are occurring at the end of an investment period. - `**prefix**_invest_b` is an auxiliary variable used in some investment modes for the additions in capacities. - `**prefix**_remove_b` is an auxiliary variable used in some investment modes for the diff --git a/src/EnergyModelsBase.jl b/src/EnergyModelsBase.jl index 35bafd0..6c8f55a 100644 --- a/src/EnergyModelsBase.jl +++ b/src/EnergyModelsBase.jl @@ -2,7 +2,7 @@ Main module for `EnergyModelsBase` a framework for building flexible energy system models. It exports several types and associated functions for accessing fields. -In addition, all required functions for creaeting and running the model are exported. +In addition, all required functions for creating and running the model are exported. You can find the exported types and functions below or on the pages *[Constraint functions](@ref man-con)* and diff --git a/src/checks.jl b/src/checks.jl index 3bd321a..a707d43 100644 --- a/src/checks.jl +++ b/src/checks.jl @@ -248,7 +248,7 @@ function check_elements( ) @assert_or_log( all(p_in โˆˆ outputs(l.from) for p_in โˆˆ inputs(l)), - "Not all resources specifed as `inputs` of the link are specified as `outputs` " * + "Not all resources specified as `inputs` of the link are specified as `outputs` " * "of the node in the field `:from`. As a consequence, the link could potentially " * "be not utilized in the model." ) @@ -263,7 +263,7 @@ function check_elements( ) @assert_or_log( all(p_out โˆˆ inputs(l.to) for p_out โˆˆ outputs(l)), - "Not all resources specifed as `outputs` of the link are specified as `inputs` " * + "Not all resources specified as `outputs` of the link are specified as `inputs` " * "of the node in the field `:to`. As a consequence, the link could potentially " * "not be utilized in the model." ) diff --git a/src/constraint_functions.jl b/src/constraint_functions.jl index 4e1b352..71ac606 100644 --- a/src/constraint_functions.jl +++ b/src/constraint_functions.jl @@ -251,7 +251,7 @@ function constraints_level_aux( @constraint(m, [t โˆˆ ๐’ฏ], m[:stor_level_ฮ”_op][n, t] == m[:stor_charge_use][n, t]) # Set the lower bound for the emissions in the storage node (:emissions_node) and to - # avoid that emissions larger than the flow into the storage. + # avoid that emissions are larger than the flow into the storage. # Fix all other emissions to a value of 0 # Fix the variables :stor_discharge_use and :flow_out to 0 for t โˆˆ ๐’ฏ @@ -305,7 +305,7 @@ function constraints_level_iterate( # Constraint for the total change in the level in a given representative period @constraint(m, [t_rp โˆˆ ๐’ฏสณแต–], m[:stor_level_ฮ”_rp][n, t_rp] == - sum(m[:stor_level_ฮ”_op][n, t] * scale_op_sp(per, t) for t โˆˆ t_rp) + sum(m[:stor_level_ฮ”_op][n, t] * scale_op_sp(per, t) for t โˆˆ t_rp) ) # Iterate through the operational structure @@ -378,9 +378,9 @@ end ) In the case of `SimpleTimes`, the iterator function is at its lowest level. In this -situation,the previous level is calculated using the function [`previous_level`](@ref) and -used for the storage balance. The the approach for calculating the `previous_level` is -depending on the types in the parameteric type `PreviousPeriods`. +situation, the previous level is calculated using the function [`previous_level`](@ref) and +used for the storage balance. The approach for calculating the `previous_level` is +depending on the types in the parametric type `PreviousPeriods`. In addition, additional bounds can be included on the initial level within an operational period. @@ -417,7 +417,7 @@ end """ constraints_level_rp(m, n::Storage, per, modeltype::EnergyModel) -Provides additional contraints for representative periods. +Provides additional constraints for representative periods. The default approach is to set the total change in all representative periods within a strategic period to 0. This implies that the `Storage` node cannot accumulate energy between @@ -554,8 +554,8 @@ end modeltype::EnergyModel, ) -When representative periods are used and the previous operational period is `nothing`, then -bounds are incorporated to avoid that the initial level storage level is violating the +When representative periods are used and the previous operational period is `nothing`, then +bounds are incorporated to avoid that the initial storage level is violating the maximum and minimum level. """ function constraints_level_bounds( @@ -656,7 +656,7 @@ In the case of a `Storage` node, the fallback option includes variable OPEX for `level`, and `discharge` if the node has the corresponding storage parameter. The individual contributions are in all situations calculated based on the installed capacities. -In the case of a `Sink` node, the variable OPEX is calculate through the penalties for both +In the case of a `Sink` node, the variable OPEX is calculated through the penalties for both `surplus` and `deficit`. """ function constraints_opex_var(m, n::Node, ๐’ฏแดตโฟแต›, modeltype::EnergyModel) diff --git a/src/data_functions.jl b/src/data_functions.jl index 181d272..ba4d0cf 100644 --- a/src/data_functions.jl +++ b/src/data_functions.jl @@ -6,7 +6,7 @@ constraints_ext_data(m, n::Node, ๐’ฏ, ๐’ซ, modeltype::EnergyModel, data::CaptureProcessEnergyEmissions) Constraints functions for calculating both the emissions and amount of COโ‚‚ captured in the -process. If the data ia a [`CaptureData`](@ref), it provides the constraint for the variable +process. If the data is a [`CaptureData`](@ref), it provides the constraint for the variable :flow_out of COโ‚‚. There exist several configurations: @@ -174,7 +174,7 @@ constraints_ext_data(m, n::Node, ๐’ฏ, ๐’ซ, modeltype::EnergyModel, data::Exten constraints_data(m, n::Node, ๐’ฏ, ๐’ซ, modeltype::EnergyModel, data::ExtensionData) Legacy function for calling the new function [`constraints_ext_data`](@ref). -The function will be removed in release 0.10. +The function will be removed in release 0.11. """ function constraints_data(m, n::Node, ๐’ฏ, ๐’ซ, modeltype::EnergyModel, data::ExtensionData) constraints_ext_data(m, n, ๐’ฏ, ๐’ซ, modeltype, data) diff --git a/src/model.jl b/src/model.jl index 45a3341..398e5c7 100644 --- a/src/model.jl +++ b/src/model.jl @@ -343,9 +343,9 @@ function variables_capex(m, ๐’ฉ::Vector{<:Node}, ๐’ณแต›แต‰แถœ, ๐’ฏ, modeltype function variables_capex(m, โ„’::Vector{<:Link}, ๐’ณแต›แต‰แถœ, ๐’ฏ, modeltype::EnergyModel) end """ - variables_emission(m, โ„’::Vector{<:Node}, ๐’ซ, ๐’ฏ, modeltype::EnergyModel) - variables_emission(m, โ„’::Vector{<:Link}, ๐’ซ, ๐’ฏ, modeltype::EnergyModel) - variables_emission(m, ๐’ฏ, ๐’ซ, modeltype::EnergyModel) + variables_emission(m, ๐’ฉ::Vector{<:Node}, ๐’ณแต›แต‰แถœ, ๐’ซ, ๐’ฏ, modeltype::EnergyModel) + variables_emission(m, โ„’::Vector{<:Link}, ๐’ณแต›แต‰แถœ, ๐’ซ, ๐’ฏ, modeltype::EnergyModel) + variables_emission(m, ๐’ซ, ๐’ฏ, modeltype::EnergyModel) Declaration of emissions variables for the element types introduced in `EnergyModelsBase` as well as global emission variables. `EnergyModelsBase` introduces two elements for an @@ -359,23 +359,23 @@ including the global variables: direct air capture. !!! tip "Link variables" - - `emissions_node[n_em, t, p_em]` are the emissions of link `l_em` with emissions in + - `emissions_link[l_em, t, p_em]` are the emissions of link `l_em` with emissions in operational period `t` of emission resource `p_em`. The values can only be positive as links should not allow for removal. !!! warning "Global variables" - - `emissions_total[t, p_em]` are the total emissions of in operational period `t` of + - `emissions_total[t, p_em]` are the total emissions in operational period `t` of emission resource `p_em`. The values can be negative to account for removal of emissions resources from the environment, through, *e.g.*, direct air capture. - - `emissions_strategic[t_inv, p_em]` are the total emissions of in operational period - `t` of emission resource `p_em`. The values can be negative to account for removal of - emissions resources from the environment, through, *e.g.*, direct air capture. The + - `emissions_strategic[t_inv, p_em]` are the total emissions in strategic period + `t_inv` of emission resource `p_em`. The values can be negative to account for removal + of emissions resources from the environment, through, *e.g.*, direct air capture. The variable has an upper bound introduced through the function [`emission_limit`](@ref) of the `EnergyModel`. The inclusion of node and link emissions require that the function `has_emissions` returns `true` for the given node or link. This is by default achieved for nodes through inclusion -of `EmissionData` in nodes while links require you to explicitly provide a method for your +of `EmissionsData` in nodes while links require you to explicitly provide a method for your link type. """ function variables_emission(m, ๐’ฉ::Vector{<:Node}, ๐’ณแต›แต‰แถœ, ๐’ซ, ๐’ฏ, modeltype::EnergyModel) diff --git a/src/structures/link.jl b/src/structures/link.jl index cf54b4f..1e6b62e 100644 --- a/src/structures/link.jl +++ b/src/structures/link.jl @@ -3,7 +3,7 @@ Declaration of the general type for formulation of [`Link`](@ref)s. Formulations can be utilized to provide specific constraint functions for a [`Link`](@ref) while keeping other -constraints unchanged. These subfunctions can be then utlized for several types of `Link`. +constraints unchanged. These subfunctions can be then utilized for several types of `Link`. """ abstract type Formulation end diff --git a/src/structures/node.jl b/src/structures/node.jl index 1ef07a8..e0a0361 100644 --- a/src/structures/node.jl +++ b/src/structures/node.jl @@ -42,7 +42,7 @@ abstract type Cyclic <: StorageBehavior end """ struct AccumulatingEmissions <: Accumulating -`StorageBehavior` which accumulates all inflow witin a strategic period. +`StorageBehavior` which accumulates all inflow within a strategic period. `AccumulatingEmissions` allows as well to serve as a [`ResourceEmit`](@ref) emission point to represent a soft constraint on storing the captured emissions. """ @@ -56,14 +56,14 @@ excluding operational times. In the case of `TwoLevel{SimpleTimes}`, this approach is similar to `CyclicStrategic`. In the case of `TwoLevel{RepresentativePeriods{SimpleTimes}}`, this approach differs from -`CyclicStrategic` as the cyclic constraint is enforeced within each representative period. +`CyclicStrategic` as the cyclic constraint is enforced within each representative period. """ struct CyclicRepresentative <: Cyclic end """ struct CyclicStrategic <: Cyclic -`StorageBehavior` in which the the cyclic behaviour is achieved within a strategic period. +`StorageBehavior` in which the cyclic behaviour is achieved within a strategic period. This implies that the initial level in individual representative periods can be different when using `RepresentativePeriods`. """ @@ -224,7 +224,7 @@ or `StrategicProfile`. # Fields - **`id`** is the name/identifier of the node. - **`cap::TimeProfile`** is the installed capacity. -- **`opex_var::TimeProfile`** is the variable operating expense per per capacity usage +- **`opex_var::TimeProfile`** is the variable operating expense per capacity usage through the variable `:cap_use`. - **`opex_fixed::TimeProfile`** is the fixed operating expense per installed capacity through the variable `:cap_inst`. @@ -263,7 +263,7 @@ The capacity is hereby normalized to a conversion value of 1 in the fields `inpu # Fields - **`id`** is the name/identifier of the node. - **`cap::TimeProfile`** is the installed capacity. -- **`opex_var::TimeProfile`** is the variable operating expense per per capacity usage +- **`opex_var::TimeProfile`** is the variable operating expense per capacity usage through the variable `:cap_use`. - **`opex_fixed::TimeProfile`** is the fixed operating expense per installed capacity through the variable `:cap_inst`. @@ -465,7 +465,7 @@ has_emissions(n::Availability) = false has_emissions(n::RefStorage{AccumulatingEmissions}) = true """ - has_emissions(๐’ฉ::Array{<:Node}) + nodes_emissions(๐’ฉ::Array{<:Node}) Returns nodes that have emission data for a given Array `::Array{<:Node}`. """