update appraisal documentation

docs/model/investment.md

@@ -24,7 +24,7 @@ shadow prices for each commodity adjusted to remove the impact of binding capaci
 
 Note: there is an option to iterate over each year so that investment decisions are based on
 equilibrium prices in the _current year_, in what's referred to as the "[ironing-out loop]".
-In this case, \\( \lambda\_{c,r,t} \\) will reflect prices from previous iteration of the
+In this case, \\( \lambda\_{c,r,t} \\) will reflect prices from the previous iteration of the
 ironing-out loop.
 
 ## Candidate and existing asset data
@@ -69,33 +69,32 @@ providing investment and dynamic decommissioning decisions.
 
 ### Pre-calculation of metrics for each supply option
 
-> Note: This section contains a reference to "scopes", a feature that is not yet implemented
-
 - Annualised fixed costs per unit of capacity (\\( AFC_{opt,r} \\)): For new candidates, this is
   their annualised CAPEX plus FOM. For existing assets, the relevant fixed cost is its FOM.
 
-- Costs per unit of activity in each time slice, calculated as follows:
-
+- Calculate net revenue per unit of activity \\(AC_{t}^{NPV} \\) (Tool A):
   \\[
     \begin{aligned}
-          AC_t = & \quad cost\_{\text{var}}[t] \\\\
-            &+ \sum\_{c} \Big( cost\_{\text{input}}[c] \cdot input\_{\text{coeff}}[c]
-              + cost\_{\text{output}}[c] \cdot output\_{\text{coeff}}[c] \Big) \\\\
-            &+ \sum\_{c} \Big( input\_{\text{coeff}}[c] - output\_{\text{coeff}}[c] \Big)
+          AC_{t}^{NPV} = &-cost\_{\text{var}}[t] \\\\
+            &- \sum\_{c} \Big( cost\_{\text{input}}[c] \cdot input\_{\text{coeff}}[c] +
+            cost\_{\text{output}}[c] \cdot output\_{\text{coeff}}[c] \Big) \\\\
+            &+ \sum\_{c} \Big( output\_{\text{coeff}}[c] - input\_{\text{coeff}}[c] \Big)
               \cdot \lambda\_{c,r,t} \\\\
-            &+ \sum\_{s,c} in\\_scope[s] \cdot \Big\\{ \\\\
-            &\quad \quad (cost\_{\text{prod}}[s,c] - \mu\_{s,c}^{\text{prod}})
-              \cdot output\_{\text{coeff}}[c] \\\\
-            &\quad \quad + (cost\_{\text{cons}}[s,c] - \mu\_{s,c}^{\text{cons}})
-              \cdot input\_{\text{coeff}}[c] \\\\
-            &\quad \quad + (cost\_{\text{net}}[s,c] - \mu\_{s,c}^{\text{net}})
-              \cdot (output\_{\text{coeff}}[c] - input\_{\text{coeff}}[c]) \\\\
-            &\Big\\}
     \end{aligned}
   \\]
 
-  When using the LCOX objective, the calculation is adjusted to exclude the commodity of interest
-  (\\( \lambda\_{c,r,t} \\) are set to zero).
+- Calculate cost per unit of activity \\( AC_{t}^{LCOX} \\) (Tool B). Note that the commodity
+  of interest (primary output \\( c_{primary} \\)) is excluded from the price term:
+  \\[
+    \begin{aligned}
+          AC_{t}^{LCOX} = & \quad cost\_{\text{var}}[t] \\\\
+            &+ \sum\_{c} \Big( cost\_{\text{input}}[c] \cdot input\_{\text{coeff}}[c]+
+            cost\_{\text{output}}[c] \cdot output\_{\text{coeff}}[c] \Big) \\\\
+            &- \sum\_{c \neq c_{primary}} \Big( output\_{\text{coeff}}[c] - input\_{\text{coeff}}
+            [c] \Big)
+              \cdot \lambda\_{c,r,t} \\\\
+    \end{aligned}
+  \\]
 
 ### Initialise demand profiles for commodity of interest
 
