Merge pull request #23 from Jerry-Zhuoer-Feng/master

Added technical docs

Author: phumthep

docs/source/technical/dispatchable.rst

@@ -5,4 +5,59 @@
 **Dispatchable/Non-dispatchable generators**
 ===============================================
 
-Loren ipsum
+**Overview**
+
+Electric power systems rely on a mix of generation technologies. Broadly, these fall into two categories:
+    * Dispatchable generators: Facilities whose output can be adjusted up or down by the system operator (e.g., natural gas, coal), subject to physical limits (ramping limits, minimum up/down times).
+    * Non‑dispatchable generators: Units that produce energy according to an exogenous resource profile (e.g., wind turbines, solar PV), with limited or no ability for the operator to increase output beyond what nature provides.
+
+**Dispatchable generators**
+
+We model the operation of dispatchable generators using three variables:
+    
+    * Dispatch variable :math:`p_{g,t}`: Power output of generator :math:`g` at time :math:`t`. More specifically, it is split into "above-min" generation :math:`p'_{g,t}` and "at-min" generation :math:`\underline{P}_g`
+    * Commitment variable :math:`u_{g,t} \in \{0,1\}`: Binary indicator if :math:`g` is online.
+    * Starting/Shutdown variable :math:`v_{g,t}, w_{g,t} \in \{0,1\}`: Binary indicator if :math:`g` is starting up or shutting down at time :math:`t`.
+
+Each dispatchable generator is subject to constraints:
+    
+    * Capacity: The capacity is constrainted by the minimum and maximum capacity.
+        :math:`\underline{P}_g \times u_{g,t} \le P'_{g,t} + \underline{P}_g \le \bar{P}_g \times u_{g,t}`
+    
+    * Ramping limit: The change in power output from :math:`t` to :math:`t+1` cannot be over the ramping limit. 
+    * Minimum up/down time: Once started or stopped, the unit remains in that state for the specified duration.
+    * Must take: If the unit has to be included in the generation profile.
+
+We then minimize the cost of generation, for which the cost of individual dispatchable generator is given by:
+    
+    * Fixed cost: Fixed cost is a function of rated capacity and fixed cost per unit.
+        :math:`c_{g,t}^{fixed} = \bar{P}_g \times {fixed\_cost\_per\_unit}_g \times u_{g,t}`
+    
+    * Variable cost: Variable cost is a function of fuel cost, heat rate, and operating cost.
+        :math:`c_{g,t}^{var} = (({fuel\_price}_g \times {heat\_rate}_g) + {opex}_g) \times p_{g,t}`
+    
+    * Startup cost: Startup cost is a function of rated capacity and startup cost per unit.
+        :math:`c_{g,t}^{start} = P_g^{max} \times {startup\_cost}_g \times v_{g,t}`
+
+    * Curtailment cost: Curtailing "must-take" thermal output is priced as the same variable rate.
+        :math:`c_{g,t}^{curt} = (({fuel\_price}_g \times {heat\_rate}_g) + {opex}_g) \times p^curt_{g,t}`
+
+**Non-dispatchable generators**
+
+For non-dispatchable generators, the model's decision is to dispatch, curtail, or store the renewable energy produced. We therefore have:
+    
+    * Dispatched :math:`pdispatch_{g,t}`
+    * Curtailed :math:`pcurtail_{g,t}`
+    * Charged :math:`pcharge_{g,t}`
+
+Non-dispatchable generators are subject to constraints:
+    
+    * Available capacity:
+        :math:`pdispatch_{g,t} \le available\_capacity_{g,t}`
+    * Energy balance:
+        :math:`pdispatch_{g,t} + pcurtail_{g,t} + pcharge_{g,t} = available\_capacity_{g,t}`
+
+We assume non-dispatchable generators do not have a fixed or start-up cost, and we get the variable cost from the contract price:
+    
+    * Variable cost:
+        :math:`c_{g,t}^{var} = {contract\_price}_g \times pdispatch_{g,t}`

docs/source/technical/linear_power_flow.rst

@@ -5,4 +5,36 @@
 **Linearized DC power flow**
 ================================
 
