Update documentation with Maaike comments

docs/src/30-concepts.md

@@ -184,7 +184,7 @@ The flows coming from the balancing hub are defined every 3 hours. Then, _min(in
 
 #### Hub Balance
 
-The hub balance is quite interesting because it integrates several flow resolutions. Remember that we didn't define any specific time resolution for this asset. Therefore, the highest resolution of all incoming and outgoing flows in the horizon implies that the hub balance must be imposed for all 6 blocks since _min(incoming flows, outgoing flows)_ becomes _min(1,2,3) = 1_
+The hub balance is quite interesting because it integrates several flow resolutions. Remember that we didn't define any specific time resolution for this asset. Therefore, the highest resolution of all incoming and outgoing flows in the horizon implies that the hub balance must be imposed for all 6 blocks since _min(incoming flows, outgoing flows)_ becomes _min(1,2,3,4) = 1_
 
 ```math
 \begin{aligned}
@@ -265,7 +265,7 @@ Therefore, the constraints are as follows:
 & \text{max\_output\_flows\_limit}_{\text{wind},3}: \\
 & \qquad v^{\text{flow}}_{(\text{wind},\text{balance}),3:6} + v^{\text{flow}}_{(\text{wind},\text{phs}),1:3} \leq p^{\text{init capacity}}_{\text{wind}} \cdot p^{\text{availability profile}}_{\text{wind},3} \\
 & \text{max\_output\_flows\_limit}_{\text{wind},4:6}: \\
-& \qquad v^{\text{flow}}_{(\text{wind},\text{balance}),3:6} + v^{\text{flow}}_{(\text{wind},\text{phs}),4:6} \leq \frac{p^{\text{init capacity}}_{\text{wind}}}{2} \cdot \sum_{b=5}^{6} p^{\text{availability profile}}_{\text{wind},b} \\
+& \qquad v^{\text{flow}}_{(\text{wind},\text{balance}),3:6} + v^{\text{flow}}_{(\text{wind},\text{phs}),4:6} \leq \frac{p^{\text{init capacity}}_{\text{wind}}}{3} \cdot \sum_{b=4}^{6} p^{\text{availability profile}}_{\text{wind},b} \\
 \end{aligned}
 ```
 
@@ -321,7 +321,8 @@ This section quantifies the advantages of the [`flexible connection`](@ref flex-
 2. Flexible connection with hourly resolution: This approach uses the flexible connection to represent the hybrid operation of the `phs` and `wind` assets.
 3. Flexible connection and flexible time: This approach uses both features, the flexible connection and the flexible time resolution.
 
-> **Note:** The flexibility of _TulipaEnergyModel.jl_ allows any of these three modeling approaches.
+!!! tip
+    The flexibility of _TulipaEnergyModel.jl_ allows any of these three modeling approaches.
 
 The table below shows the constraints and variables for each approach over a 6-hour horizon. These results show the potential of flexible connections and time resolution for reducing the size of the optimization model.
 
@@ -348,16 +349,18 @@ In the previous section, we have seen how the flexible temporal resolution is ha
 
 ![unit-commitment-case-study](./figs/unit-commitment-case-study.png)
 
-The example demonstrates various assets that supply demand. Each asset has different input data files, which activates different sets of constraints based on the method. For example, the `gas` producer has ramping constraints but not unit commitment constraints, while the `ocgt` conversion has unit commitment constraints but not ramping constraints. Lastly, the `ccgt` and `smr` assets both have unit commitment and ramping constraints.
+The example demonstrates various assets that supply demand. Each asset has different input data files, which activates different sets of constraints based on the method. For example, the `gas` producer has ramping constraints but not unit commitment constraints, while the `ocgt` conversion has unit commitment constraints but not ramping constraints. Lastly, the `ccgt` and `smr` assets both have unit commitment and ramping constraints. Moreover, `ccgt`, `wind`, `solar`, and `ocgt` are investable, meaning that the investment variable will only appear on the constraints related to those assets.
 
 ```@example unit-commitment
 using DataFrames # hide
 using CSV # hide
 input_dir = "../../test/inputs/UC-ramping" # hide
 assets_data = CSV.read(joinpath(input_dir, "asset-both.csv"), DataFrame) # hide
 graph_assets = CSV.read(joinpath(input_dir, "asset.csv"), DataFrame) # hide
+asset_milestone = CSV.read(joinpath(input_dir, "asset-milestone.csv"), DataFrame) # hide
 assets = leftjoin(graph_assets, assets_data, on=:asset) # hide
-filtered_assets = assets[assets.type .== "producer" .|| assets.type .== "conversion", ["asset", "type", "capacity", "initial_units", "unit_commitment",  "ramping"]] # hide
+assets = leftjoin(assets, asset_milestone, on=[:asset, :milestone_year]) # hide
+filtered_assets = assets[assets.type .== "producer" .|| assets.type .== "conversion", ["asset", "type", "capacity", "initial_units", "investable", "unit_commitment",  "ramping", "max_ramp_up", "max_ramp_down"]] # hide
 ```
 
 The `assets-rep-periods-partitions` file defines the time resolution for the assets in the `partition` column. For instance, here we can see that the time resolutions are 3h for the `ccgt` and 6h for the `smr`. These values mean that the unit commitment variables (e.g., `units_on`) in the model have three and six hours resolution, respectively.
@@ -398,7 +401,10 @@ In the case of the `gas` asset, there are two output flows above the minimum ope
 
 Let's now take a look at the resulting constraints in the model.
 
-`max_ramp_up(gas)`: The first constraint starts in the second timestep block and takes the difference between the output flows above the minimum operating point from $b_{k = 2:2}$ and $b_{k = 1:1}$. Note that since the $v^{\text{flow}}_{(\text{gas,ccgt}),b_k}$ is the same in both timestep blocks, the only variables that appear in this first constraint are the ones associated with the $v^{\text{flow}}_{(\text{gas,ocgt}),b_k}$. The second constraint takes the difference between the output flows from $b_{k = 3:3}$ and $b_{k = 2:2}$; in this case, there is a change in the `flow(gas, ocgt)`; therefore, the constraint considers both changes in the output flows of the asset. In addition, the ramping parameter is multiplied by the flow duration with the highest resolution, i.e., one hour, which is the duration of the $v^{\text{flow}}_{(\text{gas,ocgt}),b_k}$.
+`max_ramp_up(gas)`: The first constraint considers the ramping up of output flows of the gas asset from the first hour to the second ($b_{k = 2:2}$ to $b_{k = 1:1}$). Note that since the $v^{\text{flow}}_{(\text{gas,ccgt}),b_k}$ is defined in in blocks of 2 hours, we only need to consider the difference of the $v^{\text{flow}}_{(\text{gas,ocgt}),b_k}$ variable in this constraint. However, the second constraint takes the difference between the output flows from $b_{k = 3:3}$ to $b_{k = 2:2}$. For this constraint, we need to consider the difference in both $v^{\text{flow}}_{(\text{gas,ocgt}),b_k}$ and $v^{\text{flow}}_{(\text{gas,ccgt}),b_k}$.
+
+!!! info
+    The duration parameter in the right hand side (RHS) of this constraint, $\text{RHS} = p^{\text{capacity}}_{\text{gas}} \cdot p^{\text{max ramp up}}_{\text{gas}} \cdot p^{\text{duration}}_{b_k}$, is defined by the flow duration with the `highest resolution`, i.e., one hour, which is the duration of the $v^{\text{flow}}_{(\text{gas,ocgt}),b_k}$. We need to multiply by duration since the ramp input values are given as rates, i.e., `p.u./h` or `p.u./min`, so the RHS in the constraint must be multiplied by the duration to match the flow units. So, using the data for this example we have: $\text{RHS} = 1800 \text{MW} \cdot 0.83 \text{p.u./h} \cdot 1 \text{h} = 1494 \text{MW}$
 
 ```math
 \begin{aligned}

docs/src/40-formulation.md

@@ -361,7 +361,8 @@ Storage assets using the method to avoid charging and discharging simultaneously
 \end{aligned}
 ```
 
-**Note**: The negative sign before the $v^{\text{accumulated units}}_{a,y}$ is because the accumulated units include the $p^{\text{init units}}_{a,y}$ in its calculation.
+!!! info
+    The negative sign before the $v^{\text{accumulated units}}_{a,y}$ is because the accumulated units include the $p^{\text{init units}}_{a,y}$ in its calculation.
 
 - Maximum output flows limit for storage assets such that $a \in \mathcal{A}^{\text{sb}}_y \setminus \mathcal{A}^{\text{i}}_y$
 
@@ -397,7 +398,8 @@ Storage assets using the method to avoid charging and discharging simultaneously
 \end{aligned}
 ```
 
-**Note**: The negative sign before the $v^{\text{accumulated units}}_{a,y}$ is because the accumulated units include the $p^{\text{init units}}_{a,y}$ in its calculation.
+!!! info
+    The negative sign before the $v^{\text{accumulated units}}_{a,y}$ is because the accumulated units include the $p^{\text{init units}}_{a,y}$ in its calculation.
 
 - Maximum input flows limit for storage assets such that $a \in \mathcal{A}^{\text{sb}}_y \setminus \mathcal{A}^{\text{i}}_y$
 
@@ -415,7 +417,7 @@ v^{\text{flow}}_{f,k_y,b_{k_y}} \geq 0 \quad \forall y \in \mathcal{Y}, \forall
 
 ### [Unit Commitment Constraints](@id uc-constraints)
 
-Production and conversion assets within the set $\mathcal{A}^{\text{uc}}$ will contain the unit commitment constraints in the model. These constraints are based on the work of [Morales-España et al. (2013)](https://ieeexplore.ieee.org/document/6485014) and [Morales-España et al. (2014)](https://ieeexplore.ieee.org/document/6514884).
+Production and conversion assets within the set $\mathcal{A}^{\text{uc}}$ will contain the unit commitment constraints in the model. These constraints are based on the work of [Morales-España et al. (2013)](@ref math-references) and [Morales-España et al. (2014)](@ref math-references).
 
 The current version of the code only incorporates a basic unit commitment version of the constraints (i.e., utilizing only the unit commitment variable $v^{\text{units on}}$). However, upcoming versions will include more detailed constraints, incorporating startup and shutdown variables.
 
@@ -451,9 +453,10 @@ e^{\text{flow above min}}_{a,k_y,b_{k_y}} \geq 0  \quad
 
 Ramping constraints restrict the rate at which the output flow of a production or conversion asset can change. If the asset is part of the unit commitment set (e.g., $\mathcal{A}^{\text{uc}}_y$), the ramping limits apply to the flow above the minimum output, but if it is not, the ramping limits apply to the total output flow.
 
-Ramping constraints that take into account unit commitment variables are based on the work done by [Damcı-Kurt et. al (2016)](https://link.springer.com/article/10.1007/s10107-015-0919-9). Also, please note that since the current version of the code only handles the basic unit commitment implementation, the ramping constraints are applied to the assets in the set $\mathcal{A}^{\text{uc basic}}_y$.
+Ramping constraints that take into account unit commitment variables are based on the work done by [Damcı-Kurt et. al (2016)](@ref math-references). Also, please note that since the current version of the code only handles the basic unit commitment implementation, the ramping constraints are applied to the assets in the set $\mathcal{A}^{\text{uc basic}}_y$.
 
-> **Duration parameter**: The following constraints are multiplied by $p^{\text{duration}}_{b_{k_y}}$ on the right-hand side to adjust for the duration of the timesteps since the ramp parameters are defined as rates. This assumption is based on the idea that all timesteps are the same in this section, which simplifies the formulation. However, in a flexible temporal resolution context, this may not hold true, and the duration needs to be the minimum duration of all the outgoing flows at the timestep block $b_{k_y}$. For more information, please visit the concept section on flexible time resolution.
+!!! info "Duration parameter"
+    The following constraints are multiplied by $p^{\text{duration}}_{b_{k_y}}$ on the right-hand side to adjust for the duration of the timesteps since the ramp parameters are defined as rates. This assumption is based on the idea that all timesteps are the same in this section, which simplifies the formulation. However, in a flexible temporal resolution context, this may not hold true, and the duration needs to be the minimum duration of all the outgoing flows at the timestep block $b_{k_y}$. For more information, please visit the concept section on flexible time resolution.
 
 #### Maximum Ramp-Up Rate Limit WITH Unit Commitment Method
 
@@ -501,7 +504,7 @@ The balance constraint sense depends on the method selected in the asset file's
 
 ### Constraints for Energy Storage Assets
 
-There are two types of constraints for energy storage assets: intra-temporal and inter-temporal. Intra-temporal constraints impose limits inside a representative period, while inter-temporal constraints combine information from several representative periods (e.g., to model seasonal storage). For more information on this topic, refer to the [concepts section](@ref storage-modeling) or [Tejada-Arango et al. (2018)](https://ieeexplore.ieee.org/document/8334256) and [Tejada-Arango et al. (2019)](https://doi.org/10.1016/j.energy.2019.116079).
+There are two types of constraints for energy storage assets: intra-temporal and inter-temporal. Intra-temporal constraints impose limits inside a representative period, while inter-temporal constraints combine information from several representative periods (e.g., to model seasonal storage). For more information on this topic, refer to the [concepts section](@ref storage-modeling) or [Tejada-Arango et al. (2018)](@ref math-references) and [Tejada-Arango et al. (2019)](@ref math-references).
 
 In addition, we define the following expression to determine the energy investment limit of the storage assets. This expression takes two different forms depending on whether the storage asset belongs to the set $\mathcal{A}^{\text{se}}$ or not.
 
@@ -727,7 +730,8 @@ The following constraints aggregate variables of different assets depending on t
 
 These constraints apply to assets in a group using the investment method $\mathcal{G}^{\text{ai}}_y$. They help impose an investment potential of a spatial area commonly shared by several assets that can be invested there.
 
-> **Note**: These constraints are applied to the investments each year. The model does not yet have investment limits to a group's accumulated invested capacity.
+!!! info
+    These constraints are applied to the investments each year. The model does not yet have investment limits to a group's accumulated invested capacity.
 
 ##### Minimum Investment Limit of a Group