@@ -130,8 +129,8 @@ providing investment and dynamic decommissioning decisions.
 
 #### Tool A: NPV
 
-This method is used when decision rule is single objective and objective is annualised profit for
-agents' serving commodity \\( c \\). This method iteratively builds a supply portfolio by selecting
+This method is used when the decision rule is `single` and the objective is annualised profit for
+agents serving commodity \\( c \\). It iteratively builds a supply portfolio by selecting
 options that offer the highest annualised profit for serving the current commodity demand. The
 economic evaluation uses \\( \pi_{prevMSY} \\) prices and takes account of asset-specific
 operational constraints (e.g., minimum load levels) and the balance level of the target commodity
@@ -140,10 +139,10 @@ operational constraints (e.g., minimum load levels) and the balance level of the
 - **Optimise capacity and dispatch to maximise annualised profit:** Solve a small optimisation
   sub-problem to maximise the asset's surplus, subject to its operational rules and the specific
   demand tranche it is being asked to serve. \\(\varepsilon \approx 1×10^{-14}\\) is added to each
-  \\(AC_t \\) to allow assets which are breakeven (or very close to breakeven) to be dispatched.
+  \\(AC_{t}^{NPV} \\) to allow assets which are breakeven (or very close to breakeven) to be dispatched.
 
   \\[
-    maximise \Big\\{ - \sum_t act_t \* (AC_t + \varepsilon)
+    maximise \Big\\{\sum_t act_t (AC_{t}^{NPV} + \varepsilon)
     \Big\\}
   \\]
 
@@ -158,9 +157,32 @@ operational constraints (e.g., minimum load levels) and the balance level of the
   - Capacity is constrained to \\( CapMaxBuild \\) for candidates, and to known capacity for
     existing assets.
 
-- **Calculate a profitability index:** This is the total annualised surplus (\\( - \sum_t
-  act_t \* AC \\)) divided by the annualised fixed cost (\\(
-  AFC \* cap \\)).
+- **Decide on metric:** The type of metric used to compare profitability is dependent on the value of
+\\(\text{AFC}\\). If \\(\text{AFC} = 0\\), this is always preferred over options with
+\\(\text{AFC} > 0\\) so the latter are discarded as investment options.
+
+- **If \\(\text{AFC} > 0\\), Use the profitability index \\(\text{PI}\\) metric:** This is the total
+ annualised surplus divided by the annualised fixed cost.
+  \\[
+  \text{PI} =
+  \frac{\sum_t \text{act}_t \cdot \text{AC}_t^{\text{NPV}}}{\text{AFC} \cdot \text{cap}}
+  \\]
+
+- **If \\(\text{AFC} = 0\\), Use the total annualised surplus metric \\(\text{TAS}\\):**
+    \\[
+  \text{TAS} =
+  \sum_t \text{act}_t \cdot \text{AC}_t^{\text{NPV}}
+  \\]
+
+- **Metric deadlock fallback** If two or more investment options have equal metrics, the following
+  tie-breaking rules are applied in order:
+
+  1. Assets which are already commissioned are preferred over new candidate assets.
+
+  2. Newer (commissioned later) assets are preferred over older assets.
+
+  3. If there is still a tie, the first option in the data structure is selected,
+   which is non-deterministic. A warning is emitted when this occurs.
 
 #### Tool B: LCOX
 
@@ -175,12 +197,12 @@ commodities are set to zero, and the commodity of interest is assumed to have ze
 For each asset option:
 
 - **Optimise capacity and dispatch to minimise annualised cost:** Solve a small optimisation
-  sub-problem to maximise the asset's surplus, subject to its operational rules and the specific
+  sub-problem to minimise the asset's annualised cost, subject to its operational rules and the specific
   demand tranche it is being asked to serve.
 
   \\[
     minimise \Big\\{
-      AF \* cap + \sum_t act_t \* AC_t + VoLL \* UnmetD_t
+      \text{AFC} \times cap + \sum_t act_t \times AC_{t}^{LCOX} + VoLL \times UnmetD_t
     \Big\\}
   \\]
 
@@ -199,9 +221,176 @@ For each asset option:
   - VoLL variables are active to ensure a feasible solution alongside maximum operation of the
     asset.
 
-- **Calculate a cost index:** This is the total annualised cost (\\(
-  AFC \* cap_r + \sum_{t} act_t \* AC_t \\)), divided by the annual output
-  \\( \sum_t act_t \\).
+- **Calculate a Cost Index:** This is the total annualised cost divided by the annual output.
+  \\[
+  \text{Cost Index} = \frac{\text{AFC} \times \text{cap}_r + \sum_t \text{act}_t
+   \times \text{AC}_t^{\text{LCOX}}}{\sum_t \text{act}_t}
+  \\]
+
+## Example: Gas Power Plant
+
+The following is an illustrative example of how the NPV and LCOX approaches work, using a simple
+gas combined-cycle power plant as the supply option under consideration.
+This example demonstrates the evaluation across two time periods
+\\(t_0\\) (peak period) and \\(t_1\\) (off-peak period) with variable operating costs
+ \\( cost\_{var}[t] \\) constant in all time periods.
+
+### Model Parameters
+
+#### Asset Parameters
+<!-- markdownlint-disable MD013 -->
+| Parameter | Notation | Value | Description |
+|-----------|----------|-------|-------------|
+| Primary output (Electricity) | \\( output\_{coeff}[c_{primary}] \\) | 1.0 MWh per unit activity | Main commodity produced |
+| By-product output (Waste heat) | \\( output\_{coeff}[c_{heat}] \\) | 0.5 MWh per unit activity | Co-product from generation |
+| Input (Natural gas) | \\( input\_{coeff}[c_{gas}] \\) | 2.5 MWh per unit activity | Fuel consumption |
+| Variable operating cost | \\( cost\_{var}[t] \\) | £5/MWh of activity | Operating costs per unit activity |
+<!-- markdownlint-enable MD013 -->
+
+#### Investment Parameters
+
+| Parameter | Notation | Value |
+|-----------|----------|-------|
+| Annualised fixed cost | \\( AFC\_{opt,r} \\) | £1,000/MW |
+| Capacity | \\( cap \\) | 100 MW |
+
+#### Market Prices by Time Period
+
+| Commodity | Notation | \\(t_0\\) (Peak) | \\(t_1\\) (Off-peak) |
+|-----------|----------|-----------|---------------|
+| Electricity | \\( \lambda\_{c_{primary},r,t} \\) | £90/MWh | £50/MWh |
+| Heat | \\( \lambda\_{c_{heat},r,t} \\) | £25/MWh | £15/MWh |
+| Natural gas | \\( \lambda\_{c_{gas},r,t} \\) | £35/MWh | £25/MWh |
+
+### NPV Approach (Tool A)
+
+#### Calculate Net Revenue per Unit of Activity
+
+**For \\(t_0\\) (peak period):**
+
+\\[
+\begin{aligned}
+AC_{t_{0}}^{NPV} &= (1.0 \times 90) + (0.5 \times 25) + (-2.5 \times 35) - 5 \\\\
+&= 90 + 12.5 - 87.5 - 5 \\\\
+&= \text{£10/MWh}
+\end{aligned}
+\\]
+
+The asset earns £10 profit for every MWh it operates during peak periods.
+
+**For \\(t_1\\) (off-peak period):**
+
+\\[
+\begin{aligned}
+AC_{t_1}^{NPV} &= (1.0 \times 50) + (0.5 \times 15) + (-2.5 \times 25) - 5 \\\\
+&= 50 + 7.5 - 62.5 - 5 \\\\
+&= \text{£} -10 \text{/MWh}
+\end{aligned}
+\\]
+
+The asset loses £10 for every MWh it operates during off-peak periods.
+
+#### Dispatch Optimisation
+
+The optimisation maximises total net revenue across all time periods:
+
+\\[
+\max \sum_t act_t \cdot AC_t^{NPV} = act_{t_{0}} \cdot 10 + act_{t_1} \cdot (-10)
+\\]
+
+where \\( act_t \\) is the activity (operational level) in each time slice, subject to operational
+ constraints and demand requirements.
+
+In this case, the optimiser will prefer to dispatch the asset during \\(t_0\\) (profitable) and
+ minimise operation during \\(t_1\\) (unprofitable), subject to technical constraints such as minimum
+load requirements.
+
+#### Profitability Index
+
+The profitability index is calculated as:
+
+\\[
+\text{PI} = \frac{\sum_t act_t \cdot AC_t^{NPV}}{AFC \times cap}
+\\]
+
+Suppose the dispatch optimiser determines \\( act_{t_{0}} = 80 \\) MWh and \\( act_{t_1} = 20 \\)
+MWh are the optimal activity levels:
+
+\\[
+\begin{aligned}
+\text{PI} &= \frac{(80 \times 10) + (20 \times (-10))}{1{,}000 \times 100} \\\\
+&= \frac{800 - 200}{100{,}000} \\\\
+&= \frac{600}{100{,}000} \\\\
+&= 0.006
+\end{aligned}
+\\]
+
+The profitability index is then compared against all other options to determine which asset provides
+ the best return on investment for serving the demand.
+
+### LCOX Approach (Tool B)
+
+#### Net Cost per Unit of Activity
+
+**For \\(t_0\\) (peak period):**
+
+\\[
+\begin{aligned}
+AC_{t_{0}}^{LCOX} &= 5 + (2.5 \times 35) - (0.5 \times 25) \\\\
+&= 5 + 87.5 - 12.5 \\\\
+&= \text{£80/MWh}
+\end{aligned}
+\\]
+
+It costs £80 per MWh to operate during peak periods (net of heat by-product sales).
+
+**For \\(t_1\\) (off-peak period):**
+
+\\[
+\begin{aligned}
+AC_{t_1}^{LCOX} &= 5 + (2.5 \times 25) - (0.5 \times 15) \\\\
+&= 5 + 62.5 - 7.5 \\\\
+&= \text{£60/MWh}
+\end{aligned}
+\\]
+
+It costs £60 per MWh to operate during off-peak periods, reflecting lower gas prices
+ and lower heat by-product value.
+
+#### Capacity and Dispatch Optimisation
+
+The optimiser determines the most cost-effective capacity and dispatch pattern to meet demand across
+ both time periods by minimising the total annualised cost with respect to decision variables
+ \\( cap \\) and \\( act_t \\):
+
+\\[
+AFC \cdot cap + \sum_t act_t \cdot AC_t^{LCOX} = 1{,}000 \cdot cap + act_{t_{0}}
+ \cdot 80 + act_{t_1} \cdot 60
+\\]
+
+#### Cost Index (Levelised Cost of X)
+
+The Cost Index is calculated as:
+
+\\[
+\text{Cost Index} = \frac{AFC \cdot cap + \sum_t act_t \cdot AC_t^{LCOX}}{\sum_t act_t}
+\\]
+
+Suppose the optimiser determines \\( cap = 100 \\) MW, \\( act_{t_{0}} = 150 \\) MWh,
+ and \\( act_{t_1} = 80 \\) MWh are the optimal capacity and activity levels:
+
+\\[
+\begin{aligned}
+\text{Cost Index} &= \frac{(1{,}000 \times 100) + (150 \times 80) + (80 \times 60)}{150 + 80} \\\\
+&= \frac{100{,}000 + 12{,}000 + 4{,}800}{230} \\\\
+&= \frac{116{,}800}{230} \\\\
+&= \text{£508/MWh}
+\end{aligned}
+\\]
+
+The Cost Index is £508 per MWh of electricity produced.
+ This metric is compared across all supply options to identify
+ the lowest-cost solution for meeting demand.
 
 [overall MUSE2 workflow]: ./README.md#framework-overview
 [Dispatch Optimisation Formulation]: ./dispatch_optimisation.md