-Loren ipsum
+**Overview**
+
+In alternating‐current (AC) power systems, power is transmitted at high voltages through a network of buses and transmission lines and is a crucial part of an energy system. Each line can be characterized by its series impedance (resistance and reactance). We model power flow in a by both voltage magnitudes and angles at its ends, as described by the nonlinear AC power flow equation for real power:
+
+    :math:`P_{ij}=V_i V_j(G_{ij}\cos{(\theta_i-\theta_j)} + B_{ij}\sin{(\theta_i-\theta_j)})-V_i^2G_{ij}`
+
+where :math:`V_i` is the voltage magnitude at bus :math:`i`, :math:`\theta_i` is the voltage angle, :math:`G_{ij}` and :math:`B_{ij}` are the conductance (1 over resistance) and susceptance (1 over reactance) of the line between bus :math:`i` and bus :math:`j`.
+
+The full AC equation above captures the full dynamics but is nonlinear due to the trigonometric terms and quadratic dependence on voltage magnitudes. To simplify analysis and enable efficient optimization, we use a DC power flow approximation based on:
+    
+    * **Negligible Resistance**: Line losses due to resistance are assumed small compared to reactance for high-voltage large-scale power grids, so resistances are ignored and only reactances remain.
+    * **Small Angle Differences**: Voltage angle differences are small enough that :math:`\sin{(\theta_i)}` approaches :math:`\theta_i`.
+
+therefore we simplify the real power flow on a line as follows:
+
+    :math:`P_{ij}=B_{ij}(\theta_i-\theta_j)`
+
+where :math:`P_{ij}` is the powerflow in a line, :math:`B_{ij}` is the line susceptance, and :math:`\theta_i` the voltage angle.
+
+**Model**
+
+The above formulation translates into the following in our model: 
+
+    * Decision Variables:Our decision variables therefore include :math:`\theta_i` for each bus :math:`i`, representing the phase angle; line flows :math:`F_{ij}` as auxiliary variables representing the real power on each line. 
+    * Parameters:Constant :math:`B_{ij}` representing the line susceptance between bus :math:`i` and :math:`j`.
+    * Flow: DC approcimation of power flow.
+        :math:`F_{ij}=B_{ij}(\theta_i-\theta_j)`
+    * Kirchoff's Current Law: Power Balance at each bus. :math:`P_i^{gen} - P_i^{load}` represents the net power injection (generation minus loads) at bus :math:`i`.
+        :math:`P_i^{gen} - P_i^{load} = \sum F_{ij} -  \sum F_{ji}`
+    * Line Capacity Constraint:
+        :math:`-F_{ij}^{max} \le F_{ij} \le F_{ij}^{max}`
+
+By combining these elements: angle and flow variables, a linear flow, nodal balance equations, and capacity bounds, our code realizes the classic DC power flow model entirely within a (mixed integer) linear framework.

docs/source/technical/reservoir_model.rst

@@ -5,4 +5,36 @@
 **Reservoir model**
 =======================
 
-Loren ipsum
+**Reservoir Dynamics**
+
+Reservoir storage hinges on a simple balance: water in (inflows) minus water out (releases, spills, losses) equals the change in storage. In discrete time (daily or hourly), we enforce:
+    :math:`S_{t+1}=S_t+I_t-R_t-E_t`
+
+where :math:`S_t` is the storage, :math:`I_t` the inflow, :math:`R_t` the release, and :math:`E_t` the evaporation.
+
+In optimization formulations, the balance equation becomes an equality constraint linking decision variables (release, spill) and state variables (storage). Physical limits on storage (dead storage, maximum capacity) are imposed as inequality constraints to ensure feasible reservoir levels.
+
+Besides storage, elevation is also often used as a measure of the state of a reservoir. The storage-elevation relationship :math:`S = f(h)` and its inverse :math:`h = f^{-1}(S)` can be non-linear and is defined by emprical volume curve :math:`vol\_curve`.
+
+**Reservoir Operations**
+
+We have two core modes of operation: rule-curve scheduling and dispatch-driven re-operation:
+    
+    * **Rule-curve scheduling**: Operators follow seasonal guidelines (rule curves) to choose releases to track a daily storage target while satisfying mass balance, spill, and min/max flow constraints. It has a deterministic target, such as daily storage or level targets derived from historical rule curves. Our optimization then minimizes the deviation from the target path.
+    * **Dispatch-driven re-operation**: We invert a power‐dispatch target into release decisions. We adapt reservoir releases to meet daily or hourly power-generation targets from system dispatch, while still honoring mass balance and environmental rules. Our optimization there for solve for release sequence that minimizes mismatch between computed hydropower and dispatch targets, subject to mass balance, ramp-rate bounds, ecologoical minima, and turbine & grid limits. This is done based on hydropower physics, where we calculate the power :math:`P_t` from :math:`\eta` the turbine efficiency, :math:`\rho` the water density, :math:`g` the gravitational constant, :math:`H_t` the hydraulic head (water level above turbine center), and :math:`Q^{turbine}_t` the water flow through the turbine:
+        :math:`P_t = \eta \cdot \rho \cdot g \cdot H_t \cdot Q^{turbine}_t`
+
+**Environmental Flow & Hydropeaking Constraints**
+
+To protect downstream ecosystems, maintain habitat, and prevent fish stranding, operations must respect minimum flow requirements and limit daily ramp‐rates (hydropeaking):
+    
+    * Minimum enviornmental flow: We determine the minimum amount of water that should be released from a reservoir to maintain the health of the downstream ecosystem. The minimum flow is set at different percentages of the inflow, subject to how the inflow compares with the mean annual flow.
+    * Hydropeaking: Hydropeaking is the rapid and frequent changes in river flow to optimize hydropower operation. We adjust the release based on a hydropeaking factor and the minimum environmental flow, ensuring daily changes remain within a percentage of capacity.
+
+**Cascade Coordination & Basin-Level Aggregation** 
+
+In multi‐reservoir systems, upstream releases and spills directly become downstream inflows, creating interdependence. To manage reservoirs in a basin, we follow the modeling principles:
+
+    * Sequential Processing: Order reservoirs by cascade level; each reservoir receives the combined outflow of upstream units as its inflow.
+    * Simulation: Each reservoir at level uses the aggregated inflow from all upstream nodes.
+    * Aggregation: Sum across reservoir columns to produce basin‐level time series for water release and hydropower, enabling performance metrics and system modeling.

docs/source/technical/time_series_models.rst

@@ -5,4 +5,50 @@
 **Time series modeling**
 =========================
 
-Loren ipsum
+**ARIMA Model**
+
+ARIMA (Autoregressive Integrated Moving Average) is a foundational time-series modeling technique that combines three components:
+
+    * Autoregression (:math:`AR(p)`): Models the value at time t as a linear function of its own p lagged values, capturing persistence and momentum in the series.
+    * Integration (:math:`I(d)`): Applies differencing of order d to remove trends and achieve stationarity, ensuring the series has constant mean and variance over time.
+    * Moving Average (:math:`MA(q)`): Represents the value at time t as a linear function of q past forecast errors, capturing short-term shocks and noise.
+
+**SARIMAX Model**
+
+SARIMAX (Seasonal Autoregressive Integrated Moving Average with eXogenous regressors) extends the classic ARIMA framework by explicitly modeling both seasonality and the influence of external variables on the series. In SARIMAX, the observed series :math:`y_t` is first differenced :math:`d` times to achieve stationarity, similar to ARIMA; the residual structure is then captured by:
+
+    * Seasonality: Additional differencing and seasonal AR/MA terms at lag :math:`s` (period) to model repeating patterns (e.g., daily, weekly), by seasonally differencing :math:`D` times with period :math:`s`
+    * Exogenous Regressors: Incorporates external variables (e.g., temperature, calendar indicators) linearly to explain known drivers of variability.
+
+**Monthly SARIMAX Model**
+
+We employ a per-month SARIMAX model for:
+
+    * Non‑Stationary Seasonality across the Year: Daily/weekly cycle shapes (peak sharpness, trough depth) change with season.
+    * Localized Parameter Tuning: Fitting separate SARIMAX for each calendar month allows tailored (p,d,q)(P,D,Q,s) orders per month.
+    * Improved Forecast Robustness: Month‑specific models reduce over‑ or under‑differencing risk and avoid a one‑size‑fits‑all seasonal period.
+
+**Demand Model**
+
+In short‑term load forecasting, SARIMAX is well suited because demand exhibits strong intra‑day/weekly cycles plus dependencies on weather and calendar effects. We equip the model with the ability to forecase the hourly electricity demand:
+
+    * **Step 1:** We first run an ordinary least squares (OLS) regression on user-supplied exogenous variables (such as temperature) and get the residual series. The OLS isolates the “explained” portion of demand and the residual is treated as a stationary series for further time‐series modeling.
+    * **Step 2:** We run a Seasonal-Trend decomposition using LOESS (STL) to decompose a time series into three components: trend, season(al) and residual. 
+    * **Step 3:** We fit a Seasonal Autoregressive Integrated Moving Average with Exogenous Regressors (SARIMAX) model to capture the correlation structure, and store per-month SARIMAX models and residuals.
+
+We run auto-ARIMA on the detrended, deseasonalized residuals to pick (p,d,q)(P,D,Q,s) orders that best capture autocorrelation left after regression + STL. We can then get synthetic time series by comnbining regression, drawing sample paths from each monthly SARIMAX, and adding seasonal and trend components.
+
+**Solar Model**
+
+Solar generation follows a deterministic diurnal "bell curve" and seasonal envelope, with high‑frequency fluctuations due to clouds and atmosphere, therefore we can also use SARIMAX to capture stochastic variability. Similarly, we would like to forecase solar irradiance/PV output. We follow a similar structure to the demand model, but:
+
+    * No pre-regression on exogenous weather, instead, the STL decomposition itself captures the deterministic daily/seasonal envelope and all remaining variation feeds directly into SARIMAX.
+    * Clip output to nonnegative and force it to zero during night hours.
+
+**Related Works**
+
+SARIMAX is a tried-and-tested way of modeling both demand and solar irradiance as demonstrated by the following works:
+
+    * N. Elamin, M. Fukushige. Modeling and forecasting hourly electricity demand by SARIMAX with interactions. *Energy*. Volume 165, Part B, 2018, Pages 257-268, ISSN 0360-5442.
+    * E. Eskandarnia and M. AlHammad, "Predication of future energy consumption using SARIMAX," *3rd Smart Cities Symposium (SCS 2020)*, 2020, pp. 657-662.
+    * S. Vagropoulos, G. Chouliaras, E. Kardakos, C. Simoglou and A. Bakirtzis, "Comparison of SARIMAX, SARIMA, modified SARIMA and ANN-based models for short-term PV generation forecasting," *2016 IEEE International Energy Conference (ENERGYCON)*, Leuven, Belgium, 2016, pp. 1-6.