From 4fda4355e6e8c8b84917c7d188df36fd7e258614 Mon Sep 17 00:00:00 2001 From: Tom Bland Date: Tue, 17 Nov 2026 10:33:42 +0000 Subject: [PATCH 1/5] Add placeholder for population agents --- docs/model/agents.md | 4 ++-- schemas/input/agents.yaml | 2 +- src/agent.rs | 2 ++ src/input/agent.rs | 4 ++++ src/simulation/investment.rs | 1 + src/simulation/investment/population.rs | 32 +++++++++++++++++++++++++ src/simulation/market.rs | 3 ++- 7 files changed, 44 insertions(+), 4 deletions(-) create mode 100644 src/simulation/investment/population.rs diff --git a/docs/model/agents.md b/docs/model/agents.md index c1999f8a0..b34fb275a 100644 --- a/docs/model/agents.md +++ b/docs/model/agents.md @@ -26,8 +26,8 @@ selected by the agent: the existing assets to retain and the new candidate asset of the investment process (the investment order, handling of circularities, partial system dispatch, mothballing, etc.) is the same for all agent types. -There are two agent types, set with the `agent_type` column of [`agents.csv`][agents-csv]: -competitive agents (`competitive`) and portfolio agents (`portfolio`) +The `agent_type` column of [`agents.csv`][agents-csv] selects competitive agents (`competitive`), +portfolio agents (`portfolio`), or population agents (`population`). ## Competitive agents diff --git a/schemas/input/agents.yaml b/schemas/input/agents.yaml index 34afb2437..dea81eff6 100644 --- a/schemas/input/agents.yaml +++ b/schemas/input/agents.yaml @@ -13,7 +13,7 @@ fields: notes: One or more region IDs, separated by semicolons or the string `all` - name: agent_type type: string - enum: [competitive, portfolio] + enum: [competitive, portfolio, population] description: The asset selection algorithm used by the agent notes: | Optional (defaults to `portfolio` if omitted). With `portfolio`, the capacities of all diff --git a/src/agent.rs b/src/agent.rs index 67efae343..d06d5b645 100644 --- a/src/agent.rs +++ b/src/agent.rs @@ -77,6 +77,8 @@ pub enum AgentType { /// Existing and candidate assets compete in rounds, with the best option according to the /// agent's objective selected in each round Competitive, + /// Placeholder for a population agent; not yet implemented + Population, } /// The decision rule for a particular objective diff --git a/src/input/agent.rs b/src/input/agent.rs index b6ac929ec..ece5fcdb5 100644 --- a/src/input/agent.rs +++ b/src/input/agent.rs @@ -251,6 +251,10 @@ mod tests { "id,description,regions,decision_rule,agent_type\nagent,,GBR,single,portfolio\n", Some(AgentType::Portfolio) )] + #[case( + "id,description,regions,decision_rule,agent_type\nagent,,GBR,single,population\n", + Some(AgentType::Population) + )] fn read_agents_file_agent_type(#[case] csv: &str, #[case] expected: Option) { let dir = tempdir().unwrap(); fs::write(dir.path().join(AGENT_FILE_NAME), csv).unwrap(); diff --git a/src/simulation/investment.rs b/src/simulation/investment.rs index c03716cad..e467fe071 100644 --- a/src/simulation/investment.rs +++ b/src/simulation/investment.rs @@ -21,6 +21,7 @@ use std::sync::Arc; use strum::IntoEnumIterator; pub mod competitive; +pub mod population; pub mod portfolio; /// A map of demand across time-slice selections for a specific market diff --git a/src/simulation/investment/population.rs b/src/simulation/investment/population.rs new file mode 100644 index 000000000..a865e8a1d --- /dev/null +++ b/src/simulation/investment/population.rs @@ -0,0 +1,32 @@ +//! Placeholder for the population agent algorithm. +use crate::agent::Agent; +use crate::commodity::Commodity; +use crate::model::Model; +use crate::output::DebugDataWriter; +use crate::process::ProcessID; +use crate::region::RegionID; +use crate::simulation::investment::{AssetOptions, DemandMap, Selection}; +use crate::simulation::prices::Prices; +use crate::units::Capacity; +use anyhow::{Result, bail}; +use std::collections::HashMap; + +/// Run a population agent. +/// +/// Population agents are not yet implemented, so this always returns an error. +#[allow(clippy::too_many_arguments, clippy::needless_pass_by_value)] +pub fn run_agent( + _model: &Model, + agent: &Agent, + _commodity: &Commodity, + _region_id: &RegionID, + _demand: &DemandMap, + _options: &AssetOptions, + _agent_addition_limits: HashMap, + _agent_total_limits: HashMap, + _prices: &Prices, + _year: u32, + _debug_writer: Option<&mut DebugDataWriter>, +) -> Result { + bail!("Population agent '{}' is not yet implemented", agent.id) +} diff --git a/src/simulation/market.rs b/src/simulation/market.rs index b5ab254e7..98f7476db 100644 --- a/src/simulation/market.rs +++ b/src/simulation/market.rs @@ -11,7 +11,7 @@ use crate::region::RegionID; use crate::simulation::investment::{ AgentRunMode, AllDemandMap, AssetOptions, DemandMap, FlowEstimator, update_net_demand_map, }; -use crate::simulation::investment::{competitive, portfolio}; +use crate::simulation::investment::{competitive, population, portfolio}; use crate::simulation::prices::Prices; use crate::time_slice::TimeSliceInfo; use crate::units::{Capacity, Dimensionless, Flow}; @@ -263,6 +263,7 @@ pub fn run_agents_for_single_market( // Choose assets from among existing pool and candidates let run_agent = match agent.agent_type { AgentType::Competitive => competitive::run_agent, + AgentType::Population => population::run_agent, AgentType::Portfolio => portfolio::run_agent, }; let selection = run_agent( From 9fd75e30fd6753e81c9b17758625b580c3c57388 Mon Sep 17 00:00:00 2001 From: Tom Bland Date: Tue, 17 Nov 2026 11:45:58 +0000 Subject: [PATCH 2/5] PLACEHOLDER: old competitive algorithm --- src/simulation/investment/population.rs | 717 ++++++++++++++- .../investment/population/coefficients.rs | 109 +++ .../investment/population/constraints.rs | 174 ++++ src/simulation/investment/population/costs.rs | 33 + .../investment/population/metrics.rs | 854 ++++++++++++++++++ .../investment/population/optimisation.rs | 174 ++++ .../investment/population/output.rs | 202 +++++ 7 files changed, 2242 insertions(+), 21 deletions(-) create mode 100644 src/simulation/investment/population/coefficients.rs create mode 100644 src/simulation/investment/population/constraints.rs create mode 100644 src/simulation/investment/population/costs.rs create mode 100644 src/simulation/investment/population/metrics.rs create mode 100644 src/simulation/investment/population/optimisation.rs create mode 100644 src/simulation/investment/population/output.rs diff --git a/src/simulation/investment/population.rs b/src/simulation/investment/population.rs index a865e8a1d..30f06dac9 100644 --- a/src/simulation/investment/population.rs +++ b/src/simulation/investment/population.rs @@ -1,32 +1,707 @@ -//! Placeholder for the population agent algorithm. -use crate::agent::Agent; -use crate::commodity::Commodity; +//! The competitive agent algorithm. +//! +//! Candidate and existing assets compete in rounds: each round every option is appraised with a +//! mini dispatch optimisation, and the best option according to the agent's objective is selected. +mod coefficients; +mod constraints; +mod costs; +mod metrics; +mod optimisation; +mod output; + +use crate::agent::{Agent, AgentID}; +use crate::asset::{Asset, AssetCapacity, AssetRef}; +use crate::commodity::{Commodity, CommodityID}; use crate::model::Model; use crate::output::DebugDataWriter; -use crate::process::ProcessID; +use crate::process::{Process, ProcessID}; use crate::region::RegionID; -use crate::simulation::investment::{AssetOptions, DemandMap, Selection}; +use crate::simulation::activity::ActivityMap; +use crate::simulation::investment::Selection; +use crate::simulation::investment::{AssetOptions, DemandMap}; use crate::simulation::prices::Prices; -use crate::units::Capacity; -use anyhow::{Result, bail}; +use crate::time_slice::TimeSliceSelection; +use crate::units::{Activity, Capacity, Dimensionless, Flow, FlowPerCapacity}; +use anyhow::{Result, anyhow, ensure}; +use coefficients::calculate_coefficients_for_assets; +use itertools::{Itertools, chain}; +use log::debug; +use metrics::{ + AppraisalOutput, appraise_investment, count_equal_and_best_appraisal_outputs, + sort_and_filter_appraisal_outputs, +}; +use optimisation::solve_for_assets; +use output::write_debug_info; +use rayon::prelude::*; use std::collections::HashMap; +use std::sync::Arc; -/// Run a population agent. +/// Run the competitive algorithm for an agent to meet its share of demand for a commodity in a +/// region. +/// +/// Committed assets are dispatched first and always selected unchanged. Existing assets of the +/// agent which produce the commodity compete with candidate assets from the agent's search space to +/// meet any remaining demand. +/// +/// # Arguments /// -/// Population agents are not yet implemented, so this always returns an error. -#[allow(clippy::too_many_arguments, clippy::needless_pass_by_value)] +/// * `model` - The model +/// * `agent` - The agent selecting assets +/// * `commodity` - The commodity for which demand must be met +/// * `region_id` - The region +/// * `demand` - The agent's share of demand for the commodity in the region +/// * `options` - Committed assets, existing assets and processes available to the agent +/// * `agent_addition_limits` - The agent's share of addition limits for candidate processes +/// * `agent_total_limits` - The agent's share of total capacity limits for processes +/// * `prices` - Commodity prices calculated in the previous dispatch +/// * `year` - Current milestone year +/// * `debug_writer` - Optional debug writer +/// +/// # Returns +/// +/// The assets selected (including committed assets and retained commissioned assets) along with +/// their activities from the final appraisal round, or an error. An error is also returned if +/// demand cannot be met. +#[allow(clippy::too_many_arguments)] pub fn run_agent( - _model: &Model, + model: &Model, + agent: &Agent, + commodity: &Commodity, + region_id: &RegionID, + demand: &DemandMap, + options: &AssetOptions, + agent_addition_limits: HashMap, + agent_total_limits: HashMap, + prices: &Prices, + year: u32, + debug_writer: Option<&mut DebugDataWriter>, +) -> Result { + // Existing and candidate assets from which to choose + let opt_assets = chain( + options.existing.iter().cloned(), + get_candidate_assets( + demand, + &options.processes, + region_id, + commodity, + year, + model.parameters.capacity_tranche_fraction, + ), + ) + .collect::>(); + + select_best_assets( + model, + &options.committed, + opt_assets, + agent_addition_limits, + agent_total_limits, + commodity, + agent, + region_id, + prices, + demand.clone(), + year, + debug_writer, + ) +} + +/// Get candidate assets which produce a particular commodity from the given processes. +/// +/// Each candidate represents one investment tranche with a defined capacity. +/// - For processes with a defined `tranche_size`, the capacity is set to `tranche_size`. +/// - For processes without a defined `tranche_size`, the capacity is calculated based on the total +/// demand for the commodity and the asset's maximum annual production per unit capacity +/// (see `calculate_candidate_asset_capacity_scale`), then multiplied by +/// `capacity_tranche_fraction` to infer the tranche size. +pub fn get_candidate_assets<'a>( + demand: &'a DemandMap, + processes: &'a [Arc], + region_id: &'a RegionID, + commodity: &'a Commodity, + year: u32, + capacity_tranche_fraction: Dimensionless, +) -> impl Iterator + 'a { + processes.iter().map(move |process| { + // Create asset with zero capacity, which will be updated below + let mut asset = + Asset::new_candidate(process.clone(), region_id.clone(), Capacity(0.0), year).unwrap(); + + // Set capacity of the candidate for investment appraisal + let tranche_size = if let Some(tranche_size) = asset.process().tranche_size { + // For processes with a defined tranche size, take this + tranche_size + } else { + // Otherwise, infer the tranche size from demand and the capacity_tranche_fraction. + let capacity_scale = + calculate_candidate_asset_capacity_scale(&asset, commodity, demand); + capacity_scale * capacity_tranche_fraction + }; + let asset_capacity = AssetCapacity::single(tranche_size); + asset.set_capacity(asset_capacity); + asset.into() + }) +} + +/// Calculates a characteristic capacity scale for a candidate asset. +/// +/// The returned value is the capacity that would satisfy the total annual demand assuming the asset +/// operates at its maximum annual activity for the entire year. It ignores finer-grained activity +/// constraints and temporal variations in demand. +/// +/// For processes that do not define a tranche size, this value is later scaled by +/// `capacity_tranche_fraction` to set the capacity of one candidate investment tranche. +/// +/// If the asset has zero maximum annual supply, zero capacity is returned. This indicates that the +/// asset is non-feasible, and will be excluded from consideration by `select_best_assets`. +fn calculate_candidate_asset_capacity_scale( + asset: &Asset, + commodity: &Commodity, + demand: &DemandMap, +) -> Capacity { + let coeff = asset.get_flow(&commodity.id).unwrap().coeff; + let max_annual_supply_per_capacity = *asset + .get_activity_per_capacity_limits_for_selection(&TimeSliceSelection::Annual) + .end() + * coeff; + if max_annual_supply_per_capacity < FlowPerCapacity::EPSILON { + return Capacity(0.0); + } + let annual_demand = demand.values().copied().sum::(); + annual_demand / max_annual_supply_per_capacity +} + +/// Print debug message if there are multiple equally good outputs +fn log_on_equal_appraisal_outputs( + outputs: &[AppraisalOutput], + agent_id: &AgentID, + commodity_id: &CommodityID, + region_id: &RegionID, +) { + if outputs.is_empty() { + return; + } + + let num_identical = count_equal_and_best_appraisal_outputs(outputs); + + if num_identical > 0 { + let asset_details = outputs[..=num_identical] + .iter() + .map(|output| { + let asset = &output.asset; + format!( + "Process ID: '{}' (State: {}{}, Commission year: {})", + asset.process_id(), + asset.state(), + asset.id().map_or_default(|id| format!(", Asset ID: {id}")), + asset.commission_year() + ) + }) + .join(", "); + debug!( + "Found equally good appraisals for Agent ID: {agent_id}, Commodity: '{commodity_id}', \ + Region: {region_id}. Options: [{asset_details}]. Selecting first option.", + ); + } +} + +/// Get the best assets for meeting demand for the given commodity +/// +/// `committed_assets` have fixed capacity and are always selected, unchanged. They are dispatched +/// before any of `opt_assets` are appraised. +#[allow(clippy::too_many_arguments, clippy::too_many_lines)] +pub fn select_best_assets( + model: &Model, + committed_assets: &[AssetRef], + mut opt_assets: Vec, + agent_addition_limits: HashMap, + agent_total_limits: HashMap, + commodity: &Commodity, agent: &Agent, - _commodity: &Commodity, - _region_id: &RegionID, - _demand: &DemandMap, - _options: &AssetOptions, - _agent_addition_limits: HashMap, - _agent_total_limits: HashMap, - _prices: &Prices, - _year: u32, - _debug_writer: Option<&mut DebugDataWriter>, + region_id: &RegionID, + prices: &Prices, + mut demand: DemandMap, + year: u32, + mut debug_writer: Option<&mut DebugDataWriter>, ) -> Result { - bail!("Population agent '{}' is not yet implemented", agent.id) + let objective_type = agent.objectives[&year]; + + // Remaining addition limits for candidate processes + // Initialised as the full agent addition limits, and reduced as candidate assets are selected + let mut remaining_agent_addition_limits = agent_addition_limits; + + // Remaining total capacity for all assets + // Initialised as full agent total limits, and reduced as each asset is selection + let mut remaining_agent_total_limits = agent_total_limits; + + // Store commissioned tranches available for retention and replace assets with single tranches + let mut available_retention_tranches = + prepare_commissioned_assets_for_retention(&mut opt_assets); + + // Calculate coefficients for all asset options according to the agent's objective + let coefficients = calculate_coefficients_for_assets( + model, + objective_type, + &chain(committed_assets, &opt_assets).cloned().collect_vec(), + &prices.market, + &prices.fallback, + year, + ); + + // Iteratively select the best asset until demand is met + let mut round = 0; + let mut selected_assets: Vec = committed_assets.to_vec(); + let mut previous_solution = ActivityMap::new(); + + // Dispatch the committed assets. This must happen even if there is no demand, so that every + // selected asset has activities. + if !committed_assets.is_empty() { + (previous_solution, demand) = + solve_for_assets(model, &selected_assets, commodity, &coefficients, &demand)?; + } + + let has_options = !opt_assets.is_empty(); + while is_any_remaining_demand( + &demand, + model.parameters.remaining_demand_absolute_tolerance, + ) { + // Remove assets that would exceed the remaining limits for their processes from the options + // The addition limit applies only to candidate assets, the total limit applies to all assets + remove_assets_exceeding_agent_limits( + &mut opt_assets, + &remaining_agent_addition_limits, + true, + ); + remove_assets_exceeding_agent_limits(&mut opt_assets, &remaining_agent_total_limits, false); + if opt_assets.is_empty() { + return Err(no_options_error( + has_options, + agent, + commodity, + region_id, + year, + )); + } + // Appraise all options in parallel: each asset's appraisal is independent (all shared + // state is read-only within this block), so we can safely use Rayon here. + // Each HiGHS solve inside `appraise_investment` is configured to use only one thread + // (via `parallel="off"`) to avoid over-subscription. + let mut outputs: Vec = opt_assets + .par_iter() + .map(|asset| -> Result> { + // Skip assets with zero capacity + if asset.total_capacity() <= Capacity(0.0) { + return Ok(None); + } + + Ok(Some(appraise_investment( + model, + asset, + commodity, + objective_type, + &coefficients[asset], + &demand, + )?)) + }) + .collect::>>()? // propagate any solver error + .into_iter() + .flatten() + .collect(); + + // Save appraisal results + if let Some(writer) = debug_writer.as_deref_mut() { + write_debug_info( + writer, + year, + &format!("{} {} round {}", commodity.id, agent.id, round), + &outputs, + &demand, + commodity.time_slice_level, + )?; + } + + // Sort by investment priority and discard non-feasible options + let num_nonfeasible = sort_and_filter_appraisal_outputs(&mut outputs); + + ensure!( + !outputs.is_empty(), + "Investment appraisal failed with unmet demand for commodity '{}', region \ + '{region_id}', year {year}, agent '{}'. {num_nonfeasible} non-feasible investments \ + were not considered.", + commodity.id, + agent.id + ); + + // Warn if there are multiple equally good assets + log_on_equal_appraisal_outputs(&outputs, &agent.id, &commodity.id, region_id); + + let best_output = outputs.into_iter().next().unwrap(); + + // Log the selected asset + debug!( + "Selected {} asset '{}' (capacity: {})", + best_output.asset.state(), + best_output.asset.process_id(), + best_output.asset.total_capacity() + ); + + // Update the remaining selection state + update_selection_state( + &best_output.asset, + &mut opt_assets, + &mut remaining_agent_addition_limits, + &mut remaining_agent_total_limits, + &mut available_retention_tranches, + ); + + for (time_slice, activity) in &best_output.activity { + *previous_solution + .entry((best_output.asset.clone(), time_slice.clone())) + .or_insert(Activity(0.0)) += *activity; + } + + // Record the selected asset + record_asset_selection(best_output.asset.clone(), &mut selected_assets); + + demand = best_output.unmet_demand; + round += 1; + } + + Ok(finalise_selection( + selected_assets, + agent, + &previous_solution, + )) +} + +/// Convert the selected assets to the final selection +/// +/// Candidate assets are converted to Ready, and at this point we also assign the agent ID to the +/// asset. The solution contains the activities recorded for committed and selected assets. +fn finalise_selection( + selected_assets: Vec, + agent: &Agent, + solution: &ActivityMap, +) -> Selection { + let selected = selected_assets + .into_iter() + .map(|asset| { + let mut selected_asset = asset.clone(); + if selected_asset.is_candidate() { + selected_asset + .make_mut() + .select_candidate_for_investment(agent.id.clone()); + } + (asset, selected_asset) + }) + .collect(); + + Selection::from_optimisation(selected, solution) +} + +/// Create the error for when demand remains but there are no asset options left to appraise +fn no_options_error( + has_options: bool, + agent: &Agent, + commodity: &Commodity, + region_id: &RegionID, + year: u32, +) -> anyhow::Error { + if has_options { + anyhow!( + "Failed to meet demand for commodity '{}' in region '{region_id}' with provided \ + investment options. This may be due to overly restrictive process investment \ + constraints.", + commodity.id + ) + } else { + anyhow!( + "Agent '{}' cannot meet its demand for commodity '{}' in region '{region_id}' in \ + year {year} with its existing assets", + agent.id, + commodity.id + ) + } +} + +/// Prepare existing assets for reappraisal. +/// +/// Assets are replaced in `assets` with an asset representing a single tranche, as they are +/// appraised one tranche at a time. Returns a map from the asset to its original number of tranches. +fn prepare_commissioned_assets_for_retention(assets: &mut [AssetRef]) -> HashMap { + let mut available_retention_tranches = HashMap::new(); + + for asset in assets.iter_mut().filter(|asset| asset.is_commissioned()) { + let num_tranches = asset.num_tranches(); + + // Replace with single tranche as we appraise one tranche at a time + *asset = asset.clone().as_single_tranche(); + + // Store remaining tranches + available_retention_tranches.insert(asset.clone(), num_tranches); + } + + available_retention_tranches +} + +/// Check whether there is any remaining demand that is unmet in any time slice +fn is_any_remaining_demand(demand: &DemandMap, absolute_tolerance: Flow) -> bool { + demand.values().any(|flow| *flow > absolute_tolerance) +} + +/// Remove assets that exceed the provided process limits for one complete tranche. +fn remove_assets_exceeding_agent_limits( + opt_assets: &mut Vec, + remaining_agent_limits: &HashMap, + only_candidates: bool, +) { + opt_assets.retain(|asset| { + (only_candidates && !asset.is_candidate()) + || remaining_agent_limits + .get(asset.process_id()) + .is_none_or(|limit| *limit >= asset.total_capacity()) + }); +} + +// Update remaining process capacity limit with the capacity of a selected asset +fn subtract_capacity_from_remaining_limit( + best_asset: &AssetRef, + remaining_agent_limits: &mut HashMap, +) { + if let Some(remaining_capacity) = remaining_agent_limits.get_mut(best_asset.process_id()) { + *remaining_capacity -= best_asset.total_capacity(); + assert!( + *remaining_capacity >= Capacity(0.0), + "Remaining Capacity has fallen below zero" + ); + } +} + +/// Update the remaining investment options and selection state. +/// +/// If the asset is a candidate, its one-tranche capacity is subtracted from +/// `remaining_agent_addition_limits` (if applicable) to ensure that process addition limits are not +/// exceeded. If the asset is commissioned, one tranche is subtracted from +/// `available_retention_tranches` to ensure that retention does not invent new capacity. +/// +/// # Arguments +/// +/// * `best_asset` - The asset that has been selected as the best option in this round +/// * `opt_assets` - The list of remaining asset options to be considered in future rounds +/// * `remaining_agent_addition_limits` - The remaining agent addition limits for processes +/// * `remaining_agent_total_limit` - The remaining capacity for processes +/// * `available_retention_tranches` - The commissioned tranches available for retention +fn update_selection_state( + best_asset: &AssetRef, + opt_assets: &mut Vec, + remaining_agent_addition_limits: &mut HashMap, + remaining_agent_total_limits: &mut HashMap, + available_retention_tranches: &mut HashMap, +) { + // Subtract asset capacity from the total capacity limit, if applicable. + subtract_capacity_from_remaining_limit(best_asset, remaining_agent_total_limits); + + // Update the remaining agent addition limit for the selected asset, if applicable, and remove it + // from the options if the limit is exhausted. + if best_asset.is_candidate() { + // Candidate assets: remove capacity from the investment limit, if applicable. + subtract_capacity_from_remaining_limit(best_asset, remaining_agent_addition_limits); + } else { + // Commissioned assets: we've appraised a single tranche, so remove one tranche from the + // available retention count for this asset. + let remaining = available_retention_tranches.get_mut(best_asset).unwrap(); + *remaining = remaining.saturating_sub(1); + + // If all tranches have been selected, remove the asset from the investment options. + if *remaining == 0 { + let old_idx = opt_assets + .iter() + .position(|asset| *asset == *best_asset) + .unwrap(); + opt_assets.swap_remove(old_idx); + available_retention_tranches.remove(best_asset); + } + } +} + +/// Record a selected asset. Candidate selections represent one tranche; repeated selections of the +/// same candidate increase the resulting asset's number of tranches while preserving its tranche +/// size. +/// +/// # Arguments +/// +/// * `best_asset` - The asset that has been selected as the best option in this round +/// * `best_assets` - The list of assets that have been selected so far +fn record_asset_selection(best_asset: AssetRef, best_assets: &mut Vec) { + assert!( + best_asset.is_commissioned() || best_asset.is_candidate(), + "Invalid asset type" + ); + + // Add the selected asset to the list of best assets, or add one tranche if it's already there. + if let Some(existing_asset) = best_assets.iter_mut().find(|asset| **asset == best_asset) { + // If the asset is already selected, add the additional required tranche + existing_asset + .make_mut() + .increase_capacity(best_asset.capacity()); + } else { + // Otherwise add it to the list of best assets. Selected assets are unmothballed. + best_assets.push(best_asset.with_no_mothballed_capacity()); + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::fixture::{ + agent_id, asset, process, process_activity_limits_map, process_flows_map, svd_commodity, + time_slice, time_slice_info, + }; + use crate::process::{ActivityLimits, FlowType, Process, ProcessFlow}; + use crate::time_slice::{TimeSliceID, TimeSliceInfo}; + use crate::units::{FlowPerActivity, MoneyPerFlow}; + use indexmap::indexmap; + use rstest::{fixture, rstest}; + use std::sync::Arc; + + #[rstest] + #[case(Flow(10.0), Dimensionless(1.0), Capacity(10.0))] // normal: demand / (limit * coeff) = 10 / (1 * 1) = 10 + #[case(Flow(0.0), Dimensionless(1.0), Capacity(0.0))] // zero demand → zero capacity + #[case(Flow(10.0), Dimensionless(0.5), Capacity(20.0))] // activity limit < 1: 10 / (0.5 * 1) = 20 + #[case(Flow(10.0), Dimensionless(0.0), Capacity(0.0))] // activity limit = 0 → zero capacity + fn calculate_asset_capacity_scale_works( + time_slice: TimeSliceID, + time_slice_info: TimeSliceInfo, + svd_commodity: Commodity, + mut process: Process, + #[case] demand_value: Flow, + #[case] activity_limit: Dimensionless, + #[case] expected: Capacity, + ) { + let commodity_rc = Arc::new(svd_commodity); + let process_flow = ProcessFlow { + commodity: Arc::clone(&commodity_rc), + coeff: FlowPerActivity(1.0), + kind: FlowType::Fixed, + cost: MoneyPerFlow(0.0), + }; + process.flows = process_flows_map( + process.regions.clone(), + Arc::new(indexmap! { commodity_rc.id.clone() => process_flow }), + ); + + let mut limits = ActivityLimits::new_with_full_availability(&time_slice_info); + limits.add_time_slice_limit(time_slice.clone(), Dimensionless(0.0)..=activity_limit); + process.activity_limits = process_activity_limits_map(process.regions.clone(), limits); + + let asset = asset(process); + let demand = indexmap! { TimeSliceSelection::Single(time_slice)=> demand_value }; + assert_eq!( + calculate_candidate_asset_capacity_scale(&asset, &commodity_rc, &demand), + expected + ); + } + + #[rstest] + fn subtract_capacity_from_remaining_limit_works(asset: Asset) { + let mut remaining_agent_limits = + HashMap::from([(asset.process_id().clone(), Capacity(10.0))]); + subtract_capacity_from_remaining_limit( + &AssetRef::from(asset.clone()), + &mut remaining_agent_limits, + ); + + assert_eq!( + remaining_agent_limits[asset.process_id()].clone(), + Capacity(8.0) + ); + } + + #[fixture] + fn commissioned_asset(agent_id: AgentID, asset: Asset) -> Asset { + Asset::new_commissioned( + agent_id, + Arc::new(asset.process().clone()), + asset.region_id().clone(), + asset.capacity(), + asset.commission_year(), + ) + .unwrap() + } + + #[fixture] + fn candidate_asset(asset: Asset) -> Asset { + Asset::new_candidate( + Arc::new(asset.process().clone()), + asset.region_id().clone(), + asset.total_capacity(), + asset.commission_year(), + ) + .unwrap() + } + + #[rstest] + fn remove_assets_exceeding_agent_limits_works( + commissioned_asset: Asset, + candidate_asset: Asset, + ) { + let mut opt_assets = vec![ + commissioned_asset.clone().into(), + candidate_asset.clone().into(), + ]; + let limits = HashMap::from([(commissioned_asset.process_id().clone(), Capacity(1.0))]); + + // Check only the candidate asset is removed when `only_candidates` is true + remove_assets_exceeding_agent_limits(&mut opt_assets, &limits, true); + assert_eq!(opt_assets.len(), 1); + assert_eq!(opt_assets[0], commissioned_asset.clone().into()); + + // Check all assets are removed when `only_candidates` is false + opt_assets.push(candidate_asset.clone().into()); + remove_assets_exceeding_agent_limits(&mut opt_assets, &limits, false); + assert_eq!(opt_assets, []); + } + + #[rstest] + #[case(false)] + #[case(true)] + fn update_selection_state_works( + commissioned_asset: Asset, + candidate_asset: Asset, + #[case] commissioned: bool, + ) { + let best_asset: AssetRef = if commissioned { + commissioned_asset.clone().into() + } else { + candidate_asset.clone().into() + }; + let mut opt_assets = vec![best_asset.clone()]; + let mut addition_limits = HashMap::from([(best_asset.process_id().clone(), Capacity(2.0))]); + let mut total_limits = HashMap::from([(best_asset.process_id().clone(), Capacity(2.0))]); + let mut retention_tranches = HashMap::from([(best_asset.clone(), 1)]); + + update_selection_state( + &best_asset, + &mut opt_assets, + &mut addition_limits, + &mut total_limits, + &mut retention_tranches, + ); + + if commissioned { + // Expect total_limits to reduce and retention_tranches to be removed + assert_eq!(total_limits[best_asset.process_id()], Capacity(0.0)); + assert!(!retention_tranches.contains_key(&best_asset)); + + // Expect addition_limits to remain unchanged + assert_eq!(addition_limits[best_asset.process_id()], Capacity(2.0)); + } else { + // Expect total_limits and addition_limits to reduce + assert_eq!(total_limits[best_asset.process_id()], Capacity(0.0)); + assert_eq!(addition_limits[best_asset.process_id()], Capacity(0.0)); + + // Expect retention_tranches to remain unchanged + assert_eq!(retention_tranches[&best_asset], 1); + } + } } diff --git a/src/simulation/investment/population/coefficients.rs b/src/simulation/investment/population/coefficients.rs new file mode 100644 index 000000000..b9a0ad8bd --- /dev/null +++ b/src/simulation/investment/population/coefficients.rs @@ -0,0 +1,109 @@ +//! Calculation of cost coefficients for investment tools. +use crate::agent::ObjectiveType; +use crate::asset::AssetRef; +use crate::model::Model; +use crate::simulation::PriceMap; +use crate::time_slice::{TimeSliceID, TimeSliceInfo}; +use crate::units::{MoneyPerActivity, MoneyPerFlow}; +use indexmap::IndexMap; +use std::collections::HashMap; +use std::sync::Arc; + +/// Per-time-slice cost coefficients for an asset. +/// +/// These coefficients are calculated according to the agent's `ObjectiveType` and are used by the +/// investment appraisal routines. Both the activity coefficients used in the appraisal optimisation +/// and the costs used to calculate the appraisal metric are derived from market prices. +#[derive(Clone)] +pub struct ObjectiveCoefficients { + /// Net revenue per unit of activity, including fallback revenue and epsilon, in each time slice + pub activity_coefficients: IndexMap, + /// Costs per unit of activity for the appraisal metric, excluding fallback revenue and epsilon + pub metric_costs: IndexMap, +} + +/// Calculates cost coefficients for a set of assets for a given objective type. +/// +/// Returns a map from each asset to its [`ObjectiveCoefficients`], which holds a per-time-slice +/// activity coefficient and metric cost. +/// +/// Activity coefficients are revenue from flows (including the primary output) minus operating +/// cost, calculated using market prices, plus the primary output's fallback revenue. A small positive +/// epsilon is added to each activity coefficient so that assets with near-zero net value still appear +/// in dispatch. +/// +/// Metric costs are operating cost minus flow revenue at market prices. NPV includes all flows, +/// whereas LCOX excludes revenue from the primary output (commodity of interest). Neither includes +/// fallback revenue or epsilon. +pub fn calculate_coefficients_for_assets( + model: &Model, + objective_type: ObjectiveType, + assets: &[AssetRef], + market_prices: &PriceMap, + fallback_prices: &PriceMap, + year: u32, +) -> HashMap> { + assets + .iter() + .map(|asset| { + let coefficient = calculate_coefficients_for_asset( + asset, + objective_type, + &model.time_slice_info, + market_prices, + fallback_prices, + year, + ); + (asset.clone(), Arc::new(coefficient)) + }) + .collect() +} + +/// Calculates cost coefficients for a single asset +fn calculate_coefficients_for_asset( + asset: &AssetRef, + objective_type: ObjectiveType, + time_slice_info: &TimeSliceInfo, + market_prices: &PriceMap, + fallback_prices: &PriceMap, + year: u32, +) -> ObjectiveCoefficients { + // Small constant added to each activity coefficient to ensure break-even/slightly negative + // assets are still dispatched + const EPSILON_ACTIVITY_COEFFICIENT: MoneyPerActivity = MoneyPerActivity(f64::EPSILON * 100.0); + + let mut activity_coefficients = IndexMap::new(); + let mut metric_costs = IndexMap::new(); + let primary_output_flow = asset.primary_output().unwrap(); + let asset_region = asset.region_id(); + for time_slice in time_slice_info.iter_ids() { + // Get the operating cost of the asset. This includes the variable operating cost, levies and + // flow costs, but excludes costs/revenues from commodity consumption/production. + let operating_cost = asset.get_operating_cost(year, time_slice); + let net_revenue = asset.get_revenue_from_flows(market_prices, time_slice) - operating_cost; + + let fallback_revenue = fallback_prices + .get(&primary_output_flow.commodity.id, asset_region, time_slice) + .unwrap_or(MoneyPerFlow(0.0)) + * primary_output_flow.coeff; + + activity_coefficients.insert( + time_slice.clone(), + fallback_revenue + net_revenue + EPSILON_ACTIVITY_COEFFICIENT, + ); + + let metric_cost = match objective_type { + ObjectiveType::LevelisedCostOfX => { + operating_cost + - asset.get_revenue_from_flows_excluding_primary(market_prices, time_slice) + } + ObjectiveType::NetPresentValue => -net_revenue, + }; + metric_costs.insert(time_slice.clone(), metric_cost); + } + + ObjectiveCoefficients { + activity_coefficients, + metric_costs, + } +} diff --git a/src/simulation/investment/population/constraints.rs b/src/simulation/investment/population/constraints.rs new file mode 100644 index 000000000..924df5bdc --- /dev/null +++ b/src/simulation/investment/population/constraints.rs @@ -0,0 +1,174 @@ +//! Constraints for the optimisation problem. +use super::optimisation::Variable; +use crate::asset::AssetRef; +use crate::commodity::Commodity; +use crate::model::Model; +use crate::simulation::investment::DemandMap; +use crate::time_slice::{Season, TimeSliceID, TimeSliceInfo, TimeSliceSelection}; +use crate::units::{MoneyPerCapacityPerYear, Year}; +use highs::RowProblem as Problem; +use indexmap::IndexMap; + +/// Adds activity constraints to the problem. +/// +/// Constrains the activity variables to be within the asset's activity limits. +/// +/// The asset's per-capacity activity limits are scaled by the asset's capacity to give +/// absolute bounds, and a single bounded constraint is added per time-slice selection covering the +/// sum of activity in that selection. +pub fn add_activity_constraints( + problem: &mut Problem, + asset: &AssetRef, + activity_vars: &IndexMap, + time_slice_info: &TimeSliceInfo, +) { + for (ts_selection, limits) in asset.iter_activity_limits() { + let limits = limits.start().value()..=limits.end().value(); + + // Collect activity terms for the time slices in this selection + let terms = ts_selection + .iter(time_slice_info) + .map(|(time_slice, _)| (activity_vars[time_slice], 1.0)) + .collect::>(); + + // Constraint: sum of activities in selection within limits + problem.add_row(limits, &terms); + } +} + +/// Adds demand constraints to the problem. +/// +/// Constrains supply to be less than or equal to demand. One inequality constraint is added per +/// time-slice selection at the commodity's balance level, capping the sum of activity (scaled by +/// flow coefficients) to the total demand for that selection. +pub fn add_demand_constraints( + problem: &mut Problem, + asset: &AssetRef, + commodity: &Commodity, + time_slice_info: &TimeSliceInfo, + demand: &DemandMap, + activity_vars: &IndexMap, +) { + let flow_coeff = asset.get_flow(&commodity.id).unwrap().coeff; + for ts_selection in time_slice_info.iter_selections_at_level(commodity.time_slice_level) { + let demand_for_ts_selection = demand[&ts_selection]; + let terms: Vec<_> = ts_selection + .iter(time_slice_info) + .map(|(time_slice, _)| (activity_vars[time_slice], flow_coeff.value())) + .collect(); + problem.add_row(0.0..=demand_for_ts_selection.value(), terms); + } +} + +/// Add seasonal and annual utilisation peak constraints to the problem. +/// +/// This is almost identical to equivalent constraints in the full-system dispatch, but here we +/// make the penalties negative as this is a maximise optimisation (whereas dispatch is a minimise +/// optimisation). +pub fn add_utilisation_peak_constraints( + problem: &mut Problem, + model: &Model, + asset: &AssetRef, + activity_vars: &IndexMap, +) { + let has_seasonal_penalty = + model.parameters.seasonal_utilisation_penalty > MoneyPerCapacityPerYear(0.0); + let has_annual_penalty = + model.parameters.annual_utilisation_penalty > MoneyPerCapacityPerYear(0.0); + + // If neither penalties are applied, we don't need to add any variables and constraints + if !has_seasonal_penalty && !has_annual_penalty { + return; + } + + // So long as either penalty is applied, we need to add seasonal peak variables and constraints + let seasonal_peak_vars = add_seasonal_peak_variables(problem, model); + add_seasonal_peak_constraints( + problem, + asset, + activity_vars, + &model.time_slice_info, + &seasonal_peak_vars, + ); + + // If the annual penalty is applied, we also need to add an annual peak variable and constraints + if has_annual_penalty { + let annual_peak_var = add_annual_peak_variable(problem, model); + add_annual_peak_constraints( + problem, + &model.time_slice_info, + annual_peak_var, + &seasonal_peak_vars, + ); + } +} + +/// Add seasonal peak variables to the problem. +fn add_seasonal_peak_variables( + problem: &mut Problem, + model: &Model, +) -> IndexMap { + let mut seasonal_peak_vars = IndexMap::new(); + for (season, duration) in &model.time_slice_info.seasons { + // Scale penalty by season duration + // We make the penalty negative as we're doing a max optimisation + let col_factor = -(model.parameters.seasonal_utilisation_penalty * *duration); + let variable = problem.add_column(col_factor.value(), 0.0..); + seasonal_peak_vars.insert(season.clone(), variable); + } + seasonal_peak_vars +} + +/// Add annual peak variable to the problem. +fn add_annual_peak_variable(problem: &mut Problem, model: &Model) -> highs::Col { + // Penalty is applied over the whole year, so scale by 1 year + // We make the penalty negative as we're doing a max optimisation + let col_factor = -(model.parameters.annual_utilisation_penalty * Year(1.0)); + problem.add_column(col_factor.value(), 0.0..) +} + +/// Add constraints linking seasonal peak variables to activity variables for each (asset, season) pair. +fn add_seasonal_peak_constraints( + problem: &mut Problem, + asset: &AssetRef, + activity_vars: &IndexMap, + time_slice_info: &TimeSliceInfo, + seasonal_peak_vars: &IndexMap, +) { + let activity_per_capacity = asset.process().capacity_to_activity; + for (season, &peak_variable) in seasonal_peak_vars { + for (time_slice, ts_length) in + TimeSliceSelection::Season(season.clone()).iter(time_slice_info) + { + let time_slice_fraction = ts_length / Year(1.0); + let activity_per_capacity_in_time_slice = activity_per_capacity * time_slice_fraction; + let capacity_required_per_activity = 1.0 / activity_per_capacity_in_time_slice.value(); + + // One unit of capacity supports `activity_per_capacity_in_time_slice` activity in + // this time slice. The peak variable therefore measures the capacity required by + // the activity in the time slice. + problem.add_row( + 0.0.., + [ + (peak_variable, 1.0), + (activity_vars[time_slice], -capacity_required_per_activity), + ], + ); + } + } +} + +/// Add constraints linking seasonal peak variables to annual peak variables for each asset. +fn add_annual_peak_constraints( + problem: &mut Problem, + time_slice_info: &TimeSliceInfo, + annual_peak_var: highs::Col, + seasonal_peak_vars: &IndexMap, +) { + for season in time_slice_info.seasons.keys() { + problem.add_row( + 0.0.., + [(annual_peak_var, 1.0), (seasonal_peak_vars[season], -1.0)], + ); + } +} diff --git a/src/simulation/investment/population/costs.rs b/src/simulation/investment/population/costs.rs new file mode 100644 index 000000000..d103cf8de --- /dev/null +++ b/src/simulation/investment/population/costs.rs @@ -0,0 +1,33 @@ +//! Costs for the optimisation problem. +use crate::asset::{AssetRef, AssetState}; +use crate::units::{MoneyPerCapacity, Year}; + +/// Calculates the annual fixed costs per unit of capacity for an asset. +/// +/// The behaviour depends on whether the asset is commissioned or a candidate: +/// - For a commissioned asset, this only includes operating costs. +/// - For a candidate asset, this includes both operating and capital costs. +/// +/// The return value is the annualised fixed cost expressed as `MoneyPerCapacity`. +/// If `asset.state()` is not `Commissioned` or `Candidate` this function will panic. +pub fn annual_fixed_cost(asset: &AssetRef) -> MoneyPerCapacity { + match asset.state() { + AssetState::Commissioned { .. } => annual_fixed_cost_for_existing(asset), + AssetState::Candidate => annual_fixed_cost_for_candidate(asset), + AssetState::Ready { .. } => { + panic!("annual_fixed_cost should only be called with Commissioned or Candidate assets") + } + } +} + +fn annual_fixed_cost_for_existing(asset: &AssetRef) -> MoneyPerCapacity { + let fixed_operating_cost = asset.process_parameter().fixed_operating_cost; + fixed_operating_cost * Year(1.0) +} + +fn annual_fixed_cost_for_candidate(asset: &AssetRef) -> MoneyPerCapacity { + let fixed_operating_cost = asset.process_parameter().fixed_operating_cost; + let annual_fixed_operating_cost = fixed_operating_cost * Year(1.0); + let capital_costs = asset.get_annual_capital_cost_per_capacity(); + annual_fixed_operating_cost + capital_costs +} diff --git a/src/simulation/investment/population/metrics.rs b/src/simulation/investment/population/metrics.rs new file mode 100644 index 000000000..dc3552f30 --- /dev/null +++ b/src/simulation/investment/population/metrics.rs @@ -0,0 +1,854 @@ +//! Calculation for investment tools such as Levelised Cost of X (LCOX) and Net Present Value (NPV). +use super::coefficients::ObjectiveCoefficients; +use super::costs::annual_fixed_cost; +use super::optimisation::{ResultsMap, perform_optimisation}; +use crate::agent::ObjectiveType; +use crate::asset::{Asset, AssetRef}; +use crate::commodity::Commodity; +use crate::finance::{lcox, snas}; +use crate::model::Model; +use crate::simulation::investment::DemandMap; +use crate::time_slice::TimeSliceID; +use crate::units::{Activity, MoneyPerActivity, MoneyPerCapacity}; +use anyhow::Result; +use erased_serde::Serialize as ErasedSerialize; +use float_cmp::{ApproxEq, F64Margin}; +use indexmap::IndexMap; +use serde::Serialize; +use std::any::Any; +use std::cmp::Ordering; +use std::sync::Arc; + +/// Compares two values with approximate equality checking. +/// +/// Returns `Ordering::Equal` if the values are approximately equal +/// according to the default floating-point margin, otherwise returns +/// their relative ordering based on `a.partial_cmp(&b)`. +/// +/// This is useful when comparing floating-point-based types where exact +/// equality may not be appropriate due to numerical precision limitations. +/// +/// # Panics +/// +/// Panics if `partial_cmp` returns `None` (i.e., if either value is NaN). +fn compare_approx(a: T, b: T) -> Ordering +where + T: Copy + PartialOrd + ApproxEq, +{ + if a.approx_eq(b, F64Margin::default()) { + Ordering::Equal + } else { + a.partial_cmp(&b).expect("Cannot compare NaN values") + } +} + +/// The output of investment appraisal required to compare potential investment decisions +pub struct AppraisalOutput { + /// The asset being appraised + pub asset: AssetRef, + /// Time slice level activity of the asset + pub activity: IndexMap, + /// The hypothetical unmet demand following investment in this asset + pub unmet_demand: DemandMap, + /// The comparison metric to compare investment decisions + pub metric: Option>, + /// Activity coefficients and metric costs used in the appraisal + pub coefficients: Arc, +} + +impl AppraisalOutput { + /// Create a new `AppraisalOutput` + fn new( + asset: AssetRef, + results: ResultsMap, + metric: Option, + coefficients: Arc, + ) -> Self { + Self { + asset, + activity: results.activity, + unmet_demand: results.unmet_demand, + metric: metric.map(|m| Box::new(m) as Box), + coefficients, + } + } + /// Compare this appraisal to another on the basis of the comparison metric. + /// + /// Note that if the metrics are approximately equal, then [`Ordering::Equal`] is returned. + /// The reason for this is because different CPU architectures may lead to subtly different + /// values for the comparison metrics and if the value is very similar to another, then it can + /// lead to different decisions being made, depending on the user's platform (e.g. macOS ARM + /// vs. Windows). We want to avoid this, if possible, which is why we use a more approximate + /// comparison. + fn compare_metric(&self, other: &Self) -> Ordering { + let (metric1, metric2) = self + .metric + .as_deref() + .zip(other.metric.as_deref()) + .expect("Cannot compare non-valid outputs"); + + // We've already checked the metrics aren't `None` + metric1.compare(metric2) + } +} + +/// Supertrait for appraisal metrics that can be serialised and compared. +pub trait MetricTrait: ComparableMetric + ErasedSerialize {} +erased_serde::serialize_trait_object!(MetricTrait); + +/// Trait for appraisal metrics that can be compared. +/// +/// Implementers define how their values should be compared to determine +/// which investment option is preferable through the `compare` method. +pub trait ComparableMetric: Any + Send + Sync { + /// Returns the numeric value of this metric. + fn value(&self) -> f64; + + /// Compares this metric with another of the same type. + /// + /// Returns `Ordering::Less` if `self` is better than `other`, + /// `Ordering::Greater` if `other` is better, or `Ordering::Equal` + /// if they are approximately equal. + /// + /// # Panics + /// + /// Panics if `other` is not the same concrete type as `self`. + fn compare(&self, other: &dyn ComparableMetric) -> Ordering; + + /// Helper for downcasting to enable type-safe comparison. + fn as_any(&self) -> &dyn Any; +} + +/// Levelised Cost of X (LCOX) metric. +/// +/// Represents the average cost per unit of output. Lower values indicate +/// more cost-effective investments. +#[derive(Debug, Clone, Serialize)] +pub struct LCOXMetric { + /// The calculated cost value for this LCOX metric + cost: MoneyPerActivity, +} + +impl LCOXMetric { + /// Creates a new `LCOXMetric` with the given cost. + pub fn new(cost: MoneyPerActivity) -> Self { + Self { cost } + } +} + +impl ComparableMetric for LCOXMetric { + fn value(&self) -> f64 { + self.cost.value() + } + + fn compare(&self, other: &dyn ComparableMetric) -> Ordering { + let other = other + .as_any() + .downcast_ref::() + .expect("Cannot compare metrics of different types"); + + compare_approx(self.cost, other.cost) + } + + fn as_any(&self) -> &dyn Any { + self + } +} + +/// `LCOXMetric` implements the `MetricTrait` supertrait. +impl MetricTrait for LCOXMetric {} + +/// Net Present Value (NPV) tool metric. +/// +/// In the NPV appraisal tool we compare options using the Specific Net Annualised Surplus (SNAS) +/// expressed per unit activity. Higher values indicate more profitable investments. +#[derive(Debug, Clone, Serialize)] +struct NPVMetric { + /// The calculated SNAS value for this metric + snas: MoneyPerActivity, +} + +impl NPVMetric { + /// Creates a new `NPVMetric` with the given SNAS value. + fn new(snas: MoneyPerActivity) -> Self { + Self { snas } + } +} + +impl ComparableMetric for NPVMetric { + fn value(&self) -> f64 { + self.snas.value() + } + + fn compare(&self, other: &dyn ComparableMetric) -> Ordering { + let other = other + .as_any() + .downcast_ref::() + .expect("Cannot compare metrics of different types"); + + compare_approx(other.snas, self.snas) + } + + fn as_any(&self) -> &dyn Any { + self + } +} + +/// `NPVMetric` implements the `MetricTrait` supertrait. +impl MetricTrait for NPVMetric {} + +/// Calculate LCOX for a hypothetical investment in the given asset. +/// +/// This is more commonly referred to as Levelised Cost of *Electricity*, but as the model can +/// include other flows, we use the term LCOX. +/// +/// # Returns +/// +/// An `AppraisalOutput` containing the hypothetical capacity, activity profile and unmet demand. +/// The returned `metric` is the LCOX value (lower is better). +fn calculate_lcox( + model: &Model, + asset: &AssetRef, + commodity: &Commodity, + coefficients: &Arc, + demand: &DemandMap, +) -> Result { + let results = perform_optimisation(model, asset, commodity, coefficients, demand)?; + + let cost_index = lcox( + asset.total_capacity(), + annual_fixed_cost(asset), + &results.activity, + &coefficients.metric_costs, + ); + + Ok(AppraisalOutput::new( + asset.clone(), + results, + cost_index.map(LCOXMetric::new), + coefficients.clone(), + )) +} + +/// Calculate NPV for a hypothetical investment in the given asset. +/// +/// # Returns +/// +/// An `AppraisalOutput` containing the hypothetical capacity, activity profile and unmet demand. +fn calculate_npv( + model: &Model, + asset: &AssetRef, + commodity: &Commodity, + coefficients: &Arc, + demand: &DemandMap, +) -> Result { + let results = perform_optimisation(model, asset, commodity, coefficients, demand)?; + + let annual_fixed_cost = annual_fixed_cost(asset); + assert!( + annual_fixed_cost >= MoneyPerCapacity(0.0), + "The current NPV calculation does not support negative annual fixed costs" + ); + + let snas = snas( + asset.total_capacity(), + annual_fixed_cost, + &results.activity, + &coefficients.metric_costs, + ); + + Ok(AppraisalOutput::new( + asset.clone(), + results, + snas.map(NPVMetric::new), + coefficients.clone(), + )) +} + +/// Appraise the given investment with the specified objective type. +/// +/// # Returns +/// +/// The `AppraisalOutput` produced by the selected appraisal method. The `metric` field is +/// comparable with other appraisals of the same type (npv/lcox). +pub fn appraise_investment( + model: &Model, + asset: &AssetRef, + commodity: &Commodity, + objective_type: ObjectiveType, + coefficients: &Arc, + demand: &DemandMap, +) -> Result { + let appraisal_method = match objective_type { + ObjectiveType::LevelisedCostOfX => calculate_lcox, + ObjectiveType::NetPresentValue => calculate_npv, + }; + appraisal_method(model, asset, commodity, coefficients, demand) +} + +/// Compare assets as a fallback if metrics are equal. +/// +/// Commissioned assets are ordered before uncommissioned and newer before older. +/// +/// Used as a fallback to sort assets when they have equal appraisal tool outputs. +fn compare_asset_fallback(asset1: &Asset, asset2: &Asset) -> Ordering { + (asset2.is_commissioned(), asset2.commission_year()) + .cmp(&(asset1.is_commissioned(), asset1.commission_year())) +} + +/// Sort appraisal outputs by their investment priority and exclude non-feasible options. +/// +/// Investment priority is primarily decided by appraisal metric. When appraisal metrics are equal, +/// a tie-breaker fallback is used. Commissioned assets are preferred over uncommissioned assets, +/// and newer assets are preferred over older ones. The function does not guarantee that all ties +/// will be resolved. +/// +/// Before sorting, outputs are filtered to exclude entries with invalid metrics (i.e. `None`), so +/// the length of the returned vector may be less than the input. +/// +/// # Returns +/// +/// Returns the number of non-feasible assets which were removed. +pub fn sort_and_filter_appraisal_outputs(outputs: &mut Vec) -> usize { + let old_len = outputs.len(); + outputs.retain(|output| output.metric.is_some()); + let num_nonfeasible = old_len - outputs.len(); + + outputs.sort_by(|output1, output2| match output1.compare_metric(output2) { + // If equal, we fall back on comparing asset properties + Ordering::Equal => compare_asset_fallback(&output1.asset, &output2.asset), + cmp => cmp, + }); + + num_nonfeasible +} + +/// Counts the number of top appraisal outputs in a sorted slice that are indistinguishable +/// by both metric and fallback ordering. Excludes the first element from the count. +pub fn count_equal_and_best_appraisal_outputs(outputs: &[AppraisalOutput]) -> usize { + if outputs.is_empty() { + return 0; + } + outputs[1..] + .iter() + .take_while(|output| { + output.compare_metric(&outputs[0]).is_eq() + && compare_asset_fallback(&output.asset, &outputs[0].asset).is_eq() + }) + .count() +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::agent::AgentID; + use crate::asset::AssetCapacity; + use crate::fixture::{agent_id, asset, process, region_id}; + use crate::process::Process; + use crate::region::RegionID; + use crate::units::{Capacity, MoneyPerActivity}; + use float_cmp::assert_approx_eq; + use rstest::rstest; + use std::sync::Arc; + + /// Parametrised tests for LCOX metric comparison. + #[rstest] + #[case(10.0, 10.0, Ordering::Equal, "equal_costs")] + #[case(5.0, 10.0, Ordering::Less, "first_lower_cost_is_better")] + #[case(10.0, 5.0, Ordering::Greater, "second_lower_cost_is_better")] + fn lcox_metric_comparison( + #[case] cost1: f64, + #[case] cost2: f64, + #[case] expected: Ordering, + #[case] description: &str, + ) { + let metric1 = LCOXMetric::new(MoneyPerActivity(cost1)); + let metric2 = LCOXMetric::new(MoneyPerActivity(cost2)); + + assert_eq!( + metric1.compare(&metric2), + expected, + "Failed comparison for case: {description}" + ); + } + + /// Parametrised tests for NPV metric comparison. + #[rstest] + #[case(10.0, 10.0, Ordering::Equal, "equal_costs")] + #[case(5.0, 10.0, Ordering::Greater, "second_higher_metric_is_better")] + #[case(10.0, 5.0, Ordering::Less, "first_higher_metric_is_better")] + fn npv_metric_comparison( + #[case] cost1: f64, + #[case] cost2: f64, + #[case] expected: Ordering, + #[case] description: &str, + ) { + let metric1 = NPVMetric::new(MoneyPerActivity(cost1)); + let metric2 = NPVMetric::new(MoneyPerActivity(cost2)); + + assert_eq!( + metric1.compare(&metric2), + expected, + "Failed comparison for case: {description}" + ); + } + + #[rstest] + fn compare_assets_fallback(process: Process, region_id: RegionID, agent_id: AgentID) { + let capacity = Capacity(2.0); + let process = Arc::new(process); + let asset1 = Asset::new_commissioned( + agent_id.clone(), + process.clone(), + region_id.clone(), + AssetCapacity::single(capacity), + 2015, + ) + .unwrap(); + let asset2 = + Asset::new_candidate(process.clone(), region_id.clone(), capacity, 2015).unwrap(); + let asset3 = Asset::new_commissioned( + agent_id, + process, + region_id.clone(), + AssetCapacity::single(capacity), + 2010, + ) + .unwrap(); + + assert!(compare_asset_fallback(&asset1, &asset1).is_eq()); + assert!(compare_asset_fallback(&asset2, &asset2).is_eq()); + assert!(compare_asset_fallback(&asset3, &asset3).is_eq()); + assert!(compare_asset_fallback(&asset1, &asset2).is_lt()); + assert!(compare_asset_fallback(&asset2, &asset1).is_gt()); + assert!(compare_asset_fallback(&asset1, &asset3).is_lt()); + assert!(compare_asset_fallback(&asset3, &asset1).is_gt()); + assert!(compare_asset_fallback(&asset3, &asset2).is_lt()); + assert!(compare_asset_fallback(&asset2, &asset3).is_gt()); + } + + fn objective_coeffs() -> Arc { + Arc::new(ObjectiveCoefficients { + activity_coefficients: IndexMap::new(), + metric_costs: IndexMap::new(), + }) + } + + /// Creates appraisal from corresponding assets and metrics + /// + /// # Panics + /// + /// Panics if `assets` and `metrics` have different lengths + fn appraisal_outputs( + assets: Vec, + metrics: Vec>, + ) -> Vec { + assert_eq!( + assets.len(), + metrics.len(), + "assets and metrics must have the same length" + ); + + assets + .into_iter() + .zip(metrics) + .map(|(asset, metric)| AppraisalOutput { + asset: AssetRef::from(asset), + coefficients: objective_coeffs(), + activity: IndexMap::new(), + unmet_demand: IndexMap::new(), + metric: Some(metric), + }) + .collect() + } + + /// Creates appraisal outputs with given metrics. + /// Copies the provided default asset for each metric. + fn appraisal_outputs_with_investment_priority_invariant_to_assets( + metrics: Vec>, + asset: &Asset, + ) -> Vec { + let assets = vec![asset.clone(); metrics.len()]; + appraisal_outputs(assets, metrics) + } + + /// Test sorting by LCOX metric when invariant to asset properties + #[rstest] + fn appraisal_sort_by_lcox_metric(asset: Asset) { + let metrics: Vec> = vec![ + Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), + Box::new(LCOXMetric::new(MoneyPerActivity(3.0))), + Box::new(LCOXMetric::new(MoneyPerActivity(7.0))), + ]; + + let mut outputs = + appraisal_outputs_with_investment_priority_invariant_to_assets(metrics, &asset); + sort_and_filter_appraisal_outputs(&mut outputs); + + assert_approx_eq!(f64, outputs[0].metric.as_ref().unwrap().value(), 3.0); // Best (lowest) + assert_approx_eq!(f64, outputs[1].metric.as_ref().unwrap().value(), 5.0); + assert_approx_eq!(f64, outputs[2].metric.as_ref().unwrap().value(), 7.0); // Worst (highest) + } + + /// Test sorting by NPV metric when invariant to asset properties + #[rstest] + fn appraisal_sort_by_npv_metric(asset: Asset) { + let metrics: Vec> = vec![ + Box::new(NPVMetric::new(MoneyPerActivity(5.0))), + Box::new(NPVMetric::new(MoneyPerActivity(3.0))), + Box::new(NPVMetric::new(MoneyPerActivity(7.0))), + ]; + + let mut outputs = + appraisal_outputs_with_investment_priority_invariant_to_assets(metrics, &asset); + sort_and_filter_appraisal_outputs(&mut outputs); + + assert_approx_eq!(f64, outputs[0].metric.as_ref().unwrap().value(), 7.0); // Best (highest) + assert_approx_eq!(f64, outputs[1].metric.as_ref().unwrap().value(), 5.0); + assert_approx_eq!(f64, outputs[2].metric.as_ref().unwrap().value(), 3.0); // Worst (lowest) + } + + /// Test that mixing LCOX and NPV metrics causes a runtime panic during comparison + #[rstest] + #[should_panic(expected = "Cannot compare metrics of different types")] + fn appraisal_sort_by_mixed_metrics_panics(asset: Asset) { + let metrics: Vec> = vec![ + Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), + Box::new(NPVMetric::new(MoneyPerActivity(3.0))), + Box::new(LCOXMetric::new(MoneyPerActivity(3.0))), + ]; + + let mut outputs = + appraisal_outputs_with_investment_priority_invariant_to_assets(metrics, &asset); + // This should panic when trying to compare different metric types + sort_and_filter_appraisal_outputs(&mut outputs); + } + + /// Test that when metrics are equal, commissioned assets are sorted by commission year (newer first) + #[rstest] + fn appraisal_sort_by_commission_year_when_metrics_equal( + process: Process, + region_id: RegionID, + agent_id: AgentID, + ) { + let process_rc = Arc::new(process); + let capacity = Capacity(10.0); + let commission_years = [2015, 2020, 2010]; + + let assets: Vec<_> = commission_years + .iter() + .map(|&year| { + Asset::new_commissioned( + agent_id.clone(), + process_rc.clone(), + region_id.clone(), + AssetCapacity::single(capacity), + year, + ) + .unwrap() + }) + .collect(); + + // All metrics have the same value + let metrics: Vec> = vec![ + Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), + Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), + Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), + ]; + + let mut outputs = appraisal_outputs(assets, metrics); + sort_and_filter_appraisal_outputs(&mut outputs); + + // Should be sorted by commission year, newest first: 2020, 2015, 2010 + assert_eq!(outputs[0].asset.commission_year(), 2020); + assert_eq!(outputs[1].asset.commission_year(), 2015); + assert_eq!(outputs[2].asset.commission_year(), 2010); + } + + /// Test that when metrics and commission years are equal, the original order is preserved + #[rstest] + fn appraisal_sort_maintains_order_when_all_equal(process: Process, region_id: RegionID) { + let process_rc = Arc::new(process); + let capacity = AssetCapacity::single(Capacity(10.0)); + let commission_year = 2015; + let agent_ids = ["agent1", "agent2", "agent3"]; + + let assets: Vec<_> = agent_ids + .iter() + .map(|&id| { + Asset::new_commissioned( + AgentID(id.into()), + process_rc.clone(), + region_id.clone(), + capacity, + commission_year, + ) + .unwrap() + }) + .collect(); + + let metrics: Vec> = vec![ + Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), + Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), + Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), + ]; + + let mut outputs = appraisal_outputs(assets.clone(), metrics); + sort_and_filter_appraisal_outputs(&mut outputs); + + // Verify order is preserved - should match the original agent_ids array + for (&expected_id, output) in agent_ids.iter().zip(outputs) { + assert_eq!(output.asset.agent_id(), Some(&AgentID(expected_id.into()))); + } + } + + /// Test that commissioned assets are prioritised over non-commissioned assets when metrics are equal + #[rstest] + fn appraisal_sort_commissioned_before_uncommissioned_when_metrics_equal( + process: Process, + region_id: RegionID, + agent_id: AgentID, + ) { + let process_rc = Arc::new(process); + let capacity = Capacity(10.0); + + // Create a mix of commissioned and candidate (non-commissioned) assets + let commissioned_asset_newer = Asset::new_commissioned( + agent_id.clone(), + process_rc.clone(), + region_id.clone(), + AssetCapacity::single(capacity), + 2020, + ) + .unwrap(); + + let commissioned_asset_older = Asset::new_commissioned( + agent_id.clone(), + process_rc.clone(), + region_id.clone(), + AssetCapacity::single(capacity), + 2015, + ) + .unwrap(); + + let candidate_asset = + Asset::new_candidate(process_rc.clone(), region_id.clone(), capacity, 2020).unwrap(); + + let assets = vec![ + candidate_asset.clone(), + commissioned_asset_older.clone(), + candidate_asset.clone(), + commissioned_asset_newer.clone(), + ]; + + // All metrics have identical values to test fallback ordering + let metrics: Vec> = vec![ + Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), + Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), + Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), + Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), + ]; + + let mut outputs = appraisal_outputs(assets, metrics); + sort_and_filter_appraisal_outputs(&mut outputs); + + // Commissioned assets should be prioritised first + assert!(outputs[0].asset.is_commissioned()); + assert_eq!(outputs[0].asset.commission_year(), 2020); + assert!(outputs[1].asset.is_commissioned()); + assert_eq!(outputs[1].asset.commission_year(), 2015); + + // Non-commissioned assets should come after + assert!(!outputs[2].asset.is_commissioned()); + assert!(!outputs[3].asset.is_commissioned()); + } + + /// Test that appraisal metric is prioritised over asset properties when sorting + #[rstest] + fn appraisal_metric_is_prioritised_over_asset_properties( + process: Process, + region_id: RegionID, + agent_id: AgentID, + ) { + let process_rc = Arc::new(process); + let capacity = Capacity(10.0); + + // Create a mix of commissioned and candidate (non-commissioned) assets + let commissioned_asset_newer = Asset::new_commissioned( + agent_id.clone(), + process_rc.clone(), + region_id.clone(), + AssetCapacity::single(capacity), + 2020, + ) + .unwrap(); + + let commissioned_asset_older = Asset::new_commissioned( + agent_id.clone(), + process_rc.clone(), + region_id.clone(), + AssetCapacity::single(capacity), + 2015, + ) + .unwrap(); + + let candidate_asset = + Asset::new_candidate(process_rc.clone(), region_id.clone(), capacity, 2020).unwrap(); + + let assets = vec![ + candidate_asset.clone(), + commissioned_asset_older.clone(), + candidate_asset.clone(), + commissioned_asset_newer.clone(), + ]; + + // Make one metric slightly better than all others + let baseline_metric_value = 5.0; + let best_metric_value = baseline_metric_value - 1e-5; + let metrics: Vec> = vec![ + Box::new(LCOXMetric::new(MoneyPerActivity(best_metric_value))), + Box::new(LCOXMetric::new(MoneyPerActivity(baseline_metric_value))), + Box::new(LCOXMetric::new(MoneyPerActivity(baseline_metric_value))), + Box::new(LCOXMetric::new(MoneyPerActivity(baseline_metric_value))), + ]; + + let mut outputs = appraisal_outputs(assets, metrics); + sort_and_filter_appraisal_outputs(&mut outputs); + + // non-commissioned asset prioritised because it has a slightly better metric + assert_approx_eq!( + f64, + outputs[0].metric.as_ref().unwrap().value(), + best_metric_value + ); + } + + /// Test that appraisal outputs with an invalid metric are filtered out + #[rstest] + fn appraisal_sort_filters_invalid_metric(asset: Asset) { + let output = AppraisalOutput { + asset: AssetRef::from(asset), + coefficients: objective_coeffs(), + activity: IndexMap::new(), + unmet_demand: IndexMap::new(), + metric: None, + }; + let mut outputs = vec![output]; + + sort_and_filter_appraisal_outputs(&mut outputs); + + // The invalid output should have been filtered out + assert_eq!(outputs.len(), 0); + } + + /// Tests for counting number of equal metrics using identical assets so only metric values + /// affect the count. + #[rstest] + #[case(vec![5.0], 0, "single_element")] + #[case(vec![5.0, 5.0, 5.0], 2, "all_equal_returns_len_minus_one")] + #[case(vec![1.0, 2.0, 3.0], 0, "none_equal_to_best")] + #[case(vec![5.0, 5.0, 9.0], 1, "partial_equality_stops_at_first_difference")] + #[case(vec![5.0, 5.0, 9.0, 5.0], 1, "equality_does_not_resume_after_gap")] + fn count_equal_best_lcox_metric( + asset: Asset, + #[case] metric_values: Vec, + #[case] expected_count: usize, + #[case] description: &str, + ) { + let metrics: Vec> = metric_values + .into_iter() + .map(|v| Box::new(LCOXMetric::new(MoneyPerActivity(v))) as Box) + .collect(); + + let outputs = + appraisal_outputs_with_investment_priority_invariant_to_assets(metrics, &asset); + + assert_eq!( + count_equal_and_best_appraisal_outputs(&outputs), + expected_count, + "Failed for case: {description}" + ); + } + + /// Empty slice count should return 0. + #[test] + fn count_equal_best_empty_slice_returns_zero() { + let outputs: Vec = vec![]; + assert_eq!(count_equal_and_best_appraisal_outputs(&outputs), 0); + } + + /// Equal metrics but differing asset fallback (commissioned vs. candidate) → + /// outputs are distinguishable, so count should be 0. + #[rstest] + fn count_equal_best_equal_metric_different_fallback_returns_zero( + process: Process, + region_id: RegionID, + agent_id: AgentID, + ) { + let process_rc = Arc::new(process); + let capacity = Capacity(10.0); + + let commissioned = Asset::new_commissioned( + agent_id.clone(), + process_rc.clone(), + region_id.clone(), + AssetCapacity::single(capacity), + 2020, + ) + .unwrap(); + let candidate = + Asset::new_candidate(process_rc.clone(), region_id.clone(), capacity, 2020).unwrap(); + + let metric_value = MoneyPerActivity(5.0); + let outputs = appraisal_outputs( + vec![commissioned, candidate], + vec![ + Box::new(LCOXMetric::new(metric_value)), + Box::new(LCOXMetric::new(metric_value)), + ], + ); + + assert_eq!(count_equal_and_best_appraisal_outputs(&outputs), 0); + } + + /// Equal metrics and equal asset fallback (same commissioned status and commission year) → + /// the second element is indistinguishable, so count should be 1. + #[rstest] + fn count_equal_best_equal_metric_and_equal_fallback_returns_one( + process: Process, + region_id: RegionID, + agent_id: AgentID, + ) { + let process_rc = Arc::new(process); + let capacity = Capacity(10.0); + let year = 2020; + + let asset1 = Asset::new_commissioned( + agent_id.clone(), + process_rc.clone(), + region_id.clone(), + AssetCapacity::single(capacity), + year, + ) + .unwrap(); + let asset2 = Asset::new_commissioned( + agent_id.clone(), + process_rc.clone(), + region_id.clone(), + AssetCapacity::single(capacity), + year, + ) + .unwrap(); + + let metric_value = MoneyPerActivity(5.0); + let outputs = appraisal_outputs( + vec![asset1, asset2], + vec![ + Box::new(LCOXMetric::new(metric_value)), + Box::new(LCOXMetric::new(metric_value)), + ], + ); + + assert_eq!(count_equal_and_best_appraisal_outputs(&outputs), 1); + } +} diff --git a/src/simulation/investment/population/optimisation.rs b/src/simulation/investment/population/optimisation.rs new file mode 100644 index 000000000..e9940e2a9 --- /dev/null +++ b/src/simulation/investment/population/optimisation.rs @@ -0,0 +1,174 @@ +//! Optimisation problem for investment tools. +use super::coefficients::ObjectiveCoefficients; +use super::constraints::{ + add_activity_constraints, add_demand_constraints, add_utilisation_peak_constraints, +}; +use crate::asset::AssetRef; +use crate::commodity::Commodity; +use crate::model::Model; +use crate::optimisation::{ModelError, apply_highs_options_from_toml, solve_optimal}; +use crate::simulation::activity::ActivityMap; +use crate::simulation::investment::DemandMap; +use crate::time_slice::{TimeSliceID, TimeSliceInfo}; +use crate::units::{Activity, Flow}; +use anyhow::{Context, Result}; +use highs::{RowProblem as Problem, Sense}; +use indexmap::IndexMap; +use std::collections::HashMap; +use std::sync::Arc; + +/// A decision variable in the optimisation +/// +/// This alias represents a column created in the `highs` solver. Callers rely on the order +/// in which columns are added to the problem when extracting solution values. +pub type Variable = highs::Col; + +/// Map containing optimisation results and coefficients +pub struct ResultsMap { + /// Activity variables in each time slice + pub activity: IndexMap, + /// Remaining unmet demand per time slice, computed post-solve + pub unmet_demand: DemandMap, +} + +/// Adds activity variables to the problem, one per time slice. +/// +/// Returns a map from time slice to the corresponding decision variable. +fn add_activity_vars( + problem: &mut Problem, + cost_coefficients: &ObjectiveCoefficients, +) -> IndexMap { + cost_coefficients + .activity_coefficients + .iter() + .map(|(time_slice, cost)| { + let var = problem.add_column(cost.value(), 0.0..); + (time_slice.clone(), var) + }) + .collect() +} + +/// Adds constraints to the problem. +fn add_constraints( + problem: &mut Problem, + model: &Model, + asset: &AssetRef, + commodity: &Commodity, + activity_vars: &IndexMap, + demand: &DemandMap, + time_slice_info: &TimeSliceInfo, +) { + add_activity_constraints(problem, asset, activity_vars, time_slice_info); + add_demand_constraints( + problem, + asset, + commodity, + time_slice_info, + demand, + activity_vars, + ); + add_utilisation_peak_constraints(problem, model, asset, activity_vars); +} + +/// Computes remaining unmet demand per time-slice selection after a solve. +/// +/// For each time-slice selection at the commodity's balance level, the selection-level residual +/// (`demand - supply`, clamped to zero) is stored directly. Downstream consumers operate at the +/// selection level (e.g. the next round's demand constraint and `is_any_remaining_demand`), so +/// there is no need to distribute values across individual time slices. +fn compute_unmet_demand( + demand: &DemandMap, + activity: &IndexMap, + commodity: &Commodity, + asset: &AssetRef, + time_slice_info: &TimeSliceInfo, +) -> DemandMap { + let flow_coeff = asset.get_flow(&commodity.id).unwrap().coeff; + time_slice_info + .iter_selections_at_level(commodity.time_slice_level) + .map(|ts_selection| { + let demand_for_selection = demand[&ts_selection]; + let supply_for_selection: Flow = ts_selection + .iter(time_slice_info) + .map(|(ts, _)| activity[ts] * flow_coeff) + .sum(); + let unmet = (demand_for_selection - supply_for_selection).max(Flow(0.0)); + (ts_selection, unmet) + }) + .collect() +} + +/// Performs optimisation for an asset, given the coefficients and demand. +pub fn perform_optimisation( + model: &Model, + asset: &AssetRef, + commodity: &Commodity, + coefficients: &ObjectiveCoefficients, + demand: &DemandMap, +) -> Result { + // Create problem and add variables + let mut problem = Problem::default(); + let activity_vars = add_activity_vars(&mut problem, coefficients); + + // Add constraints + add_constraints( + &mut problem, + model, + asset, + commodity, + &activity_vars, + demand, + &model.time_slice_info, + ); + + // Solve model + let mut highs_model = problem.optimise(Sense::Maximise); + apply_highs_options_from_toml(&mut highs_model, &model.parameters.highs.appraisal_options) + .context("Failed to apply custom HiGHS options to appraisal optimisation")?; + // Enforce single-threaded solving: when appraisals run in parallel via Rayon each HiGHS + // instance must not spawn additional worker threads. Setting `parallel="off"` disables + // HiGHS's concurrent simplex strategy without touching the global thread-pool scheduler + // (setting `threads=N` would fail if the scheduler was already initialised on this thread + // by a previous solve with a different count). + highs_model.set_option("parallel", "off"); + let solution = solve_optimal(highs_model) + .map_err(ModelError::into_anyhow)? + .get_solution(); + let solution_values = solution.columns(); + let activity = activity_vars + .keys() + .zip(solution_values.iter()) + .map(|(time_slice, &value)| (time_slice.clone(), Activity::new(value))) + .collect(); + let unmet_demand = + compute_unmet_demand(demand, &activity, commodity, asset, &model.time_slice_info); + Ok(ResultsMap { + activity, + unmet_demand, + }) +} + +/// Dispatches each asset in order, reducing demand after each single-asset optimisation. +pub fn solve_for_assets( + model: &Model, + assets: &[AssetRef], + commodity: &Commodity, + coefficients: &HashMap>, + demand: &DemandMap, +) -> Result<(ActivityMap, DemandMap)> { + let mut activity = ActivityMap::new(); + let mut unmet_demand = demand.clone(); + + for asset in assets { + let results = + perform_optimisation(model, asset, commodity, &coefficients[asset], &unmet_demand)?; + for (time_slice, value) in results.activity { + *activity + .entry((asset.clone(), time_slice)) + .or_insert(Activity(0.0)) += value; + } + unmet_demand = results.unmet_demand; + } + + Ok((activity, unmet_demand)) +} diff --git a/src/simulation/investment/population/output.rs b/src/simulation/investment/population/output.rs new file mode 100644 index 000000000..c3476edfe --- /dev/null +++ b/src/simulation/investment/population/output.rs @@ -0,0 +1,202 @@ +//! Debug output for the competitive asset selection algorithm. +use super::metrics::AppraisalOutput; +use crate::asset::AssetID; +use crate::output::DebugDataWriter; +use crate::process::ProcessID; +use crate::region::RegionID; +use crate::simulation::investment::DemandMap; +use crate::time_slice::{TimeSliceID, TimeSliceLevel, TimeSliceSelection}; +use crate::units::{Activity, Capacity, Flow, MoneyPerActivity}; +use anyhow::Result; +use serde::{Deserialize, Serialize}; + +/// The output file name for appraisal results +const APPRAISAL_RESULTS_FILE_NAME: &str = "debug_asset_selection_competitive.csv"; + +/// The output file name for appraisal time slice results +const APPRAISAL_RESULTS_TIME_SLICE_FILE_NAME: &str = + "debug_asset_selection_competitive_time_slices.csv"; + +/// Represents the appraisal results in a row of the appraisal results CSV file +#[derive(Serialize, Deserialize, Debug, PartialEq)] +struct AppraisalResultsRow { + milestone_year: u32, + run_description: String, + asset_id: Option, + process_id: ProcessID, + region_id: RegionID, + capacity: Capacity, + metric: Option, +} + +/// Represents the appraisal results in a row of the appraisal results time slice CSV file +#[derive(Serialize, Deserialize, Debug, PartialEq)] +struct AppraisalResultsTimeSliceRow { + milestone_year: u32, + run_description: String, + asset_id: Option, + process_id: ProcessID, + region_id: RegionID, + time_slice: TimeSliceID, + activity: Activity, + activity_coefficient: MoneyPerActivity, + time_slice_level: TimeSliceLevel, + demand_for_selection: Flow, + unmet_demand_for_selection: Flow, +} + +/// Write debug info about a round of investment appraisal +pub fn write_debug_info( + writer: &mut DebugDataWriter, + milestone_year: u32, + run_description: &str, + appraisal_results: &[AppraisalOutput], + demand: &DemandMap, + time_slice_level: TimeSliceLevel, +) -> Result<()> { + let run_description = writer.debug_run_description(run_description); + + let rows = appraisal_results.iter().map(|result| AppraisalResultsRow { + milestone_year, + run_description: run_description.to_string(), + asset_id: result.asset.id(), + process_id: result.asset.process_id().clone(), + region_id: result.asset.region_id().clone(), + capacity: result.asset.total_capacity(), + metric: result.metric.as_ref().map(|m| m.value()), + }); + let output_writer = writer.get_custom_writer(APPRAISAL_RESULTS_FILE_NAME)?; + for row in rows { + output_writer.serialize(row)?; + } + + let time_slice_rows = appraisal_results.iter().flat_map(|result| { + let run_description = &run_description; + result.activity.iter().map(move |(time_slice, activity)| { + // Map the individual time slice back to its containing selection so we can look + // up selection-level demand and unmet demand. + let selection = match time_slice_level { + TimeSliceLevel::Annual => TimeSliceSelection::Annual, + TimeSliceLevel::Season => TimeSliceSelection::Season(time_slice.season.clone()), + TimeSliceLevel::DayNight => TimeSliceSelection::Single(time_slice.clone()), + }; + AppraisalResultsTimeSliceRow { + milestone_year, + run_description: run_description.to_string(), + asset_id: result.asset.id(), + process_id: result.asset.process_id().clone(), + region_id: result.asset.region_id().clone(), + time_slice: time_slice.clone(), + activity: *activity, + activity_coefficient: result.coefficients.activity_coefficients[time_slice], + time_slice_level, + demand_for_selection: demand[&selection], + unmet_demand_for_selection: result.unmet_demand[&selection], + } + }) + }); + let output_writer = writer.get_custom_writer(APPRAISAL_RESULTS_TIME_SLICE_FILE_NAME)?; + for row in time_slice_rows { + output_writer.serialize(row)?; + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::super::coefficients::ObjectiveCoefficients; + use super::super::metrics::LCOXMetric; + use super::*; + use crate::asset::{Asset, AssetRef}; + use crate::fixture::{asset, time_slice}; + use crate::output::DataWriter; + use indexmap::indexmap; + use itertools::{Itertools, assert_equal}; + use rstest::{fixture, rstest}; + use std::iter; + use std::path::Path; + use std::sync::Arc; + use tempfile::tempdir; + + #[fixture] + fn appraisal_output(asset: Asset, time_slice: TimeSliceID) -> AppraisalOutput { + let activity_coefficients = indexmap! { time_slice.clone() => MoneyPerActivity(0.5) }; + let metric_costs = indexmap! { time_slice.clone() => MoneyPerActivity(0.4) }; + let activity = indexmap! { time_slice.clone() => Activity(10.0) }; + let unmet_demand = + indexmap! { TimeSliceSelection::Single(time_slice.clone()) => Flow(5.0) }; + AppraisalOutput { + asset: AssetRef::from(asset), + coefficients: Arc::new(ObjectiveCoefficients { + activity_coefficients, + metric_costs, + }), + activity, + unmet_demand, + metric: Some(Box::new(LCOXMetric::new(MoneyPerActivity(4.14)))), + } + } + + fn read_rows Deserialize<'de>>(dir: &Path, file_name: &str) -> Vec { + csv::Reader::from_path(dir.join(file_name)) + .unwrap() + .into_deserialize() + .try_collect() + .unwrap() + } + + #[rstest] + fn write_debug_info_works( + asset: Asset, + appraisal_output: AppraisalOutput, + time_slice: TimeSliceID, + ) { + let milestone_year = 2020; + let run_description = "test_run".to_string(); + let dir = tempdir().unwrap(); + let demand = indexmap! { TimeSliceSelection::Single(time_slice.clone()) => Flow(100.0) }; + + { + let mut writer = DataWriter::create(dir.path(), dir.path(), true).unwrap(); + write_debug_info( + writer.debug_writer().unwrap(), + milestone_year, + &run_description, + &[appraisal_output], + &demand, + TimeSliceLevel::DayNight, + ) + .unwrap(); + writer.flush().unwrap(); + } + + let expected = AppraisalResultsRow { + milestone_year, + run_description: run_description.clone(), + asset_id: None, + process_id: asset.process_id().clone(), + region_id: asset.region_id().clone(), + capacity: Capacity(2.0), + metric: Some(4.14), + }; + let records: Vec = read_rows(dir.path(), APPRAISAL_RESULTS_FILE_NAME); + assert_equal(records, iter::once(expected)); + + let expected = AppraisalResultsTimeSliceRow { + milestone_year, + run_description, + asset_id: None, + process_id: asset.process_id().clone(), + region_id: asset.region_id().clone(), + time_slice: time_slice.clone(), + activity: Activity(10.0), + activity_coefficient: MoneyPerActivity(0.5), + time_slice_level: TimeSliceLevel::DayNight, + demand_for_selection: Flow(100.0), + unmet_demand_for_selection: Flow(5.0), + }; + let records: Vec = + read_rows(dir.path(), APPRAISAL_RESULTS_TIME_SLICE_FILE_NAME); + assert_equal(records, iter::once(expected)); + } +} From 4ce6001dcbe1065705b1c97f3d427ce6ebce97fa Mon Sep 17 00:00:00 2001 From: Tom Bland Date: Tue, 17 Nov 2026 13:52:04 +0000 Subject: [PATCH 3/5] Implement population algorithm --- src/simulation/investment/population.rs | 987 ++++++++---------- .../investment/population/coefficients.rs | 109 -- .../investment/population/constraints.rs | 138 ++- .../investment/population/metrics.rs | 867 +-------------- .../investment/population/optimisation.rs | 225 ++-- .../investment/population/output.rs | 181 ++-- 6 files changed, 745 insertions(+), 1762 deletions(-) delete mode 100644 src/simulation/investment/population/coefficients.rs diff --git a/src/simulation/investment/population.rs b/src/simulation/investment/population.rs index 30f06dac9..3d793d428 100644 --- a/src/simulation/investment/population.rs +++ b/src/simulation/investment/population.rs @@ -1,8 +1,7 @@ -//! The competitive agent algorithm. +//! The population agent algorithm. //! -//! Candidate and existing assets compete in rounds: each round every option is appraised with a -//! mini dispatch optimisation, and the best option according to the agent's objective is selected. -mod coefficients; +//! Each option is appraised once against the full demand profile. Feasible options are then +//! selected in merit order, scaling their fitted profiles to the remaining demand. mod constraints; mod costs; mod metrics; @@ -16,32 +15,26 @@ use crate::model::Model; use crate::output::DebugDataWriter; use crate::process::{Process, ProcessID}; use crate::region::RegionID; +use crate::simulation::PriceMap; use crate::simulation::activity::ActivityMap; use crate::simulation::investment::Selection; use crate::simulation::investment::{AssetOptions, DemandMap}; use crate::simulation::prices::Prices; -use crate::time_slice::TimeSliceSelection; -use crate::units::{Activity, Capacity, Dimensionless, Flow, FlowPerCapacity}; -use anyhow::{Result, anyhow, ensure}; -use coefficients::calculate_coefficients_for_assets; +use crate::units::{Activity, Capacity, Dimensionless, Flow}; +use anyhow::{Result, anyhow}; use itertools::{Itertools, chain}; use log::debug; -use metrics::{ - AppraisalOutput, appraise_investment, count_equal_and_best_appraisal_outputs, - sort_and_filter_appraisal_outputs, -}; -use optimisation::solve_for_assets; +use metrics::{AppraisalOutput, count_equal_and_best_appraisal_outputs, sort_appraisal_outputs}; +use optimisation::perform_optimisation; use output::write_debug_info; use rayon::prelude::*; use std::collections::HashMap; use std::sync::Arc; -/// Run the competitive algorithm for an agent to meet its share of demand for a commodity in a -/// region. +/// Run the population algorithm for an agent to meet its share of demand for a commodity. /// -/// Committed assets are dispatched first and always selected unchanged. Existing assets of the -/// agent which produce the commodity compete with candidate assets from the agent's search space to -/// meet any remaining demand. +/// Committed assets are merit-ordered first and selected unchanged, up to their active capacity. +/// Existing assets and candidates are then merit-ordered together to meet any remaining demand. /// /// # Arguments /// @@ -52,16 +45,15 @@ use std::sync::Arc; /// * `demand` - The agent's share of demand for the commodity in the region /// * `options` - Committed assets, existing assets and processes available to the agent /// * `agent_addition_limits` - The agent's share of addition limits for candidate processes -/// * `agent_total_limits` - The agent's share of total capacity limits for processes -/// * `prices` - Commodity prices calculated in the previous dispatch +/// * `agent_total_limits` - The agent's share of total capacity limits for existing and candidate +/// assets +/// * `prices` - Market prices used to calculate input costs /// * `year` - Current milestone year /// * `debug_writer` - Optional debug writer /// /// # Returns /// -/// The assets selected (including committed assets and retained commissioned assets) along with -/// their activities from the final appraisal round, or an error. An error is also returned if -/// demand cannot be met. +/// The selected assets and their activities, or an error if demand cannot be met. #[allow(clippy::too_many_arguments)] pub fn run_agent( model: &Model, @@ -76,330 +68,417 @@ pub fn run_agent( year: u32, debug_writer: Option<&mut DebugDataWriter>, ) -> Result { - // Existing and candidate assets from which to choose + // Existing assets retain their current capacity as the maximum retention amount. Candidate + // capacity is assembled as in portfolio: discrete when the process has a tranche size and + // continuous otherwise. let opt_assets = chain( options.existing.iter().cloned(), - get_candidate_assets( - demand, - &options.processes, - region_id, - commodity, - year, - model.parameters.capacity_tranche_fraction, - ), + get_candidate_assets(&options.processes, region_id, year), ) .collect::>(); select_best_assets( model, &options.committed, - opt_assets, + &opt_assets, agent_addition_limits, agent_total_limits, commodity, agent, region_id, prices, - demand.clone(), + demand, year, debug_writer, ) } -/// Get candidate assets which produce a particular commodity from the given processes. +/// Construct candidates using the same continuous/discrete capacity setup as portfolio. +/// +/// A candidate with a tranche size starts as one tranche; the optimisation determines its +/// capacity and selection later rounds it down to a whole number of tranches. Candidates without a +/// tranche size start with zero continuous capacity. No demand-derived candidate capacity scale is +/// needed because capacity is a free variable during appraisal. +/// +/// # Arguments /// -/// Each candidate represents one investment tranche with a defined capacity. -/// - For processes with a defined `tranche_size`, the capacity is set to `tranche_size`. -/// - For processes without a defined `tranche_size`, the capacity is calculated based on the total -/// demand for the commodity and the asset's maximum annual production per unit capacity -/// (see `calculate_candidate_asset_capacity_scale`), then multiplied by -/// `capacity_tranche_fraction` to infer the tranche size. +/// * `processes` - Processes available in the agent's search space +/// * `region_id` - The region in which the candidate is located +/// * `year` - The candidate's commission year pub fn get_candidate_assets<'a>( - demand: &'a DemandMap, processes: &'a [Arc], region_id: &'a RegionID, - commodity: &'a Commodity, year: u32, - capacity_tranche_fraction: Dimensionless, ) -> impl Iterator + 'a { processes.iter().map(move |process| { - // Create asset with zero capacity, which will be updated below + let tranche_size = process.tranche_size.unwrap_or(Capacity(0.0)); let mut asset = - Asset::new_candidate(process.clone(), region_id.clone(), Capacity(0.0), year).unwrap(); - - // Set capacity of the candidate for investment appraisal - let tranche_size = if let Some(tranche_size) = asset.process().tranche_size { - // For processes with a defined tranche size, take this - tranche_size - } else { - // Otherwise, infer the tranche size from demand and the capacity_tranche_fraction. - let capacity_scale = - calculate_candidate_asset_capacity_scale(&asset, commodity, demand); - capacity_scale * capacity_tranche_fraction - }; - let asset_capacity = AssetCapacity::single(tranche_size); - asset.set_capacity(asset_capacity); + Asset::new_candidate(process.clone(), region_id.clone(), tranche_size, year).unwrap(); + if process.tranche_size.is_none() { + asset.set_capacity(AssetCapacity::continuous(Capacity(0.0))); + } asset.into() }) } -/// Calculates a characteristic capacity scale for a candidate asset. +/// Select committed assets first, then existing and candidate assets in merit order. /// -/// The returned value is the capacity that would satisfy the total annual demand assuming the asset -/// operates at its maximum annual activity for the entire year. It ignores finer-grained activity -/// constraints and temporal variations in demand. +/// Every option is appraised once against the original demand profile. Since a feasible appraisal +/// reproduces that profile exactly, selecting a fraction of its capacity supplies the same fraction +/// of every demand selection; the remaining demand therefore retains the original shape. /// -/// For processes that do not define a tranche size, this value is later scaled by -/// `capacity_tranche_fraction` to set the capacity of one candidate investment tranche. +/// Committed assets are ordered by metric among themselves and used up to active capacity. Then +/// existing assets and candidates compete together. Candidate additions are bounded by addition +/// and total limits; existing retention is bounded by the asset's capacity and total limits. /// -/// If the asset has zero maximum annual supply, zero capacity is returned. This indicates that the -/// asset is non-feasible, and will be excluded from consideration by `select_best_assets`. -fn calculate_candidate_asset_capacity_scale( - asset: &Asset, - commodity: &Commodity, - demand: &DemandMap, -) -> Capacity { - let coeff = asset.get_flow(&commodity.id).unwrap().coeff; - let max_annual_supply_per_capacity = *asset - .get_activity_per_capacity_limits_for_selection(&TimeSliceSelection::Annual) - .end() - * coeff; - if max_annual_supply_per_capacity < FlowPerCapacity::EPSILON { - return Capacity(0.0); - } - let annual_demand = demand.values().copied().sum::(); - annual_demand / max_annual_supply_per_capacity -} - -/// Print debug message if there are multiple equally good outputs -fn log_on_equal_appraisal_outputs( - outputs: &[AppraisalOutput], - agent_id: &AgentID, - commodity_id: &CommodityID, - region_id: &RegionID, -) { - if outputs.is_empty() { - return; - } - - let num_identical = count_equal_and_best_appraisal_outputs(outputs); - - if num_identical > 0 { - let asset_details = outputs[..=num_identical] - .iter() - .map(|output| { - let asset = &output.asset; - format!( - "Process ID: '{}' (State: {}{}, Commission year: {})", - asset.process_id(), - asset.state(), - asset.id().map_or_default(|id| format!(", Asset ID: {id}")), - asset.commission_year() - ) - }) - .join(", "); - debug!( - "Found equally good appraisals for Agent ID: {agent_id}, Commodity: '{commodity_id}', \ - Region: {region_id}. Options: [{asset_details}]. Selecting first option.", - ); - } -} - -/// Get the best assets for meeting demand for the given commodity +/// # Returns /// -/// `committed_assets` have fixed capacity and are always selected, unchanged. They are dispatched -/// before any of `opt_assets` are appraised. +/// The committed assets and the assets needed to meet demand, along with their selected activities. +/// Returns an error if the available profiles and limits cannot meet demand. #[allow(clippy::too_many_arguments, clippy::too_many_lines)] pub fn select_best_assets( model: &Model, committed_assets: &[AssetRef], - mut opt_assets: Vec, + opt_assets: &[AssetRef], agent_addition_limits: HashMap, agent_total_limits: HashMap, commodity: &Commodity, agent: &Agent, region_id: &RegionID, prices: &Prices, - mut demand: DemandMap, + demand: &DemandMap, year: u32, - mut debug_writer: Option<&mut DebugDataWriter>, + debug_writer: Option<&mut DebugDataWriter>, ) -> Result { - let objective_type = agent.objectives[&year]; - - // Remaining addition limits for candidate processes - // Initialised as the full agent addition limits, and reduced as candidate assets are selected - let mut remaining_agent_addition_limits = agent_addition_limits; - - // Remaining total capacity for all assets - // Initialised as full agent total limits, and reduced as each asset is selection - let mut remaining_agent_total_limits = agent_total_limits; + let has_options = !opt_assets.is_empty(); + let mut remaining_demand = demand.clone(); + let mut selected = committed_assets + .iter() + .map(|asset| (asset.clone(), asset.clone())) + .collect::>(); + let mut activities = ActivityMap::new(); + for asset in committed_assets { + // Committed assets remain selected even when they are not dispatched. Give each one + // explicit zero activities so the returned selection contains a complete activity map. + for time_slice in model.time_slice_info.iter_ids() { + activities.insert((asset.clone(), time_slice.clone()), Activity(0.0)); + } + } - // Store commissioned tranches available for retention and replace assets with single tranches - let mut available_retention_tranches = - prepare_commissioned_assets_for_retention(&mut opt_assets); + // With no material demand, committed assets are still returned unchanged; there is no profile + // to appraise and no existing asset or candidate needs to be retained or built. + if !is_any_remaining_demand( + &remaining_demand, + model.parameters.remaining_demand_absolute_tolerance, + ) { + return Ok(Selection::from_optimisation(selected, &activities)); + } - // Calculate coefficients for all asset options according to the agent's objective - let coefficients = calculate_coefficients_for_assets( + // Appraise each option against the same full profile exactly once. Committed costs are sunk, + // while candidates include annualised capital costs. + let mut committed_appraisals = appraise_assets( model, - objective_type, - &chain(committed_assets, &opt_assets).cloned().collect_vec(), + committed_assets, + commodity, &prices.market, - &prices.fallback, + demand, year, - ); - - // Iteratively select the best asset until demand is met - let mut round = 0; - let mut selected_assets: Vec = committed_assets.to_vec(); - let mut previous_solution = ActivityMap::new(); - - // Dispatch the committed assets. This must happen even if there is no demand, so that every - // selected asset has activities. - if !committed_assets.is_empty() { - (previous_solution, demand) = - solve_for_assets(model, &selected_assets, commodity, &coefficients, &demand)?; + )?; + let mut option_appraisals = + appraise_assets(model, opt_assets, commodity, &prices.market, demand, year)?; + if let Some(writer) = debug_writer { + // Write the complete appraisal sets once rather than repeating them after each selection. + let run_description = format!("{} {} {}", commodity.id, region_id, agent.id); + write_debug_info( + writer, + year, + &run_description, + &committed_appraisals, + demand, + commodity.time_slice_level, + )?; + write_debug_info( + writer, + year, + &run_description, + &option_appraisals, + demand, + commodity.time_slice_level, + )?; } - let has_options = !opt_assets.is_empty(); - while is_any_remaining_demand( - &demand, - model.parameters.remaining_demand_absolute_tolerance, - ) { - // Remove assets that would exceed the remaining limits for their processes from the options - // The addition limit applies only to candidate assets, the total limit applies to all assets - remove_assets_exceeding_agent_limits( - &mut opt_assets, - &remaining_agent_addition_limits, - true, - ); - remove_assets_exceeding_agent_limits(&mut opt_assets, &remaining_agent_total_limits, false); - if opt_assets.is_empty() { - return Err(no_options_error( - has_options, - agent, - commodity, - region_id, - year, - )); + sort_appraisal_outputs(&mut committed_appraisals); + sort_appraisal_outputs(&mut option_appraisals); + log_on_equal_appraisal_outputs(&committed_appraisals, &agent.id, &commodity.id, region_id); + log_on_equal_appraisal_outputs(&option_appraisals, &agent.id, &commodity.id, region_id); + + // Committed assets are a separate first stage. Their installed capacity is fixed, but their + // activity is scaled to the portion of the full demand profile they can cover. + for appraisal in committed_appraisals { + if !is_any_remaining_demand( + &remaining_demand, + model.parameters.remaining_demand_absolute_tolerance, + ) { + break; } - // Appraise all options in parallel: each asset's appraisal is independent (all shared - // state is read-only within this block), so we can safely use Rayon here. - // Each HiGHS solve inside `appraise_investment` is configured to use only one thread - // (via `parallel="off"`) to avoid over-subscription. - let mut outputs: Vec = opt_assets - .par_iter() - .map(|asset| -> Result> { - // Skip assets with zero capacity - if asset.total_capacity() <= Capacity(0.0) { - return Ok(None); - } - - Ok(Some(appraise_investment( - model, - asset, - commodity, - objective_type, - &coefficients[asset], - &demand, - )?)) - }) - .collect::>>()? // propagate any solver error - .into_iter() - .flatten() - .collect(); + let selected_capacity = capacity_for_remaining_demand( + appraisal.capacity, + remaining_demand_fraction(demand, &remaining_demand), + ) + .min(appraisal.asset.active_capacity()); + apply_appraisal( + &appraisal, + selected_capacity, + demand, + &mut remaining_demand, + &mut activities, + ); + debug!( + "Selected committed asset '{}' (capacity used: {selected_capacity})", + appraisal.asset.process_id() + ); + } - // Save appraisal results - if let Some(writer) = debug_writer.as_deref_mut() { - write_debug_info( - writer, - year, - &format!("{} {} round {}", commodity.id, agent.id, round), - &outputs, - &demand, - commodity.time_slice_level, - )?; + // Candidates and existing assets now compete by the same cost metric. Limits are applied to + // selected capacity, not to the full-demand capacity used for appraisal. + let mut remaining_addition_limits = agent_addition_limits; + let mut remaining_total_limits = agent_total_limits; + for appraisal in option_appraisals { + if !is_any_remaining_demand( + &remaining_demand, + model.parameters.remaining_demand_absolute_tolerance, + ) { + break; } - // Sort by investment priority and discard non-feasible options - let num_nonfeasible = sort_and_filter_appraisal_outputs(&mut outputs); - - ensure!( - !outputs.is_empty(), - "Investment appraisal failed with unmet demand for commodity '{}', region \ - '{region_id}', year {year}, agent '{}'. {num_nonfeasible} non-feasible investments \ - were not considered.", - commodity.id, - agent.id + let requested_capacity = capacity_for_remaining_demand( + appraisal.capacity, + remaining_demand_fraction(demand, &remaining_demand), ); + let mut capacity_limit = requested_capacity; + if !appraisal.asset.is_candidate() { + // Existing assets may be retained or mothballed, but never expanded. + capacity_limit = capacity_limit.min(appraisal.asset.total_capacity()); + } + if let Some(limit) = remaining_total_limits.get(appraisal.asset.process_id()) { + capacity_limit = capacity_limit.min(*limit); + } + if appraisal.asset.is_candidate() + && let Some(limit) = remaining_addition_limits.get(appraisal.asset.process_id()) + { + capacity_limit = capacity_limit.min(*limit); + } - // Warn if there are multiple equally good assets - log_on_equal_appraisal_outputs(&outputs, &agent.id, &commodity.id, region_id); - - let best_output = outputs.into_iter().next().unwrap(); + // A tranche-sized asset must not be rounded up past the demand or any remaining limit. + let selected_capacity = + round_capacity_down(appraisal.asset.capacity(), capacity_limit).total_capacity(); + if selected_capacity <= Capacity(0.0) { + continue; + } - // Log the selected asset - debug!( - "Selected {} asset '{}' (capacity: {})", - best_output.asset.state(), - best_output.asset.process_id(), - best_output.asset.total_capacity() + let selected_asset = selected_asset(&appraisal.asset, selected_capacity, agent); + selected.push((appraisal.asset.clone(), selected_asset)); + // The fitted profile is linear in capacity, so use the selected capacity to update both + // activities and every selection of the remaining demand map. + apply_appraisal( + &appraisal, + selected_capacity, + demand, + &mut remaining_demand, + &mut activities, ); - // Update the remaining selection state - update_selection_state( - &best_output.asset, - &mut opt_assets, - &mut remaining_agent_addition_limits, - &mut remaining_agent_total_limits, - &mut available_retention_tranches, + subtract_capacity_limit( + appraisal.asset.process_id(), + selected_capacity, + &mut remaining_total_limits, + ); + if appraisal.asset.is_candidate() { + subtract_capacity_limit( + appraisal.asset.process_id(), + selected_capacity, + &mut remaining_addition_limits, + ); + } + debug!( + "Selected {} asset '{}' (capacity: {selected_capacity})", + appraisal.asset.state(), + appraisal.asset.process_id() ); + } - for (time_slice, activity) in &best_output.activity { - *previous_solution - .entry((best_output.asset.clone(), time_slice.clone())) - .or_insert(Activity(0.0)) += *activity; + if is_any_remaining_demand( + &remaining_demand, + model.parameters.remaining_demand_absolute_tolerance, + ) { + if !has_options { + return Err(no_options_error(false, agent, commodity, region_id, year)); } + return Err(no_options_error( + has_options, + agent, + commodity, + region_id, + year, + )); + } + + Ok(Selection::from_optimisation(selected, &activities)) +} - // Record the selected asset - record_asset_selection(best_output.asset.clone(), &mut selected_assets); +fn appraise_assets( + model: &Model, + assets: &[AssetRef], + commodity: &Commodity, + market_prices: &PriceMap, + demand: &DemandMap, + year: u32, +) -> Result> { + // Appraisals are independent and can run in parallel. Infeasible profiles are expected and + // omitted; configuration and other solver errors propagate. + let results = assets + .par_iter() + .map(|asset| -> Result> { + let Some(results) = + perform_optimisation(model, asset, commodity, market_prices, year, demand)? + else { + return Ok(None); + }; + if results.capacity <= Capacity(0.0) { + return Ok(None); + } + Ok(Some(AppraisalOutput::new( + asset.clone(), + results.capacity, + &results.activity, + results.metric, + ))) + }) + .collect::>>()?; + Ok(results.into_iter().flatten().collect()) +} - demand = best_output.unmet_demand; - round += 1; +fn selected_asset(asset: &AssetRef, capacity: Capacity, agent: &Agent) -> AssetRef { + // Retained commissioned assets are unmothballed before reducing their capacity. Candidates are + // marked ready for investment before their selected tranche count is assigned. + let mut selected_asset = asset.clone().with_no_mothballed_capacity(); + let capacity = round_capacity_down(asset.capacity(), capacity); + let inner = selected_asset.make_mut(); + if inner.is_candidate() { + inner.select_candidate_for_investment(agent.id.clone()); } + inner.set_capacity(capacity); + selected_asset +} - Ok(finalise_selection( - selected_assets, - agent, - &previous_solution, - )) +fn apply_appraisal( + appraisal: &AppraisalOutput, + capacity: Capacity, + original_demand: &DemandMap, + remaining_demand: &mut DemandMap, + activities: &mut ActivityMap, +) { + if capacity <= Capacity(0.0) { + return; + } + // The appraisal matches original demand at `appraisal.capacity`; scaling capacity scales its + // activity and supply profile by the same factor. + let fraction = Dimensionless((capacity / appraisal.capacity).value()); + for (time_slice, activity_per_capacity) in &appraisal.activity_per_capacity { + *activities + .entry((appraisal.asset.clone(), time_slice.clone())) + .or_insert(Activity(0.0)) += *activity_per_capacity * capacity; + } + for (selection, original_flow) in original_demand { + let flow = (remaining_demand[selection] - *original_flow * fraction).max(Flow(0.0)); + remaining_demand.insert(selection.clone(), flow); + } +} + +/// Scale the capacity required for the full profile to the current residual demand. +fn capacity_for_remaining_demand( + full_demand_capacity: Capacity, + remaining_fraction: Dimensionless, +) -> Capacity { + full_demand_capacity * remaining_fraction } -/// Convert the selected assets to the final selection +/// Calculate the residual demand as a fraction of the original profile. /// -/// Candidate assets are converted to Ready, and at this point we also assign the agent ID to the -/// asset. The solution contains the activities recorded for committed and selected assets. -fn finalise_selection( - selected_assets: Vec, - agent: &Agent, - solution: &ActivityMap, -) -> Selection { - let selected = selected_assets - .into_iter() - .map(|asset| { - let mut selected_asset = asset.clone(); - if selected_asset.is_candidate() { - selected_asset - .make_mut() - .select_candidate_for_investment(agent.id.clone()); - } - (asset, selected_asset) - }) - .collect(); +/// Every selected option supplies a scalar multiple of the original profile, so the ratio of +/// total flows is also the ratio for each time-slice selection. +fn remaining_demand_fraction(original: &DemandMap, remaining: &DemandMap) -> Dimensionless { + let original_total: Flow = original.values().copied().sum(); + if original_total <= Flow(0.0) { + return Dimensionless(0.0); + } + let remaining_total: Flow = remaining.values().copied().sum(); + (remaining_total / original_total).min(Dimensionless(1.0)) +} + +/// Represent a selected capacity using the asset's capacity type, rounding discrete capacity down. +/// +/// The returned capacity never exceeds the amount available from demand or investment limits. +fn round_capacity_down(capacity_type: AssetCapacity, capacity: Capacity) -> AssetCapacity { + match capacity_type { + AssetCapacity::Continuous(_) => AssetCapacity::continuous(capacity.max(Capacity(0.0))), + AssetCapacity::Discrete { tranche_size, .. } if tranche_size > Capacity(0.0) => { + #[allow(clippy::cast_sign_loss, clippy::cast_possible_truncation)] + let num_tranches = (capacity / tranche_size).value().floor() as u32; + AssetCapacity::discrete(num_tranches, tranche_size) + } + AssetCapacity::Discrete { tranche_size, .. } => AssetCapacity::discrete(0, tranche_size), + } +} + +/// Reduce a process limit by selected capacity, if that process has a configured limit. +fn subtract_capacity_limit( + process_id: &ProcessID, + capacity: Capacity, + limits: &mut HashMap, +) { + if let Some(limit) = limits.get_mut(process_id) { + *limit = (*limit - capacity).max(Capacity(0.0)); + } +} + +/// Check whether any demand selection remains above the model's absolute tolerance. +fn is_any_remaining_demand(demand: &DemandMap, absolute_tolerance: Flow) -> bool { + demand.values().any(|flow| *flow > absolute_tolerance) +} + +/// Log when multiple options share the same best metric and fallback ordering. +fn log_on_equal_appraisal_outputs( + outputs: &[AppraisalOutput], + agent_id: &AgentID, + commodity_id: &CommodityID, + region_id: &RegionID, +) { + let num_identical = count_equal_and_best_appraisal_outputs(outputs); + if num_identical == 0 { + return; + } - Selection::from_optimisation(selected, solution) + let asset_details = outputs[..=num_identical] + .iter() + .map(|output| { + let asset = &output.asset; + format!( + "Process ID: '{}' (State: {}{}, Commission year: {})", + asset.process_id(), + asset.state(), + asset.id().map_or_default(|id| format!(", Asset ID: {id}")), + asset.commission_year() + ) + }) + .join(", "); + debug!( + "Found equally good appraisals for Agent ID: {agent_id}, Commodity: '{commodity_id}', \ + Region: {region_id}. Options: [{asset_details}]. Selecting first option.", + ); } -/// Create the error for when demand remains but there are no asset options left to appraise +/// Create the error returned when available options and limits cannot meet demand. fn no_options_error( has_options: bool, agent: &Agent, @@ -424,284 +503,124 @@ fn no_options_error( } } -/// Prepare existing assets for reappraisal. -/// -/// Assets are replaced in `assets` with an asset representing a single tranche, as they are -/// appraised one tranche at a time. Returns a map from the asset to its original number of tranches. -fn prepare_commissioned_assets_for_retention(assets: &mut [AssetRef]) -> HashMap { - let mut available_retention_tranches = HashMap::new(); - - for asset in assets.iter_mut().filter(|asset| asset.is_commissioned()) { - let num_tranches = asset.num_tranches(); - - // Replace with single tranche as we appraise one tranche at a time - *asset = asset.clone().as_single_tranche(); - - // Store remaining tranches - available_retention_tranches.insert(asset.clone(), num_tranches); - } - - available_retention_tranches -} - -/// Check whether there is any remaining demand that is unmet in any time slice -fn is_any_remaining_demand(demand: &DemandMap, absolute_tolerance: Flow) -> bool { - demand.values().any(|flow| *flow > absolute_tolerance) -} - -/// Remove assets that exceed the provided process limits for one complete tranche. -fn remove_assets_exceeding_agent_limits( - opt_assets: &mut Vec, - remaining_agent_limits: &HashMap, - only_candidates: bool, -) { - opt_assets.retain(|asset| { - (only_candidates && !asset.is_candidate()) - || remaining_agent_limits - .get(asset.process_id()) - .is_none_or(|limit| *limit >= asset.total_capacity()) - }); -} - -// Update remaining process capacity limit with the capacity of a selected asset -fn subtract_capacity_from_remaining_limit( - best_asset: &AssetRef, - remaining_agent_limits: &mut HashMap, -) { - if let Some(remaining_capacity) = remaining_agent_limits.get_mut(best_asset.process_id()) { - *remaining_capacity -= best_asset.total_capacity(); - assert!( - *remaining_capacity >= Capacity(0.0), - "Remaining Capacity has fallen below zero" - ); - } -} - -/// Update the remaining investment options and selection state. -/// -/// If the asset is a candidate, its one-tranche capacity is subtracted from -/// `remaining_agent_addition_limits` (if applicable) to ensure that process addition limits are not -/// exceeded. If the asset is commissioned, one tranche is subtracted from -/// `available_retention_tranches` to ensure that retention does not invent new capacity. -/// -/// # Arguments -/// -/// * `best_asset` - The asset that has been selected as the best option in this round -/// * `opt_assets` - The list of remaining asset options to be considered in future rounds -/// * `remaining_agent_addition_limits` - The remaining agent addition limits for processes -/// * `remaining_agent_total_limit` - The remaining capacity for processes -/// * `available_retention_tranches` - The commissioned tranches available for retention -fn update_selection_state( - best_asset: &AssetRef, - opt_assets: &mut Vec, - remaining_agent_addition_limits: &mut HashMap, - remaining_agent_total_limits: &mut HashMap, - available_retention_tranches: &mut HashMap, -) { - // Subtract asset capacity from the total capacity limit, if applicable. - subtract_capacity_from_remaining_limit(best_asset, remaining_agent_total_limits); - - // Update the remaining agent addition limit for the selected asset, if applicable, and remove it - // from the options if the limit is exhausted. - if best_asset.is_candidate() { - // Candidate assets: remove capacity from the investment limit, if applicable. - subtract_capacity_from_remaining_limit(best_asset, remaining_agent_addition_limits); - } else { - // Commissioned assets: we've appraised a single tranche, so remove one tranche from the - // available retention count for this asset. - let remaining = available_retention_tranches.get_mut(best_asset).unwrap(); - *remaining = remaining.saturating_sub(1); - - // If all tranches have been selected, remove the asset from the investment options. - if *remaining == 0 { - let old_idx = opt_assets - .iter() - .position(|asset| *asset == *best_asset) - .unwrap(); - opt_assets.swap_remove(old_idx); - available_retention_tranches.remove(best_asset); - } - } -} - -/// Record a selected asset. Candidate selections represent one tranche; repeated selections of the -/// same candidate increase the resulting asset's number of tranches while preserving its tranche -/// size. -/// -/// # Arguments -/// -/// * `best_asset` - The asset that has been selected as the best option in this round -/// * `best_assets` - The list of assets that have been selected so far -fn record_asset_selection(best_asset: AssetRef, best_assets: &mut Vec) { - assert!( - best_asset.is_commissioned() || best_asset.is_candidate(), - "Invalid asset type" - ); - - // Add the selected asset to the list of best assets, or add one tranche if it's already there. - if let Some(existing_asset) = best_assets.iter_mut().find(|asset| **asset == best_asset) { - // If the asset is already selected, add the additional required tranche - existing_asset - .make_mut() - .increase_capacity(best_asset.capacity()); - } else { - // Otherwise add it to the list of best assets. Selected assets are unmothballed. - best_assets.push(best_asset.with_no_mothballed_capacity()); - } -} - #[cfg(test)] mod tests { use super::*; - use crate::fixture::{ - agent_id, asset, process, process_activity_limits_map, process_flows_map, svd_commodity, - time_slice, time_slice_info, - }; - use crate::process::{ActivityLimits, FlowType, Process, ProcessFlow}; - use crate::time_slice::{TimeSliceID, TimeSliceInfo}; - use crate::units::{FlowPerActivity, MoneyPerFlow}; - use indexmap::indexmap; - use rstest::{fixture, rstest}; - use std::sync::Arc; + use crate::agent::AgentID; + use crate::commodity::CommodityID; + use crate::fixture::build_patched_simple_tempdir; + use crate::fixture::process; + use crate::input::load_model; + use crate::simulation::investment::AssetOptions; + use crate::simulation::prices::Prices; + use crate::units::Activity; + use float_cmp::assert_approx_eq; + use rstest::rstest; #[rstest] - #[case(Flow(10.0), Dimensionless(1.0), Capacity(10.0))] // normal: demand / (limit * coeff) = 10 / (1 * 1) = 10 - #[case(Flow(0.0), Dimensionless(1.0), Capacity(0.0))] // zero demand → zero capacity - #[case(Flow(10.0), Dimensionless(0.5), Capacity(20.0))] // activity limit < 1: 10 / (0.5 * 1) = 20 - #[case(Flow(10.0), Dimensionless(0.0), Capacity(0.0))] // activity limit = 0 → zero capacity - fn calculate_asset_capacity_scale_works( - time_slice: TimeSliceID, - time_slice_info: TimeSliceInfo, - svd_commodity: Commodity, + #[case(None, AssetCapacity::continuous(Capacity(0.0)))] + #[case(Some(Capacity(3.0)), AssetCapacity::single(Capacity(3.0)))] + fn candidate_assets_use_portfolio_capacity_setup( mut process: Process, - #[case] demand_value: Flow, - #[case] activity_limit: Dimensionless, - #[case] expected: Capacity, + #[case] tranche_size: Option, + #[case] expected_capacity: AssetCapacity, ) { - let commodity_rc = Arc::new(svd_commodity); - let process_flow = ProcessFlow { - commodity: Arc::clone(&commodity_rc), - coeff: FlowPerActivity(1.0), - kind: FlowType::Fixed, - cost: MoneyPerFlow(0.0), - }; - process.flows = process_flows_map( - process.regions.clone(), - Arc::new(indexmap! { commodity_rc.id.clone() => process_flow }), - ); - - let mut limits = ActivityLimits::new_with_full_availability(&time_slice_info); - limits.add_time_slice_limit(time_slice.clone(), Dimensionless(0.0)..=activity_limit); - process.activity_limits = process_activity_limits_map(process.regions.clone(), limits); + process.tranche_size = tranche_size; + let candidates = get_candidate_assets(&[Arc::new(process)], &RegionID::from("GBR"), 2020) + .collect::>(); - let asset = asset(process); - let demand = indexmap! { TimeSliceSelection::Single(time_slice)=> demand_value }; - assert_eq!( - calculate_candidate_asset_capacity_scale(&asset, &commodity_rc, &demand), - expected - ); + assert_eq!(candidates.len(), 1); + assert_eq!(candidates[0].capacity(), expected_capacity); } #[rstest] - fn subtract_capacity_from_remaining_limit_works(asset: Asset) { - let mut remaining_agent_limits = - HashMap::from([(asset.process_id().clone(), Capacity(10.0))]); - subtract_capacity_from_remaining_limit( - &AssetRef::from(asset.clone()), - &mut remaining_agent_limits, - ); - - assert_eq!( - remaining_agent_limits[asset.process_id()].clone(), - Capacity(8.0) - ); - } - - #[fixture] - fn commissioned_asset(agent_id: AgentID, asset: Asset) -> Asset { - Asset::new_commissioned( - agent_id, - Arc::new(asset.process().clone()), - asset.region_id().clone(), - asset.capacity(), - asset.commission_year(), - ) - .unwrap() - } - - #[fixture] - fn candidate_asset(asset: Asset) -> Asset { - Asset::new_candidate( - Arc::new(asset.process().clone()), - asset.region_id().clone(), - asset.total_capacity(), - asset.commission_year(), - ) - .unwrap() - } - - #[rstest] - fn remove_assets_exceeding_agent_limits_works( - commissioned_asset: Asset, - candidate_asset: Asset, + #[case( + AssetCapacity::continuous(Capacity(5.0)), + Capacity(2.5), + AssetCapacity::continuous(Capacity(2.5)) + )] + #[case( + AssetCapacity::single(Capacity(2.0)), + Capacity(5.9), + AssetCapacity::discrete(2, Capacity(2.0)) + )] + #[case( + AssetCapacity::single(Capacity(2.0)), + Capacity(1.9), + AssetCapacity::discrete(0, Capacity(2.0)) + )] + fn capacity_is_rounded_down( + #[case] capacity_type: AssetCapacity, + #[case] capacity: Capacity, + #[case] expected: AssetCapacity, ) { - let mut opt_assets = vec![ - commissioned_asset.clone().into(), - candidate_asset.clone().into(), - ]; - let limits = HashMap::from([(commissioned_asset.process_id().clone(), Capacity(1.0))]); - - // Check only the candidate asset is removed when `only_candidates` is true - remove_assets_exceeding_agent_limits(&mut opt_assets, &limits, true); - assert_eq!(opt_assets.len(), 1); - assert_eq!(opt_assets[0], commissioned_asset.clone().into()); - - // Check all assets are removed when `only_candidates` is false - opt_assets.push(candidate_asset.clone().into()); - remove_assets_exceeding_agent_limits(&mut opt_assets, &limits, false); - assert_eq!(opt_assets, []); + assert_eq!(round_capacity_down(capacity_type, capacity), expected); } - #[rstest] - #[case(false)] - #[case(true)] - fn update_selection_state_works( - commissioned_asset: Asset, - candidate_asset: Asset, - #[case] commissioned: bool, - ) { - let best_asset: AssetRef = if commissioned { - commissioned_asset.clone().into() - } else { - candidate_asset.clone().into() + #[test] + fn run_agent_supplies_the_full_demand_profile() { + let model_dir = build_patched_simple_tempdir(Vec::new()); + let model = load_model(model_dir.path()).unwrap(); + let year = model.parameters.milestone_years[0]; + let agent = &model.agents[&AgentID::from("A0_RES")]; + let commodity = &model.commodities[&CommodityID::from("RSHEAT")]; + let region_id = RegionID::from("GBR"); + let process = agent + .iter_search_space(®ion_id, &commodity.id, year) + .next() + .unwrap() + .clone(); + let candidate = get_candidate_assets(std::slice::from_ref(&process), ®ion_id, year) + .next() + .unwrap(); + let flow_coefficient = candidate.get_flow(&commodity.id).unwrap().coeff; + let demand: DemandMap = model + .time_slice_info + .iter_selections_at_level(commodity.time_slice_level) + .map(|selection| { + let maximum_activity = *candidate + .get_activity_per_capacity_limits_for_selection(&selection) + .end(); + ( + selection, + maximum_activity * Capacity(1.0) * flow_coefficient, + ) + }) + .collect(); + let options = AssetOptions { + processes: vec![process], + ..AssetOptions::default() }; - let mut opt_assets = vec![best_asset.clone()]; - let mut addition_limits = HashMap::from([(best_asset.process_id().clone(), Capacity(2.0))]); - let mut total_limits = HashMap::from([(best_asset.process_id().clone(), Capacity(2.0))]); - let mut retention_tranches = HashMap::from([(best_asset.clone(), 1)]); - - update_selection_state( - &best_asset, - &mut opt_assets, - &mut addition_limits, - &mut total_limits, - &mut retention_tranches, - ); - - if commissioned { - // Expect total_limits to reduce and retention_tranches to be removed - assert_eq!(total_limits[best_asset.process_id()], Capacity(0.0)); - assert!(!retention_tranches.contains_key(&best_asset)); - - // Expect addition_limits to remain unchanged - assert_eq!(addition_limits[best_asset.process_id()], Capacity(2.0)); - } else { - // Expect total_limits and addition_limits to reduce - assert_eq!(total_limits[best_asset.process_id()], Capacity(0.0)); - assert_eq!(addition_limits[best_asset.process_id()], Capacity(0.0)); - - // Expect retention_tranches to remain unchanged - assert_eq!(retention_tranches[&best_asset], 1); + let selection = run_agent( + &model, + agent, + commodity, + ®ion_id, + &demand, + &options, + HashMap::new(), + HashMap::new(), + &Prices::default(), + year, + None, + ) + .unwrap(); + + assert_eq!(selection.assets.len(), 1); + let selected_asset = &selection.assets[0]; + for (time_selection, required_flow) in &demand { + let supplied_flow: Flow = time_selection + .iter(&model.time_slice_info) + .map(|(time_slice, _)| { + selection + .activity + .get(&(selected_asset.clone(), time_slice.clone())) + .copied() + .unwrap_or(Activity(0.0)) + * flow_coefficient + }) + .sum(); + assert_approx_eq!(f64, supplied_flow.value(), required_flow.value()); } } } diff --git a/src/simulation/investment/population/coefficients.rs b/src/simulation/investment/population/coefficients.rs deleted file mode 100644 index b9a0ad8bd..000000000 --- a/src/simulation/investment/population/coefficients.rs +++ /dev/null @@ -1,109 +0,0 @@ -//! Calculation of cost coefficients for investment tools. -use crate::agent::ObjectiveType; -use crate::asset::AssetRef; -use crate::model::Model; -use crate::simulation::PriceMap; -use crate::time_slice::{TimeSliceID, TimeSliceInfo}; -use crate::units::{MoneyPerActivity, MoneyPerFlow}; -use indexmap::IndexMap; -use std::collections::HashMap; -use std::sync::Arc; - -/// Per-time-slice cost coefficients for an asset. -/// -/// These coefficients are calculated according to the agent's `ObjectiveType` and are used by the -/// investment appraisal routines. Both the activity coefficients used in the appraisal optimisation -/// and the costs used to calculate the appraisal metric are derived from market prices. -#[derive(Clone)] -pub struct ObjectiveCoefficients { - /// Net revenue per unit of activity, including fallback revenue and epsilon, in each time slice - pub activity_coefficients: IndexMap, - /// Costs per unit of activity for the appraisal metric, excluding fallback revenue and epsilon - pub metric_costs: IndexMap, -} - -/// Calculates cost coefficients for a set of assets for a given objective type. -/// -/// Returns a map from each asset to its [`ObjectiveCoefficients`], which holds a per-time-slice -/// activity coefficient and metric cost. -/// -/// Activity coefficients are revenue from flows (including the primary output) minus operating -/// cost, calculated using market prices, plus the primary output's fallback revenue. A small positive -/// epsilon is added to each activity coefficient so that assets with near-zero net value still appear -/// in dispatch. -/// -/// Metric costs are operating cost minus flow revenue at market prices. NPV includes all flows, -/// whereas LCOX excludes revenue from the primary output (commodity of interest). Neither includes -/// fallback revenue or epsilon. -pub fn calculate_coefficients_for_assets( - model: &Model, - objective_type: ObjectiveType, - assets: &[AssetRef], - market_prices: &PriceMap, - fallback_prices: &PriceMap, - year: u32, -) -> HashMap> { - assets - .iter() - .map(|asset| { - let coefficient = calculate_coefficients_for_asset( - asset, - objective_type, - &model.time_slice_info, - market_prices, - fallback_prices, - year, - ); - (asset.clone(), Arc::new(coefficient)) - }) - .collect() -} - -/// Calculates cost coefficients for a single asset -fn calculate_coefficients_for_asset( - asset: &AssetRef, - objective_type: ObjectiveType, - time_slice_info: &TimeSliceInfo, - market_prices: &PriceMap, - fallback_prices: &PriceMap, - year: u32, -) -> ObjectiveCoefficients { - // Small constant added to each activity coefficient to ensure break-even/slightly negative - // assets are still dispatched - const EPSILON_ACTIVITY_COEFFICIENT: MoneyPerActivity = MoneyPerActivity(f64::EPSILON * 100.0); - - let mut activity_coefficients = IndexMap::new(); - let mut metric_costs = IndexMap::new(); - let primary_output_flow = asset.primary_output().unwrap(); - let asset_region = asset.region_id(); - for time_slice in time_slice_info.iter_ids() { - // Get the operating cost of the asset. This includes the variable operating cost, levies and - // flow costs, but excludes costs/revenues from commodity consumption/production. - let operating_cost = asset.get_operating_cost(year, time_slice); - let net_revenue = asset.get_revenue_from_flows(market_prices, time_slice) - operating_cost; - - let fallback_revenue = fallback_prices - .get(&primary_output_flow.commodity.id, asset_region, time_slice) - .unwrap_or(MoneyPerFlow(0.0)) - * primary_output_flow.coeff; - - activity_coefficients.insert( - time_slice.clone(), - fallback_revenue + net_revenue + EPSILON_ACTIVITY_COEFFICIENT, - ); - - let metric_cost = match objective_type { - ObjectiveType::LevelisedCostOfX => { - operating_cost - - asset.get_revenue_from_flows_excluding_primary(market_prices, time_slice) - } - ObjectiveType::NetPresentValue => -net_revenue, - }; - metric_costs.insert(time_slice.clone(), metric_cost); - } - - ObjectiveCoefficients { - activity_coefficients, - metric_costs, - } -} diff --git a/src/simulation/investment/population/constraints.rs b/src/simulation/investment/population/constraints.rs index 924df5bdc..aede00681 100644 --- a/src/simulation/investment/population/constraints.rs +++ b/src/simulation/investment/population/constraints.rs @@ -1,4 +1,4 @@ -//! Constraints for the optimisation problem. +//! Constraints for fitting an asset to the demand profile. use super::optimisation::Variable; use crate::asset::AssetRef; use crate::commodity::Commodity; @@ -9,38 +9,37 @@ use crate::units::{MoneyPerCapacityPerYear, Year}; use highs::RowProblem as Problem; use indexmap::IndexMap; -/// Adds activity constraints to the problem. +/// Constrain activity to the asset's availability limits, scaled by the capacity variable. /// -/// Constrains the activity variables to be within the asset's activity limits. -/// -/// The asset's per-capacity activity limits are scaled by the asset's capacity to give -/// absolute bounds, and a single bounded constraint is added per time-slice selection covering the -/// sum of activity in that selection. +/// For each time-slice selection, the sum of activity is bounded below and above by the asset's +/// per-capacity activity limits multiplied by the fitted capacity. pub fn add_activity_constraints( problem: &mut Problem, asset: &AssetRef, activity_vars: &IndexMap, + capacity_var: Variable, time_slice_info: &TimeSliceInfo, ) { - for (ts_selection, limits) in asset.iter_activity_limits() { - let limits = limits.start().value()..=limits.end().value(); - - // Collect activity terms for the time slices in this selection - let terms = ts_selection + for (selection, limits) in asset.iter_activity_per_capacity_limits() { + let activity_terms = selection .iter(time_slice_info) .map(|(time_slice, _)| (activity_vars[time_slice], 1.0)) .collect::>(); - // Constraint: sum of activities in selection within limits - problem.add_row(limits, &terms); + let mut upper_terms = activity_terms.clone(); + upper_terms.push((capacity_var, -limits.end().value())); + problem.add_row(..=0.0, upper_terms); + + let mut lower_terms = activity_terms; + lower_terms.push((capacity_var, -limits.start().value())); + problem.add_row(0.0.., lower_terms); } } -/// Adds demand constraints to the problem. +/// Require supply to equal demand at every selection of the commodity's balance level. /// -/// Constrains supply to be less than or equal to demand. One inequality constraint is added per -/// time-slice selection at the commodity's balance level, capping the sum of activity (scaled by -/// flow coefficients) to the total demand for that selection. +/// A separate equality is added for each selection, so a feasible option reproduces the demand +/// profile rather than merely meeting its total annual volume. pub fn add_demand_constraints( problem: &mut Problem, asset: &AssetRef, @@ -49,39 +48,38 @@ pub fn add_demand_constraints( demand: &DemandMap, activity_vars: &IndexMap, ) { - let flow_coeff = asset.get_flow(&commodity.id).unwrap().coeff; - for ts_selection in time_slice_info.iter_selections_at_level(commodity.time_slice_level) { - let demand_for_ts_selection = demand[&ts_selection]; - let terms: Vec<_> = ts_selection + let flow_coefficient = asset.get_flow(&commodity.id).unwrap().coeff.value(); + for selection in time_slice_info.iter_selections_at_level(commodity.time_slice_level) { + let terms = selection .iter(time_slice_info) - .map(|(time_slice, _)| (activity_vars[time_slice], flow_coeff.value())) - .collect(); - problem.add_row(0.0..=demand_for_ts_selection.value(), terms); + .map(|(time_slice, _)| (activity_vars[time_slice], flow_coefficient)) + .collect::>(); + let required = demand[&selection].value(); + problem.add_row(required..=required, terms); } } -/// Add seasonal and annual utilisation peak constraints to the problem. +/// Add seasonal and annual peak-utilisation cost variables used by portfolio. /// -/// This is almost identical to equivalent constraints in the full-system dispatch, but here we -/// make the penalties negative as this is a maximise optimisation (whereas dispatch is a minimise -/// optimisation). +/// Peak variables carry their configured penalty in the minimisation objective and are constrained +/// to be at least the capacity required by activity in each time slice. Annual peak is constrained +/// to be at least each seasonal peak. If neither penalty is configured, no peak variables or rows +/// are needed. pub fn add_utilisation_peak_constraints( problem: &mut Problem, model: &Model, asset: &AssetRef, activity_vars: &IndexMap, ) { - let has_seasonal_penalty = + let seasonal_penalty = model.parameters.seasonal_utilisation_penalty > MoneyPerCapacityPerYear(0.0); - let has_annual_penalty = - model.parameters.annual_utilisation_penalty > MoneyPerCapacityPerYear(0.0); - - // If neither penalties are applied, we don't need to add any variables and constraints - if !has_seasonal_penalty && !has_annual_penalty { + let annual_penalty = model.parameters.annual_utilisation_penalty > MoneyPerCapacityPerYear(0.0); + if !seasonal_penalty && !annual_penalty { return; } - // So long as either penalty is applied, we need to add seasonal peak variables and constraints + // Annual peak is linked through the seasonal peaks, so seasonal variables are also needed when + // only the annual penalty is configured. let seasonal_peak_vars = add_seasonal_peak_variables(problem, model); add_seasonal_peak_constraints( problem, @@ -90,9 +88,7 @@ pub fn add_utilisation_peak_constraints( &model.time_slice_info, &seasonal_peak_vars, ); - - // If the annual penalty is applied, we also need to add an annual peak variable and constraints - if has_annual_penalty { + if annual_penalty { let annual_peak_var = add_annual_peak_variable(problem, model); add_annual_peak_constraints( problem, @@ -103,67 +99,59 @@ pub fn add_utilisation_peak_constraints( } } -/// Add seasonal peak variables to the problem. -fn add_seasonal_peak_variables( - problem: &mut Problem, - model: &Model, -) -> IndexMap { - let mut seasonal_peak_vars = IndexMap::new(); - for (season, duration) in &model.time_slice_info.seasons { - // Scale penalty by season duration - // We make the penalty negative as we're doing a max optimisation - let col_factor = -(model.parameters.seasonal_utilisation_penalty * *duration); - let variable = problem.add_column(col_factor.value(), 0.0..); - seasonal_peak_vars.insert(season.clone(), variable); - } - seasonal_peak_vars +/// Add one non-negative seasonal peak-capacity variable per season. +fn add_seasonal_peak_variables(problem: &mut Problem, model: &Model) -> IndexMap { + model + .time_slice_info + .seasons + .iter() + .map(|(season, duration)| { + let cost = model.parameters.seasonal_utilisation_penalty * *duration; + (season.clone(), problem.add_column(cost.value(), 0.0..)) + }) + .collect() } -/// Add annual peak variable to the problem. -fn add_annual_peak_variable(problem: &mut Problem, model: &Model) -> highs::Col { - // Penalty is applied over the whole year, so scale by 1 year - // We make the penalty negative as we're doing a max optimisation - let col_factor = -(model.parameters.annual_utilisation_penalty * Year(1.0)); - problem.add_column(col_factor.value(), 0.0..) +/// Add a non-negative annual peak-capacity variable. +fn add_annual_peak_variable(problem: &mut Problem, model: &Model) -> Variable { + let cost = model.parameters.annual_utilisation_penalty * Year(1.0); + problem.add_column(cost.value(), 0.0..) } -/// Add constraints linking seasonal peak variables to activity variables for each (asset, season) pair. +/// Link each seasonal peak to the capacity required by activity in each of its time slices. fn add_seasonal_peak_constraints( problem: &mut Problem, asset: &AssetRef, activity_vars: &IndexMap, time_slice_info: &TimeSliceInfo, - seasonal_peak_vars: &IndexMap, + seasonal_peak_vars: &IndexMap, ) { let activity_per_capacity = asset.process().capacity_to_activity; - for (season, &peak_variable) in seasonal_peak_vars { - for (time_slice, ts_length) in + for (season, &peak_var) in seasonal_peak_vars { + for (time_slice, duration) in TimeSliceSelection::Season(season.clone()).iter(time_slice_info) { - let time_slice_fraction = ts_length / Year(1.0); - let activity_per_capacity_in_time_slice = activity_per_capacity * time_slice_fraction; - let capacity_required_per_activity = 1.0 / activity_per_capacity_in_time_slice.value(); - - // One unit of capacity supports `activity_per_capacity_in_time_slice` activity in - // this time slice. The peak variable therefore measures the capacity required by - // the activity in the time slice. + // Convert the process's annual activity-per-capacity rate to the duration of this + // time slice. The peak variable then bounds the capacity needed for its activity. + let activity_per_capacity_in_slice = activity_per_capacity * (duration / Year(1.0)); + let capacity_per_activity = 1.0 / activity_per_capacity_in_slice.value(); problem.add_row( 0.0.., [ - (peak_variable, 1.0), - (activity_vars[time_slice], -capacity_required_per_activity), + (peak_var, 1.0), + (activity_vars[time_slice], -capacity_per_activity), ], ); } } } -/// Add constraints linking seasonal peak variables to annual peak variables for each asset. +/// Constrain the annual peak to be at least every seasonal peak. fn add_annual_peak_constraints( problem: &mut Problem, time_slice_info: &TimeSliceInfo, - annual_peak_var: highs::Col, - seasonal_peak_vars: &IndexMap, + annual_peak_var: Variable, + seasonal_peak_vars: &IndexMap, ) { for season in time_slice_info.seasons.keys() { problem.add_row( diff --git a/src/simulation/investment/population/metrics.rs b/src/simulation/investment/population/metrics.rs index dc3552f30..ec2de86cf 100644 --- a/src/simulation/investment/population/metrics.rs +++ b/src/simulation/investment/population/metrics.rs @@ -1,854 +1,91 @@ -//! Calculation for investment tools such as Levelised Cost of X (LCOX) and Net Present Value (NPV). -use super::coefficients::ObjectiveCoefficients; -use super::costs::annual_fixed_cost; -use super::optimisation::{ResultsMap, perform_optimisation}; -use crate::agent::ObjectiveType; -use crate::asset::{Asset, AssetRef}; -use crate::commodity::Commodity; -use crate::finance::{lcox, snas}; -use crate::model::Model; -use crate::simulation::investment::DemandMap; +//! Appraisal results and merit-order sorting for the population agent. +use super::optimisation::activity_per_capacity; +use crate::asset::AssetRef; use crate::time_slice::TimeSliceID; -use crate::units::{Activity, MoneyPerActivity, MoneyPerCapacity}; -use anyhow::Result; -use erased_serde::Serialize as ErasedSerialize; +use crate::units::{Activity, ActivityPerCapacity, Capacity}; use float_cmp::{ApproxEq, F64Margin}; use indexmap::IndexMap; -use serde::Serialize; -use std::any::Any; use std::cmp::Ordering; -use std::sync::Arc; -/// Compares two values with approximate equality checking. -/// -/// Returns `Ordering::Equal` if the values are approximately equal -/// according to the default floating-point margin, otherwise returns -/// their relative ordering based on `a.partial_cmp(&b)`. -/// -/// This is useful when comparing floating-point-based types where exact -/// equality may not be appropriate due to numerical precision limitations. -/// -/// # Panics -/// -/// Panics if `partial_cmp` returns `None` (i.e., if either value is NaN). -fn compare_approx(a: T, b: T) -> Ordering -where - T: Copy + PartialOrd + ApproxEq, -{ - if a.approx_eq(b, F64Margin::default()) { - Ordering::Equal - } else { - a.partial_cmp(&b).expect("Cannot compare NaN values") - } -} - -/// The output of investment appraisal required to compare potential investment decisions +/// The result of appraising one option against the complete demand profile. pub struct AppraisalOutput { - /// The asset being appraised + /// The asset being appraised. pub asset: AssetRef, - /// Time slice level activity of the asset - pub activity: IndexMap, - /// The hypothetical unmet demand following investment in this asset - pub unmet_demand: DemandMap, - /// The comparison metric to compare investment decisions - pub metric: Option>, - /// Activity coefficients and metric costs used in the appraisal - pub coefficients: Arc, + /// Capacity required to supply the full demand profile. + pub capacity: Capacity, + /// Activity per unit capacity for the fitted profile. + pub activity_per_capacity: IndexMap, + /// Total objective value for supplying the full demand profile. + pub metric: f64, } impl AppraisalOutput { - /// Create a new `AppraisalOutput` - fn new( + /// Build an appraisal result and convert its activity profile to per-capacity values. + pub fn new( asset: AssetRef, - results: ResultsMap, - metric: Option, - coefficients: Arc, + capacity: Capacity, + activity: &IndexMap, + metric: f64, ) -> Self { Self { asset, - activity: results.activity, - unmet_demand: results.unmet_demand, - metric: metric.map(|m| Box::new(m) as Box), - coefficients, + capacity, + activity_per_capacity: activity_per_capacity(activity, capacity), + metric, } } - /// Compare this appraisal to another on the basis of the comparison metric. - /// - /// Note that if the metrics are approximately equal, then [`Ordering::Equal`] is returned. - /// The reason for this is because different CPU architectures may lead to subtly different - /// values for the comparison metrics and if the value is very similar to another, then it can - /// lead to different decisions being made, depending on the user's platform (e.g. macOS ARM - /// vs. Windows). We want to avoid this, if possible, which is why we use a more approximate - /// comparison. - fn compare_metric(&self, other: &Self) -> Ordering { - let (metric1, metric2) = self - .metric - .as_deref() - .zip(other.metric.as_deref()) - .expect("Cannot compare non-valid outputs"); - - // We've already checked the metrics aren't `None` - metric1.compare(metric2) - } -} - -/// Supertrait for appraisal metrics that can be serialised and compared. -pub trait MetricTrait: ComparableMetric + ErasedSerialize {} -erased_serde::serialize_trait_object!(MetricTrait); - -/// Trait for appraisal metrics that can be compared. -/// -/// Implementers define how their values should be compared to determine -/// which investment option is preferable through the `compare` method. -pub trait ComparableMetric: Any + Send + Sync { - /// Returns the numeric value of this metric. - fn value(&self) -> f64; - - /// Compares this metric with another of the same type. - /// - /// Returns `Ordering::Less` if `self` is better than `other`, - /// `Ordering::Greater` if `other` is better, or `Ordering::Equal` - /// if they are approximately equal. - /// - /// # Panics - /// - /// Panics if `other` is not the same concrete type as `self`. - fn compare(&self, other: &dyn ComparableMetric) -> Ordering; - - /// Helper for downcasting to enable type-safe comparison. - fn as_any(&self) -> &dyn Any; } -/// Levelised Cost of X (LCOX) metric. +/// Compare metrics approximately to avoid platform-specific choices caused by tiny solver +/// differences (for example, between different CPU architectures). /// -/// Represents the average cost per unit of output. Lower values indicate -/// more cost-effective investments. -#[derive(Debug, Clone, Serialize)] -pub struct LCOXMetric { - /// The calculated cost value for this LCOX metric - cost: MoneyPerActivity, -} - -impl LCOXMetric { - /// Creates a new `LCOXMetric` with the given cost. - pub fn new(cost: MoneyPerActivity) -> Self { - Self { cost } - } -} - -impl ComparableMetric for LCOXMetric { - fn value(&self) -> f64 { - self.cost.value() - } - - fn compare(&self, other: &dyn ComparableMetric) -> Ordering { - let other = other - .as_any() - .downcast_ref::() - .expect("Cannot compare metrics of different types"); - - compare_approx(self.cost, other.cost) - } - - fn as_any(&self) -> &dyn Any { - self - } -} - -/// `LCOXMetric` implements the `MetricTrait` supertrait. -impl MetricTrait for LCOXMetric {} - -/// Net Present Value (NPV) tool metric. +/// # Panics /// -/// In the NPV appraisal tool we compare options using the Specific Net Annualised Surplus (SNAS) -/// expressed per unit activity. Higher values indicate more profitable investments. -#[derive(Debug, Clone, Serialize)] -struct NPVMetric { - /// The calculated SNAS value for this metric - snas: MoneyPerActivity, -} - -impl NPVMetric { - /// Creates a new `NPVMetric` with the given SNAS value. - fn new(snas: MoneyPerActivity) -> Self { - Self { snas } - } -} - -impl ComparableMetric for NPVMetric { - fn value(&self) -> f64 { - self.snas.value() - } - - fn compare(&self, other: &dyn ComparableMetric) -> Ordering { - let other = other - .as_any() - .downcast_ref::() - .expect("Cannot compare metrics of different types"); - - compare_approx(other.snas, self.snas) - } - - fn as_any(&self) -> &dyn Any { - self +/// Panics if either metric is NaN. +fn compare_metric(left: f64, right: f64) -> Ordering { + if left.approx_eq(right, F64Margin::default()) { + Ordering::Equal + } else { + left.partial_cmp(&right) + .expect("Cannot compare NaN metrics") } } -/// `NPVMetric` implements the `MetricTrait` supertrait. -impl MetricTrait for NPVMetric {} - -/// Calculate LCOX for a hypothetical investment in the given asset. -/// -/// This is more commonly referred to as Levelised Cost of *Electricity*, but as the model can -/// include other flows, we use the term LCOX. -/// -/// # Returns -/// -/// An `AppraisalOutput` containing the hypothetical capacity, activity profile and unmet demand. -/// The returned `metric` is the LCOX value (lower is better). -fn calculate_lcox( - model: &Model, - asset: &AssetRef, - commodity: &Commodity, - coefficients: &Arc, - demand: &DemandMap, -) -> Result { - let results = perform_optimisation(model, asset, commodity, coefficients, demand)?; - - let cost_index = lcox( - asset.total_capacity(), - annual_fixed_cost(asset), - &results.activity, - &coefficients.metric_costs, - ); - - Ok(AppraisalOutput::new( - asset.clone(), - results, - cost_index.map(LCOXMetric::new), - coefficients.clone(), - )) -} - -/// Calculate NPV for a hypothetical investment in the given asset. -/// -/// # Returns -/// -/// An `AppraisalOutput` containing the hypothetical capacity, activity profile and unmet demand. -fn calculate_npv( - model: &Model, - asset: &AssetRef, - commodity: &Commodity, - coefficients: &Arc, - demand: &DemandMap, -) -> Result { - let results = perform_optimisation(model, asset, commodity, coefficients, demand)?; - - let annual_fixed_cost = annual_fixed_cost(asset); - assert!( - annual_fixed_cost >= MoneyPerCapacity(0.0), - "The current NPV calculation does not support negative annual fixed costs" - ); - - let snas = snas( - asset.total_capacity(), - annual_fixed_cost, - &results.activity, - &coefficients.metric_costs, - ); - - Ok(AppraisalOutput::new( - asset.clone(), - results, - snas.map(NPVMetric::new), - coefficients.clone(), - )) -} - -/// Appraise the given investment with the specified objective type. -/// -/// # Returns -/// -/// The `AppraisalOutput` produced by the selected appraisal method. The `metric` field is -/// comparable with other appraisals of the same type (npv/lcox). -pub fn appraise_investment( - model: &Model, - asset: &AssetRef, - commodity: &Commodity, - objective_type: ObjectiveType, - coefficients: &Arc, - demand: &DemandMap, -) -> Result { - let appraisal_method = match objective_type { - ObjectiveType::LevelisedCostOfX => calculate_lcox, - ObjectiveType::NetPresentValue => calculate_npv, - }; - appraisal_method(model, asset, commodity, coefficients, demand) -} - -/// Compare assets as a fallback if metrics are equal. +/// Compare assets as a fallback when their metrics are equal. /// -/// Commissioned assets are ordered before uncommissioned and newer before older. -/// -/// Used as a fallback to sort assets when they have equal appraisal tool outputs. -fn compare_asset_fallback(asset1: &Asset, asset2: &Asset) -> Ordering { +/// Commissioned assets are preferred over candidates, and newer assets are preferred over older +/// commissioned assets. This preserves the population agent's existing equal-metric tie-break. +fn compare_asset_fallback(asset1: &AssetRef, asset2: &AssetRef) -> Ordering { (asset2.is_commissioned(), asset2.commission_year()) .cmp(&(asset1.is_commissioned(), asset1.commission_year())) } -/// Sort appraisal outputs by their investment priority and exclude non-feasible options. -/// -/// Investment priority is primarily decided by appraisal metric. When appraisal metrics are equal, -/// a tie-breaker fallback is used. Commissioned assets are preferred over uncommissioned assets, -/// and newer assets are preferred over older ones. The function does not guarantee that all ties -/// will be resolved. +/// Sort by investment priority, preserving the existing commissioned/newer tie-break rules. /// -/// Before sorting, outputs are filtered to exclude entries with invalid metrics (i.e. `None`), so -/// the length of the returned vector may be less than the input. -/// -/// # Returns -/// -/// Returns the number of non-feasible assets which were removed. -pub fn sort_and_filter_appraisal_outputs(outputs: &mut Vec) -> usize { - let old_len = outputs.len(); - outputs.retain(|output| output.metric.is_some()); - let num_nonfeasible = old_len - outputs.len(); - - outputs.sort_by(|output1, output2| match output1.compare_metric(output2) { - // If equal, we fall back on comparing asset properties - Ordering::Equal => compare_asset_fallback(&output1.asset, &output2.asset), - cmp => cmp, - }); - - num_nonfeasible +/// Lower optimisation cost is better. If metrics are approximately equal, the asset fallback is +/// used; remaining ties retain the input order. +pub fn sort_appraisal_outputs(outputs: &mut [AppraisalOutput]) { + outputs.sort_by( + |left, right| match compare_metric(left.metric, right.metric) { + Ordering::Equal => compare_asset_fallback(&left.asset, &right.asset), + ordering => ordering, + }, + ); } -/// Counts the number of top appraisal outputs in a sorted slice that are indistinguishable -/// by both metric and fallback ordering. Excludes the first element from the count. +/// Count the best options indistinguishable from the first under metric and fallback ordering. +/// +/// The first option is excluded from the count. The caller uses this to log when the selected +/// option is not uniquely best. pub fn count_equal_and_best_appraisal_outputs(outputs: &[AppraisalOutput]) -> usize { - if outputs.is_empty() { + let Some(best) = outputs.first() else { return 0; - } + }; outputs[1..] .iter() .take_while(|output| { - output.compare_metric(&outputs[0]).is_eq() - && compare_asset_fallback(&output.asset, &outputs[0].asset).is_eq() + compare_metric(output.metric, best.metric).is_eq() + && compare_asset_fallback(&output.asset, &best.asset).is_eq() }) .count() } - -#[cfg(test)] -mod tests { - use super::*; - use crate::agent::AgentID; - use crate::asset::AssetCapacity; - use crate::fixture::{agent_id, asset, process, region_id}; - use crate::process::Process; - use crate::region::RegionID; - use crate::units::{Capacity, MoneyPerActivity}; - use float_cmp::assert_approx_eq; - use rstest::rstest; - use std::sync::Arc; - - /// Parametrised tests for LCOX metric comparison. - #[rstest] - #[case(10.0, 10.0, Ordering::Equal, "equal_costs")] - #[case(5.0, 10.0, Ordering::Less, "first_lower_cost_is_better")] - #[case(10.0, 5.0, Ordering::Greater, "second_lower_cost_is_better")] - fn lcox_metric_comparison( - #[case] cost1: f64, - #[case] cost2: f64, - #[case] expected: Ordering, - #[case] description: &str, - ) { - let metric1 = LCOXMetric::new(MoneyPerActivity(cost1)); - let metric2 = LCOXMetric::new(MoneyPerActivity(cost2)); - - assert_eq!( - metric1.compare(&metric2), - expected, - "Failed comparison for case: {description}" - ); - } - - /// Parametrised tests for NPV metric comparison. - #[rstest] - #[case(10.0, 10.0, Ordering::Equal, "equal_costs")] - #[case(5.0, 10.0, Ordering::Greater, "second_higher_metric_is_better")] - #[case(10.0, 5.0, Ordering::Less, "first_higher_metric_is_better")] - fn npv_metric_comparison( - #[case] cost1: f64, - #[case] cost2: f64, - #[case] expected: Ordering, - #[case] description: &str, - ) { - let metric1 = NPVMetric::new(MoneyPerActivity(cost1)); - let metric2 = NPVMetric::new(MoneyPerActivity(cost2)); - - assert_eq!( - metric1.compare(&metric2), - expected, - "Failed comparison for case: {description}" - ); - } - - #[rstest] - fn compare_assets_fallback(process: Process, region_id: RegionID, agent_id: AgentID) { - let capacity = Capacity(2.0); - let process = Arc::new(process); - let asset1 = Asset::new_commissioned( - agent_id.clone(), - process.clone(), - region_id.clone(), - AssetCapacity::single(capacity), - 2015, - ) - .unwrap(); - let asset2 = - Asset::new_candidate(process.clone(), region_id.clone(), capacity, 2015).unwrap(); - let asset3 = Asset::new_commissioned( - agent_id, - process, - region_id.clone(), - AssetCapacity::single(capacity), - 2010, - ) - .unwrap(); - - assert!(compare_asset_fallback(&asset1, &asset1).is_eq()); - assert!(compare_asset_fallback(&asset2, &asset2).is_eq()); - assert!(compare_asset_fallback(&asset3, &asset3).is_eq()); - assert!(compare_asset_fallback(&asset1, &asset2).is_lt()); - assert!(compare_asset_fallback(&asset2, &asset1).is_gt()); - assert!(compare_asset_fallback(&asset1, &asset3).is_lt()); - assert!(compare_asset_fallback(&asset3, &asset1).is_gt()); - assert!(compare_asset_fallback(&asset3, &asset2).is_lt()); - assert!(compare_asset_fallback(&asset2, &asset3).is_gt()); - } - - fn objective_coeffs() -> Arc { - Arc::new(ObjectiveCoefficients { - activity_coefficients: IndexMap::new(), - metric_costs: IndexMap::new(), - }) - } - - /// Creates appraisal from corresponding assets and metrics - /// - /// # Panics - /// - /// Panics if `assets` and `metrics` have different lengths - fn appraisal_outputs( - assets: Vec, - metrics: Vec>, - ) -> Vec { - assert_eq!( - assets.len(), - metrics.len(), - "assets and metrics must have the same length" - ); - - assets - .into_iter() - .zip(metrics) - .map(|(asset, metric)| AppraisalOutput { - asset: AssetRef::from(asset), - coefficients: objective_coeffs(), - activity: IndexMap::new(), - unmet_demand: IndexMap::new(), - metric: Some(metric), - }) - .collect() - } - - /// Creates appraisal outputs with given metrics. - /// Copies the provided default asset for each metric. - fn appraisal_outputs_with_investment_priority_invariant_to_assets( - metrics: Vec>, - asset: &Asset, - ) -> Vec { - let assets = vec![asset.clone(); metrics.len()]; - appraisal_outputs(assets, metrics) - } - - /// Test sorting by LCOX metric when invariant to asset properties - #[rstest] - fn appraisal_sort_by_lcox_metric(asset: Asset) { - let metrics: Vec> = vec![ - Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), - Box::new(LCOXMetric::new(MoneyPerActivity(3.0))), - Box::new(LCOXMetric::new(MoneyPerActivity(7.0))), - ]; - - let mut outputs = - appraisal_outputs_with_investment_priority_invariant_to_assets(metrics, &asset); - sort_and_filter_appraisal_outputs(&mut outputs); - - assert_approx_eq!(f64, outputs[0].metric.as_ref().unwrap().value(), 3.0); // Best (lowest) - assert_approx_eq!(f64, outputs[1].metric.as_ref().unwrap().value(), 5.0); - assert_approx_eq!(f64, outputs[2].metric.as_ref().unwrap().value(), 7.0); // Worst (highest) - } - - /// Test sorting by NPV metric when invariant to asset properties - #[rstest] - fn appraisal_sort_by_npv_metric(asset: Asset) { - let metrics: Vec> = vec![ - Box::new(NPVMetric::new(MoneyPerActivity(5.0))), - Box::new(NPVMetric::new(MoneyPerActivity(3.0))), - Box::new(NPVMetric::new(MoneyPerActivity(7.0))), - ]; - - let mut outputs = - appraisal_outputs_with_investment_priority_invariant_to_assets(metrics, &asset); - sort_and_filter_appraisal_outputs(&mut outputs); - - assert_approx_eq!(f64, outputs[0].metric.as_ref().unwrap().value(), 7.0); // Best (highest) - assert_approx_eq!(f64, outputs[1].metric.as_ref().unwrap().value(), 5.0); - assert_approx_eq!(f64, outputs[2].metric.as_ref().unwrap().value(), 3.0); // Worst (lowest) - } - - /// Test that mixing LCOX and NPV metrics causes a runtime panic during comparison - #[rstest] - #[should_panic(expected = "Cannot compare metrics of different types")] - fn appraisal_sort_by_mixed_metrics_panics(asset: Asset) { - let metrics: Vec> = vec![ - Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), - Box::new(NPVMetric::new(MoneyPerActivity(3.0))), - Box::new(LCOXMetric::new(MoneyPerActivity(3.0))), - ]; - - let mut outputs = - appraisal_outputs_with_investment_priority_invariant_to_assets(metrics, &asset); - // This should panic when trying to compare different metric types - sort_and_filter_appraisal_outputs(&mut outputs); - } - - /// Test that when metrics are equal, commissioned assets are sorted by commission year (newer first) - #[rstest] - fn appraisal_sort_by_commission_year_when_metrics_equal( - process: Process, - region_id: RegionID, - agent_id: AgentID, - ) { - let process_rc = Arc::new(process); - let capacity = Capacity(10.0); - let commission_years = [2015, 2020, 2010]; - - let assets: Vec<_> = commission_years - .iter() - .map(|&year| { - Asset::new_commissioned( - agent_id.clone(), - process_rc.clone(), - region_id.clone(), - AssetCapacity::single(capacity), - year, - ) - .unwrap() - }) - .collect(); - - // All metrics have the same value - let metrics: Vec> = vec![ - Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), - Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), - Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), - ]; - - let mut outputs = appraisal_outputs(assets, metrics); - sort_and_filter_appraisal_outputs(&mut outputs); - - // Should be sorted by commission year, newest first: 2020, 2015, 2010 - assert_eq!(outputs[0].asset.commission_year(), 2020); - assert_eq!(outputs[1].asset.commission_year(), 2015); - assert_eq!(outputs[2].asset.commission_year(), 2010); - } - - /// Test that when metrics and commission years are equal, the original order is preserved - #[rstest] - fn appraisal_sort_maintains_order_when_all_equal(process: Process, region_id: RegionID) { - let process_rc = Arc::new(process); - let capacity = AssetCapacity::single(Capacity(10.0)); - let commission_year = 2015; - let agent_ids = ["agent1", "agent2", "agent3"]; - - let assets: Vec<_> = agent_ids - .iter() - .map(|&id| { - Asset::new_commissioned( - AgentID(id.into()), - process_rc.clone(), - region_id.clone(), - capacity, - commission_year, - ) - .unwrap() - }) - .collect(); - - let metrics: Vec> = vec![ - Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), - Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), - Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), - ]; - - let mut outputs = appraisal_outputs(assets.clone(), metrics); - sort_and_filter_appraisal_outputs(&mut outputs); - - // Verify order is preserved - should match the original agent_ids array - for (&expected_id, output) in agent_ids.iter().zip(outputs) { - assert_eq!(output.asset.agent_id(), Some(&AgentID(expected_id.into()))); - } - } - - /// Test that commissioned assets are prioritised over non-commissioned assets when metrics are equal - #[rstest] - fn appraisal_sort_commissioned_before_uncommissioned_when_metrics_equal( - process: Process, - region_id: RegionID, - agent_id: AgentID, - ) { - let process_rc = Arc::new(process); - let capacity = Capacity(10.0); - - // Create a mix of commissioned and candidate (non-commissioned) assets - let commissioned_asset_newer = Asset::new_commissioned( - agent_id.clone(), - process_rc.clone(), - region_id.clone(), - AssetCapacity::single(capacity), - 2020, - ) - .unwrap(); - - let commissioned_asset_older = Asset::new_commissioned( - agent_id.clone(), - process_rc.clone(), - region_id.clone(), - AssetCapacity::single(capacity), - 2015, - ) - .unwrap(); - - let candidate_asset = - Asset::new_candidate(process_rc.clone(), region_id.clone(), capacity, 2020).unwrap(); - - let assets = vec![ - candidate_asset.clone(), - commissioned_asset_older.clone(), - candidate_asset.clone(), - commissioned_asset_newer.clone(), - ]; - - // All metrics have identical values to test fallback ordering - let metrics: Vec> = vec![ - Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), - Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), - Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), - Box::new(LCOXMetric::new(MoneyPerActivity(5.0))), - ]; - - let mut outputs = appraisal_outputs(assets, metrics); - sort_and_filter_appraisal_outputs(&mut outputs); - - // Commissioned assets should be prioritised first - assert!(outputs[0].asset.is_commissioned()); - assert_eq!(outputs[0].asset.commission_year(), 2020); - assert!(outputs[1].asset.is_commissioned()); - assert_eq!(outputs[1].asset.commission_year(), 2015); - - // Non-commissioned assets should come after - assert!(!outputs[2].asset.is_commissioned()); - assert!(!outputs[3].asset.is_commissioned()); - } - - /// Test that appraisal metric is prioritised over asset properties when sorting - #[rstest] - fn appraisal_metric_is_prioritised_over_asset_properties( - process: Process, - region_id: RegionID, - agent_id: AgentID, - ) { - let process_rc = Arc::new(process); - let capacity = Capacity(10.0); - - // Create a mix of commissioned and candidate (non-commissioned) assets - let commissioned_asset_newer = Asset::new_commissioned( - agent_id.clone(), - process_rc.clone(), - region_id.clone(), - AssetCapacity::single(capacity), - 2020, - ) - .unwrap(); - - let commissioned_asset_older = Asset::new_commissioned( - agent_id.clone(), - process_rc.clone(), - region_id.clone(), - AssetCapacity::single(capacity), - 2015, - ) - .unwrap(); - - let candidate_asset = - Asset::new_candidate(process_rc.clone(), region_id.clone(), capacity, 2020).unwrap(); - - let assets = vec![ - candidate_asset.clone(), - commissioned_asset_older.clone(), - candidate_asset.clone(), - commissioned_asset_newer.clone(), - ]; - - // Make one metric slightly better than all others - let baseline_metric_value = 5.0; - let best_metric_value = baseline_metric_value - 1e-5; - let metrics: Vec> = vec![ - Box::new(LCOXMetric::new(MoneyPerActivity(best_metric_value))), - Box::new(LCOXMetric::new(MoneyPerActivity(baseline_metric_value))), - Box::new(LCOXMetric::new(MoneyPerActivity(baseline_metric_value))), - Box::new(LCOXMetric::new(MoneyPerActivity(baseline_metric_value))), - ]; - - let mut outputs = appraisal_outputs(assets, metrics); - sort_and_filter_appraisal_outputs(&mut outputs); - - // non-commissioned asset prioritised because it has a slightly better metric - assert_approx_eq!( - f64, - outputs[0].metric.as_ref().unwrap().value(), - best_metric_value - ); - } - - /// Test that appraisal outputs with an invalid metric are filtered out - #[rstest] - fn appraisal_sort_filters_invalid_metric(asset: Asset) { - let output = AppraisalOutput { - asset: AssetRef::from(asset), - coefficients: objective_coeffs(), - activity: IndexMap::new(), - unmet_demand: IndexMap::new(), - metric: None, - }; - let mut outputs = vec![output]; - - sort_and_filter_appraisal_outputs(&mut outputs); - - // The invalid output should have been filtered out - assert_eq!(outputs.len(), 0); - } - - /// Tests for counting number of equal metrics using identical assets so only metric values - /// affect the count. - #[rstest] - #[case(vec![5.0], 0, "single_element")] - #[case(vec![5.0, 5.0, 5.0], 2, "all_equal_returns_len_minus_one")] - #[case(vec![1.0, 2.0, 3.0], 0, "none_equal_to_best")] - #[case(vec![5.0, 5.0, 9.0], 1, "partial_equality_stops_at_first_difference")] - #[case(vec![5.0, 5.0, 9.0, 5.0], 1, "equality_does_not_resume_after_gap")] - fn count_equal_best_lcox_metric( - asset: Asset, - #[case] metric_values: Vec, - #[case] expected_count: usize, - #[case] description: &str, - ) { - let metrics: Vec> = metric_values - .into_iter() - .map(|v| Box::new(LCOXMetric::new(MoneyPerActivity(v))) as Box) - .collect(); - - let outputs = - appraisal_outputs_with_investment_priority_invariant_to_assets(metrics, &asset); - - assert_eq!( - count_equal_and_best_appraisal_outputs(&outputs), - expected_count, - "Failed for case: {description}" - ); - } - - /// Empty slice count should return 0. - #[test] - fn count_equal_best_empty_slice_returns_zero() { - let outputs: Vec = vec![]; - assert_eq!(count_equal_and_best_appraisal_outputs(&outputs), 0); - } - - /// Equal metrics but differing asset fallback (commissioned vs. candidate) → - /// outputs are distinguishable, so count should be 0. - #[rstest] - fn count_equal_best_equal_metric_different_fallback_returns_zero( - process: Process, - region_id: RegionID, - agent_id: AgentID, - ) { - let process_rc = Arc::new(process); - let capacity = Capacity(10.0); - - let commissioned = Asset::new_commissioned( - agent_id.clone(), - process_rc.clone(), - region_id.clone(), - AssetCapacity::single(capacity), - 2020, - ) - .unwrap(); - let candidate = - Asset::new_candidate(process_rc.clone(), region_id.clone(), capacity, 2020).unwrap(); - - let metric_value = MoneyPerActivity(5.0); - let outputs = appraisal_outputs( - vec![commissioned, candidate], - vec![ - Box::new(LCOXMetric::new(metric_value)), - Box::new(LCOXMetric::new(metric_value)), - ], - ); - - assert_eq!(count_equal_and_best_appraisal_outputs(&outputs), 0); - } - - /// Equal metrics and equal asset fallback (same commissioned status and commission year) → - /// the second element is indistinguishable, so count should be 1. - #[rstest] - fn count_equal_best_equal_metric_and_equal_fallback_returns_one( - process: Process, - region_id: RegionID, - agent_id: AgentID, - ) { - let process_rc = Arc::new(process); - let capacity = Capacity(10.0); - let year = 2020; - - let asset1 = Asset::new_commissioned( - agent_id.clone(), - process_rc.clone(), - region_id.clone(), - AssetCapacity::single(capacity), - year, - ) - .unwrap(); - let asset2 = Asset::new_commissioned( - agent_id.clone(), - process_rc.clone(), - region_id.clone(), - AssetCapacity::single(capacity), - year, - ) - .unwrap(); - - let metric_value = MoneyPerActivity(5.0); - let outputs = appraisal_outputs( - vec![asset1, asset2], - vec![ - Box::new(LCOXMetric::new(metric_value)), - Box::new(LCOXMetric::new(metric_value)), - ], - ); - - assert_eq!(count_equal_and_best_appraisal_outputs(&outputs), 1); - } -} diff --git a/src/simulation/investment/population/optimisation.rs b/src/simulation/investment/population/optimisation.rs index e9940e2a9..6b6b77742 100644 --- a/src/simulation/investment/population/optimisation.rs +++ b/src/simulation/investment/population/optimisation.rs @@ -1,174 +1,147 @@ -//! Optimisation problem for investment tools. -use super::coefficients::ObjectiveCoefficients; +//! Full-demand profile optimisation for one population-agent option. +//! +//! Each option is optimised independently with a free capacity variable. The resulting activity +//! profile therefore either matches every demand selection exactly or is infeasible; the caller +//! later scales the profile to the residual demand and applies the asset's capacity limits. use super::constraints::{ add_activity_constraints, add_demand_constraints, add_utilisation_peak_constraints, }; +use super::costs::annual_fixed_cost; use crate::asset::AssetRef; use crate::commodity::Commodity; use crate::model::Model; use crate::optimisation::{ModelError, apply_highs_options_from_toml, solve_optimal}; -use crate::simulation::activity::ActivityMap; +use crate::simulation::PriceMap; use crate::simulation::investment::DemandMap; -use crate::time_slice::{TimeSliceID, TimeSliceInfo}; -use crate::units::{Activity, Flow}; +use crate::time_slice::TimeSliceID; +use crate::time_slice::TimeSliceInfo; +use crate::units::{Activity, ActivityPerCapacity, Capacity}; use anyhow::{Context, Result}; -use highs::{RowProblem as Problem, Sense}; +use highs::{HighsModelStatus, RowProblem as Problem, Sense}; use indexmap::IndexMap; -use std::collections::HashMap; -use std::sync::Arc; -/// A decision variable in the optimisation +/// A decision variable in the optimisation. /// -/// This alias represents a column created in the `highs` solver. Callers rely on the order -/// in which columns are added to the problem when extracting solution values. +/// The order in which variables are added matters because solution columns are extracted by index. pub type Variable = highs::Col; -/// Map containing optimisation results and coefficients +/// The solved capacity, activity profile and objective value for one full-demand fit. pub struct ResultsMap { - /// Activity variables in each time slice + /// Capacity required to supply the complete demand profile. + pub capacity: Capacity, + /// Activity in each time slice that supplies the complete demand profile. pub activity: IndexMap, - /// Remaining unmet demand per time slice, computed post-solve - pub unmet_demand: DemandMap, + /// The minimised total cost for this full-demand fit. + pub metric: f64, } -/// Adds activity variables to the problem, one per time slice. -/// -/// Returns a map from time slice to the corresponding decision variable. +/// Add one non-negative activity variable per time slice, with its cost as the objective +/// coefficient. fn add_activity_vars( problem: &mut Problem, - cost_coefficients: &ObjectiveCoefficients, -) -> IndexMap { - cost_coefficients - .activity_coefficients - .iter() - .map(|(time_slice, cost)| { - let var = problem.add_column(cost.value(), 0.0..); - (time_slice.clone(), var) - }) - .collect() -} - -/// Adds constraints to the problem. -fn add_constraints( - problem: &mut Problem, - model: &Model, - asset: &AssetRef, - commodity: &Commodity, - activity_vars: &IndexMap, - demand: &DemandMap, - time_slice_info: &TimeSliceInfo, -) { - add_activity_constraints(problem, asset, activity_vars, time_slice_info); - add_demand_constraints( - problem, - asset, - commodity, - time_slice_info, - demand, - activity_vars, - ); - add_utilisation_peak_constraints(problem, model, asset, activity_vars); -} - -/// Computes remaining unmet demand per time-slice selection after a solve. -/// -/// For each time-slice selection at the commodity's balance level, the selection-level residual -/// (`demand - supply`, clamped to zero) is stored directly. Downstream consumers operate at the -/// selection level (e.g. the next round's demand constraint and `is_any_remaining_demand`), so -/// there is no need to distribute values across individual time slices. -fn compute_unmet_demand( - demand: &DemandMap, - activity: &IndexMap, - commodity: &Commodity, asset: &AssetRef, time_slice_info: &TimeSliceInfo, -) -> DemandMap { - let flow_coeff = asset.get_flow(&commodity.id).unwrap().coeff; + market_prices: &PriceMap, + year: u32, +) -> IndexMap { + assert_eq!(problem.num_cols(), 0); // must come first time_slice_info - .iter_selections_at_level(commodity.time_slice_level) - .map(|ts_selection| { - let demand_for_selection = demand[&ts_selection]; - let supply_for_selection: Flow = ts_selection - .iter(time_slice_info) - .map(|(ts, _)| activity[ts] * flow_coeff) - .sum(); - let unmet = (demand_for_selection - supply_for_selection).max(Flow(0.0)); - (ts_selection, unmet) + .iter_ids() + .map(|time_slice| { + let cost = asset.get_operating_cost(year, time_slice) + + asset.get_input_cost_from_prices(market_prices, time_slice); + (time_slice.clone(), problem.add_column(cost.value(), 0.0..)) }) .collect() } -/// Performs optimisation for an asset, given the coefficients and demand. +/// Fit one asset's activity profile exactly to the full demand profile. +/// +/// Capacity is left unbounded here so that profile feasibility and cost can be appraised separately +/// from selection limits. Those limits are applied after options have been merit-ordered. +/// +/// Returns `Ok(None)` when the constraints are infeasible for this asset. Other solver and +/// configuration errors are returned to the caller. pub fn perform_optimisation( model: &Model, asset: &AssetRef, commodity: &Commodity, - coefficients: &ObjectiveCoefficients, + market_prices: &PriceMap, + year: u32, demand: &DemandMap, -) -> Result { - // Create problem and add variables +) -> Result> { let mut problem = Problem::default(); - let activity_vars = add_activity_vars(&mut problem, coefficients); + let activity_vars = add_activity_vars( + &mut problem, + asset, + &model.time_slice_info, + market_prices, + year, + ); + // Capacity is free during appraisal; candidate, committed and retention limits are selection + // constraints, not profile-feasibility constraints. + let capacity_var = problem.add_column(annual_fixed_cost(asset).value(), 0.0..); - // Add constraints - add_constraints( + add_activity_constraints( &mut problem, - model, asset, - commodity, &activity_vars, - demand, + capacity_var, + &model.time_slice_info, + ); + add_demand_constraints( + &mut problem, + asset, + commodity, &model.time_slice_info, + demand, + &activity_vars, ); + add_utilisation_peak_constraints(&mut problem, model, asset, &activity_vars); - // Solve model - let mut highs_model = problem.optimise(Sense::Maximise); + let mut highs_model = problem.optimise(Sense::Minimise); apply_highs_options_from_toml(&mut highs_model, &model.parameters.highs.appraisal_options) - .context("Failed to apply custom HiGHS options to appraisal optimisation")?; - // Enforce single-threaded solving: when appraisals run in parallel via Rayon each HiGHS - // instance must not spawn additional worker threads. Setting `parallel="off"` disables - // HiGHS's concurrent simplex strategy without touching the global thread-pool scheduler - // (setting `threads=N` would fail if the scheduler was already initialised on this thread - // by a previous solve with a different count). + .context("Failed to apply custom HiGHS options to population appraisal")?; + // Appraisals may run in parallel via Rayon, so each HiGHS solve must remain single-threaded to + // avoid over-subscription. highs_model.set_option("parallel", "off"); - let solution = solve_optimal(highs_model) - .map_err(ModelError::into_anyhow)? - .get_solution(); - let solution_values = solution.columns(); - let activity = activity_vars + + // An infeasible profile is an expected non-option. Preserve all other errors so configuration + // failures and unexpected solver states remain visible. + let solved = match solve_optimal(highs_model) { + Ok(solved) => solved, + Err(ModelError::NonOptimal(HighsModelStatus::Infeasible)) => return Ok(None), + Err(error) => return Err(error.into_anyhow()), + }; + let metric = solved.objective_value(); + let solution = solved.get_solution(); + let values = solution.columns(); + // Activity variables are created first and capacity immediately after them; peak variables, + // when present, follow capacity. + let activities = activity_vars .keys() - .zip(solution_values.iter()) + .zip(values.iter()) .map(|(time_slice, &value)| (time_slice.clone(), Activity::new(value))) .collect(); - let unmet_demand = - compute_unmet_demand(demand, &activity, commodity, asset, &model.time_slice_info); - Ok(ResultsMap { - activity, - unmet_demand, - }) -} + let capacity = Capacity::new(values[activity_vars.len()]); -/// Dispatches each asset in order, reducing demand after each single-asset optimisation. -pub fn solve_for_assets( - model: &Model, - assets: &[AssetRef], - commodity: &Commodity, - coefficients: &HashMap>, - demand: &DemandMap, -) -> Result<(ActivityMap, DemandMap)> { - let mut activity = ActivityMap::new(); - let mut unmet_demand = demand.clone(); - - for asset in assets { - let results = - perform_optimisation(model, asset, commodity, &coefficients[asset], &unmet_demand)?; - for (time_slice, value) in results.activity { - *activity - .entry((asset.clone(), time_slice)) - .or_insert(Activity(0.0)) += value; - } - unmet_demand = results.unmet_demand; - } + Ok(Some(ResultsMap { + capacity, + activity: activities, + metric, + })) +} - Ok((activity, unmet_demand)) +/// Convert a full-demand activity profile into activity per unit of fitted capacity. +/// +/// The fitted capacity is positive whenever demand is positive; zero-capacity results are removed +/// by the appraisal caller before this conversion. +pub fn activity_per_capacity( + activity: &IndexMap, + capacity: Capacity, +) -> IndexMap { + activity + .iter() + .map(|(time_slice, activity)| (time_slice.clone(), *activity / capacity)) + .collect() } diff --git a/src/simulation/investment/population/output.rs b/src/simulation/investment/population/output.rs index c3476edfe..87726f381 100644 --- a/src/simulation/investment/population/output.rs +++ b/src/simulation/investment/population/output.rs @@ -1,4 +1,4 @@ -//! Debug output for the competitive asset selection algorithm. +//! Debug output for the population asset selection algorithm. use super::metrics::AppraisalOutput; use crate::asset::AssetID; use crate::output::DebugDataWriter; @@ -6,18 +6,17 @@ use crate::process::ProcessID; use crate::region::RegionID; use crate::simulation::investment::DemandMap; use crate::time_slice::{TimeSliceID, TimeSliceLevel, TimeSliceSelection}; -use crate::units::{Activity, Capacity, Flow, MoneyPerActivity}; +use crate::units::{ActivityPerCapacity, Capacity, Flow}; use anyhow::Result; use serde::{Deserialize, Serialize}; -/// The output file name for appraisal results -const APPRAISAL_RESULTS_FILE_NAME: &str = "debug_asset_selection_competitive.csv"; - -/// The output file name for appraisal time slice results +/// Summary appraisal results, with one row per feasible option. +const APPRAISAL_RESULTS_FILE_NAME: &str = "debug_asset_selection_population.csv"; +/// Per-time-slice fitted activity per unit capacity for each feasible option. const APPRAISAL_RESULTS_TIME_SLICE_FILE_NAME: &str = - "debug_asset_selection_competitive_time_slices.csv"; + "debug_asset_selection_population_time_slices.csv"; -/// Represents the appraisal results in a row of the appraisal results CSV file +/// One row in the summary appraisal results file. #[derive(Serialize, Deserialize, Debug, PartialEq)] struct AppraisalResultsRow { milestone_year: u32, @@ -26,10 +25,10 @@ struct AppraisalResultsRow { process_id: ProcessID, region_id: RegionID, capacity: Capacity, - metric: Option, + metric: f64, } -/// Represents the appraisal results in a row of the appraisal results time slice CSV file +/// One row in the time-slice appraisal results file. #[derive(Serialize, Deserialize, Debug, PartialEq)] struct AppraisalResultsTimeSliceRow { milestone_year: u32, @@ -38,14 +37,16 @@ struct AppraisalResultsTimeSliceRow { process_id: ProcessID, region_id: RegionID, time_slice: TimeSliceID, - activity: Activity, - activity_coefficient: MoneyPerActivity, + activity_per_capacity: ActivityPerCapacity, time_slice_level: TimeSliceLevel, demand_for_selection: Flow, - unmet_demand_for_selection: Flow, } -/// Write debug info about a round of investment appraisal +/// Write the one-time appraisal results for all feasible options. +/// +/// The summary file contains the full-demand capacity and optimisation metric. The time-slice file +/// records the fitted activity per unit capacity alongside demand at the commodity's balance +/// level. There is no unmet-demand column because each retained appraisal matches the full profile. pub fn write_debug_info( writer: &mut DebugDataWriter, milestone_year: u32, @@ -55,88 +56,59 @@ pub fn write_debug_info( time_slice_level: TimeSliceLevel, ) -> Result<()> { let run_description = writer.debug_run_description(run_description); - - let rows = appraisal_results.iter().map(|result| AppraisalResultsRow { - milestone_year, - run_description: run_description.to_string(), - asset_id: result.asset.id(), - process_id: result.asset.process_id().clone(), - region_id: result.asset.region_id().clone(), - capacity: result.asset.total_capacity(), - metric: result.metric.as_ref().map(|m| m.value()), - }); let output_writer = writer.get_custom_writer(APPRAISAL_RESULTS_FILE_NAME)?; - for row in rows { - output_writer.serialize(row)?; + for result in appraisal_results { + output_writer.serialize(AppraisalResultsRow { + milestone_year, + run_description: run_description.to_string(), + asset_id: result.asset.id(), + process_id: result.asset.process_id().clone(), + region_id: result.asset.region_id().clone(), + capacity: result.capacity, + metric: result.metric, + })?; } - let time_slice_rows = appraisal_results.iter().flat_map(|result| { - let run_description = &run_description; - result.activity.iter().map(move |(time_slice, activity)| { - // Map the individual time slice back to its containing selection so we can look - // up selection-level demand and unmet demand. + let output_writer = writer.get_custom_writer(APPRAISAL_RESULTS_TIME_SLICE_FILE_NAME)?; + for result in appraisal_results { + for (time_slice, activity_per_capacity) in &result.activity_per_capacity { + // Map the individual time slice to its containing demand selection at the commodity's + // balance level. let selection = match time_slice_level { TimeSliceLevel::Annual => TimeSliceSelection::Annual, TimeSliceLevel::Season => TimeSliceSelection::Season(time_slice.season.clone()), TimeSliceLevel::DayNight => TimeSliceSelection::Single(time_slice.clone()), }; - AppraisalResultsTimeSliceRow { + output_writer.serialize(AppraisalResultsTimeSliceRow { milestone_year, run_description: run_description.to_string(), asset_id: result.asset.id(), process_id: result.asset.process_id().clone(), region_id: result.asset.region_id().clone(), time_slice: time_slice.clone(), - activity: *activity, - activity_coefficient: result.coefficients.activity_coefficients[time_slice], + activity_per_capacity: *activity_per_capacity, time_slice_level, demand_for_selection: demand[&selection], - unmet_demand_for_selection: result.unmet_demand[&selection], - } - }) - }); - let output_writer = writer.get_custom_writer(APPRAISAL_RESULTS_TIME_SLICE_FILE_NAME)?; - for row in time_slice_rows { - output_writer.serialize(row)?; + })?; + } } Ok(()) } #[cfg(test)] mod tests { - use super::super::coefficients::ObjectiveCoefficients; - use super::super::metrics::LCOXMetric; use super::*; use crate::asset::{Asset, AssetRef}; use crate::fixture::{asset, time_slice}; use crate::output::DataWriter; + use crate::units::ActivityPerCapacity; use indexmap::indexmap; use itertools::{Itertools, assert_equal}; - use rstest::{fixture, rstest}; + use rstest::rstest; use std::iter; use std::path::Path; - use std::sync::Arc; use tempfile::tempdir; - #[fixture] - fn appraisal_output(asset: Asset, time_slice: TimeSliceID) -> AppraisalOutput { - let activity_coefficients = indexmap! { time_slice.clone() => MoneyPerActivity(0.5) }; - let metric_costs = indexmap! { time_slice.clone() => MoneyPerActivity(0.4) }; - let activity = indexmap! { time_slice.clone() => Activity(10.0) }; - let unmet_demand = - indexmap! { TimeSliceSelection::Single(time_slice.clone()) => Flow(5.0) }; - AppraisalOutput { - asset: AssetRef::from(asset), - coefficients: Arc::new(ObjectiveCoefficients { - activity_coefficients, - metric_costs, - }), - activity, - unmet_demand, - metric: Some(Box::new(LCOXMetric::new(MoneyPerActivity(4.14)))), - } - } - fn read_rows Deserialize<'de>>(dir: &Path, file_name: &str) -> Vec { csv::Reader::from_path(dir.join(file_name)) .unwrap() @@ -146,23 +118,25 @@ mod tests { } #[rstest] - fn write_debug_info_works( - asset: Asset, - appraisal_output: AppraisalOutput, - time_slice: TimeSliceID, - ) { - let milestone_year = 2020; - let run_description = "test_run".to_string(); + fn write_debug_info_writes_profile_without_unmet_demand(asset: Asset, time_slice: TimeSliceID) { + let run_description = "test_run"; let dir = tempdir().unwrap(); let demand = indexmap! { TimeSliceSelection::Single(time_slice.clone()) => Flow(100.0) }; - + let appraisal = AppraisalOutput { + asset: AssetRef::from(asset.clone()), + capacity: Capacity(2.0), + activity_per_capacity: indexmap! { + time_slice.clone() => ActivityPerCapacity(5.0) + }, + metric: 4.14, + }; { let mut writer = DataWriter::create(dir.path(), dir.path(), true).unwrap(); write_debug_info( writer.debug_writer().unwrap(), - milestone_year, - &run_description, - &[appraisal_output], + 2020, + run_description, + &[appraisal], &demand, TimeSliceLevel::DayNight, ) @@ -170,33 +144,34 @@ mod tests { writer.flush().unwrap(); } - let expected = AppraisalResultsRow { - milestone_year, - run_description: run_description.clone(), - asset_id: None, - process_id: asset.process_id().clone(), - region_id: asset.region_id().clone(), - capacity: Capacity(2.0), - metric: Some(4.14), - }; - let records: Vec = read_rows(dir.path(), APPRAISAL_RESULTS_FILE_NAME); - assert_equal(records, iter::once(expected)); - - let expected = AppraisalResultsTimeSliceRow { - milestone_year, - run_description, - asset_id: None, - process_id: asset.process_id().clone(), - region_id: asset.region_id().clone(), - time_slice: time_slice.clone(), - activity: Activity(10.0), - activity_coefficient: MoneyPerActivity(0.5), - time_slice_level: TimeSliceLevel::DayNight, - demand_for_selection: Flow(100.0), - unmet_demand_for_selection: Flow(5.0), - }; - let records: Vec = - read_rows(dir.path(), APPRAISAL_RESULTS_TIME_SLICE_FILE_NAME); - assert_equal(records, iter::once(expected)); + assert_equal( + read_rows::(dir.path(), APPRAISAL_RESULTS_FILE_NAME), + iter::once(AppraisalResultsRow { + milestone_year: 2020, + run_description: run_description.to_string(), + asset_id: None, + process_id: asset.process_id().clone(), + region_id: asset.region_id().clone(), + capacity: Capacity(2.0), + metric: 4.14, + }), + ); + assert_equal( + read_rows::( + dir.path(), + APPRAISAL_RESULTS_TIME_SLICE_FILE_NAME, + ), + iter::once(AppraisalResultsTimeSliceRow { + milestone_year: 2020, + run_description: run_description.to_string(), + asset_id: None, + process_id: asset.process_id().clone(), + region_id: asset.region_id().clone(), + time_slice: time_slice.clone(), + activity_per_capacity: ActivityPerCapacity(5.0), + time_slice_level: TimeSliceLevel::DayNight, + demand_for_selection: Flow(100.0), + }), + ); } } From 7a7ac98d87bc6ef3a75f9a438c88ad0a5293022d Mon Sep 17 00:00:00 2001 From: Tom Bland Date: Tue, 17 Nov 2026 14:19:06 +0000 Subject: [PATCH 4/5] Update docs --- docs/model/agents.md | 74 ++++++++++++++++++++++++++++++++++ docs/model/investment.md | 6 +-- docs/release_notes/upcoming.md | 3 ++ schemas/input/agents.yaml | 6 ++- 4 files changed, 84 insertions(+), 5 deletions(-) diff --git a/docs/model/agents.md b/docs/model/agents.md index b34fb275a..61062df24 100644 --- a/docs/model/agents.md +++ b/docs/model/agents.md @@ -487,6 +487,80 @@ Once the LP has been solved, the selected assets are constructed from the capaci 3. Selected existing assets have any mothballed capacity that is needed reactivated, and selected candidate assets are assigned to the agent, to be commissioned. +## Population agents + +A population agent represents a large number of discrete entities with identical needs, such as +households. Each asset represents equipment that a group of these entities uses to meet one of its +needs, such as the gas boilers of homes heated with gas. + +At each milestone year, the agent selects equipment for a market: one commodity in one region. Its +target is its share of that market's demand. Demand is a profile across time slices (or groups of +time slices, according to the commodity's time-slice level), rather than just a single annual total. +The population agent appraises options against the full profile, then selects them in merit order. + +### Population agent options + +The options considered are the agent's [investment options][investment-options]: + +- each of the agent's existing assets in the region which have the commodity as their primary + output, including any mothballed capacity; and +- one candidate asset for each process in the agent's search space for the commodity, region and + milestone year. + +### Appraisal + +A candidate asset has continuous capacity unless its process defines a `tranche_size`, in which +case its capacity is in whole multiples of that size. The appraisal finds the capacity needed for +the full demand profile; the capacity and investment limits described under +[Population agent asset selection](#population-agent-asset-selection) are applied when assets are +selected. + +Each option is appraised independently, once, against the full demand profile. An optimisation finds +the capacity and activity in each time slice that would supply the full profile using that option +alone. Activity must respect the process's availability limits, and output must match demand in +every time-slice group at the commodity's time-slice level. An option that cannot reproduce the +profile is excluded. + +The optimisation minimises the option's total annual cost: + +\\[ + \mathrm{Metric} = + \mathrm{AnnualFixedCost} \times \mathrm{Capacity} + + \sum_t \left( + \mathrm{OperatingCost}_t + \mathrm{InputCost}_t + \right) \times \mathrm{Activity}_t + + \mathrm{UtilisationPenalties} +\\] + +- **Annual fixed cost** includes fixed operating and maintenance costs. For a candidate asset it + also includes annualised capital cost; for an existing asset, capital cost is already sunk and is + not included. +- **Operating cost** includes the process's variable operating costs, levies and flow costs. +- **Input cost** is the cost of the asset's input commodities, valued at their market prices. +- **Utilisation penalties** are included when seasonal or annual peak-utilisation penalties are + configured. + +The resulting minimum cost is the option's appraisal metric; lower-cost options rank higher. If +metrics are approximately equal, commissioned assets rank ahead of candidates, and newer +commissioned assets rank ahead of older ones. Any remaining ties keep the options' input order. + +### Population agent asset selection + +1. Rank existing assets and candidates together by their appraisal metric, with lower-cost options + first. +2. Consider options in merit order. For each option, scale its full-demand capacity to the fraction + of demand that remains. Limit the selected capacity by the available capacity and the agent's + share of any investment constraints (process limits scaled by the agent's share of demand). + Candidate capacity is limited by both the process's `addition_limit` and `total_capacity_limit`; + existing capacity is limited by its total capacity and any `total_capacity_limit`. Round + discrete capacity down to whole tranches so it does not exceed demand or a limit. Scale the + fitted activity profile by the ratio of selected capacity to its full-demand capacity, and + subtract the resulting supply from the remaining demand. Any existing capacity not retained + remains mothballed. +3. Continue until demand is met within the `remaining_demand_absolute_tolerance` configured in + `model.toml`. If the available options cannot meet demand after applying their capacity and + investment limits, the simulation ends with an error. + [investment]: ./investment.md [investment-options]: ./investment.md#investment-options [investment-constraints]: ./investment.md#investment-constraints diff --git a/docs/model/investment.md b/docs/model/investment.md index c03d2b4e2..da744c9ba 100644 --- a/docs/model/investment.md +++ b/docs/model/investment.md @@ -119,12 +119,12 @@ Every asset consists of either a continuous capacity or one or more equal-capaci has continuous capacity. - Assets invested in _by MUSE_ are made up of tranches of the process `tranche_size`, if defined. Otherwise, their capacity depends on the agent type: competitive agents build new capacity in - tranches whose size is inferred from demand at the time of investment, while portfolio agents - build a continuous capacity (see [Agents][agents]). + tranches whose size is inferred from demand at the time of investment, while portfolio and + population agents build a continuous capacity (see [Agents][agents]). The tranches of a multi-tranche asset can be retained or mothballed independently. A continuous-capacity asset is retained or mothballed as a whole by competitive agents, whereas -portfolio agents may retain only part of its capacity (see +portfolio and population agents may retain only part of its capacity (see [Mothballing and Decommissioning](#mothballing-and-decommissioning)). ## Investment Constraints diff --git a/docs/release_notes/upcoming.md b/docs/release_notes/upcoming.md index 1a95c140f..97224887c 100644 --- a/docs/release_notes/upcoming.md +++ b/docs/release_notes/upcoming.md @@ -9,6 +9,8 @@ - Agents now have an agent type, set with the new optional `agent_type` column in `agents.csv`. The new `portfolio` agent type selects assets for each market by solving a single optimisation, rather than appraising options one at a time ([#1574]) +- A new `population` agent type represents a population of discrete entities with identical needs, + such as households, and selects assets in merit order ([#1603]) - A new optional `simulation_protocol` setting in `model.toml` selects how each milestone year is simulated. The new default, `agent_dispatch`, calculates flows and prices directly from the activities determined by agents' own optimisations, without a system-wide dispatch. @@ -29,3 +31,4 @@ [#1548]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1548 [#1557]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1557 [#1574]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1574 +[#1603]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1603 diff --git a/schemas/input/agents.yaml b/schemas/input/agents.yaml index dea81eff6..61151852a 100644 --- a/schemas/input/agents.yaml +++ b/schemas/input/agents.yaml @@ -19,8 +19,10 @@ fields: Optional (defaults to `portfolio` if omitted). With `portfolio`, the capacities of all existing and candidate assets are chosen together in a single optimisation. With `competitive`, existing and candidate assets compete in rounds, with the best option according - to the agent's objective selected in each round. Competitive agents are experimental and - require `please_give_me_broken_results = true` in `model.toml`. See the + to the agent's objective selected in each round. With `population`, the agent represents many + discrete entities with identical needs, such as households; existing assets and candidates are + appraised against the full demand profile and selected in merit order. Competitive agents are + experimental and require `please_give_me_broken_results = true` in `model.toml`. See the [Agents](../model/agents.md) page for details. - name: decision_rule type: string From e99c82e9da70b74a6eb6c105529557c4a540eb30 Mon Sep 17 00:00:00 2001 From: Tom Bland Date: Tue, 17 Nov 2026 14:30:25 +0000 Subject: [PATCH 5/5] Update example models --- examples/circularity/agents.csv | 16 ++++++++-------- examples/circularity/assets.csv | 4 ++-- examples/missing_commodity/agents.csv | 14 +++++++------- examples/muse1_default/agents.csv | 8 ++++---- examples/simple/agents.csv | 10 +++++----- examples/two_outputs/agents.csv | 16 ++++++++-------- examples/two_regions/agents.csv | 8 ++++---- 7 files changed, 38 insertions(+), 38 deletions(-) diff --git a/examples/circularity/agents.csv b/examples/circularity/agents.csv index ceebf51cd..0325cedcd 100644 --- a/examples/circularity/agents.csv +++ b/examples/circularity/agents.csv @@ -1,8 +1,8 @@ -id,description,regions,decision_rule,decision_lexico_tolerance -A0_OAG,Oil and gas IOC,all,single, -A0_ELC,Electricity generators,all,single, -A0_RES,Residential consumer,all,single, -A0_TRA,Consumer who drives,all,single, -A0_BPD,Biomass producer,all,single, -A0_BPL,Biomass pelletiser,all,single, -A0_REF,Refiners,all,single, +id,description,regions,decision_rule,decision_lexico_tolerance,agent_type +A0_OAG,Oil and gas IOC,all,single,,portfolio +A0_ELC,Electricity generators,all,single,,portfolio +A0_RES,Residential consumer,all,single,,population +A0_TRA,Consumer who drives,all,single,,population +A0_BPD,Biomass producer,all,single,,portfolio +A0_BPL,Biomass pelletiser,all,single,,portfolio +A0_REF,Refiners,all,single,,portfolio diff --git a/examples/circularity/assets.csv b/examples/circularity/assets.csv index 694912ce4..5e12bd382 100644 --- a/examples/circularity/assets.csv +++ b/examples/circularity/assets.csv @@ -1,9 +1,9 @@ process_id,region_id,agent_id,capacity,commission_year GASDRV,GBR,A0_OAG,4010.2,2020 -OAGRSV,GBR,A0_OAG,2073.38,2020 +OAGRSV,GBR,A0_OAG,2097.18,2020 GASPRC,GBR,A0_OAG,3789.64,2020 OILREF,GBR,A0_REF,716.5,2020 -OILRF2,GBR,A0_REF,929.5,2020 +OILRF2,GBR,A0_REF,962.71,2020 WNDFRM,GBR,A0_ELC,3.964844,2020 GASCGT,GBR,A0_ELC,5.519,2020 H2YGEN,GBR,A0_ELC,1.0,2020 diff --git a/examples/missing_commodity/agents.csv b/examples/missing_commodity/agents.csv index 0f14a98e3..6a9524f00 100644 --- a/examples/missing_commodity/agents.csv +++ b/examples/missing_commodity/agents.csv @@ -1,7 +1,7 @@ -id,description,regions,decision_rule,decision_lexico_tolerance -A0_GEX,Gas extractors,all,single, -A0_GPR,Gas processors,all,single, -A0_BPD,Biomass producer,all,single, -A0_BPL,Biomass pelletiser,all,single, -A0_ELC,Electricity generators,all,single, -A0_RES,Residential consumer,all,single, +id,description,regions,decision_rule,decision_lexico_tolerance,agent_type +A0_GEX,Gas extractors,all,single,,portfolio +A0_GPR,Gas processors,all,single,,portfolio +A0_BPD,Biomass producer,all,single,,portfolio +A0_BPL,Biomass pelletiser,all,single,,portfolio +A0_ELC,Electricity generators,all,single,,portfolio +A0_RES,Residential consumer,all,single,,population diff --git a/examples/muse1_default/agents.csv b/examples/muse1_default/agents.csv index 20d77c552..4dad75358 100644 --- a/examples/muse1_default/agents.csv +++ b/examples/muse1_default/agents.csv @@ -1,4 +1,4 @@ -id,description,regions,decision_rule,decision_lexico_tolerance -A1_RES,Residential sector agent,R1,single, -A1_PWR,Power sector agent,R1,single, -A1_GAS,Gas sector agent,R1,single, +id,description,regions,decision_rule,decision_lexico_tolerance,agent_type +A1_RES,Residential sector agent,R1,single,,population +A1_PWR,Power sector agent,R1,single,,portfolio +A1_GAS,Gas sector agent,R1,single,,portfolio diff --git a/examples/simple/agents.csv b/examples/simple/agents.csv index e64c2cf10..f65ed7385 100644 --- a/examples/simple/agents.csv +++ b/examples/simple/agents.csv @@ -1,5 +1,5 @@ -id,description,regions,decision_rule,decision_lexico_tolerance -A0_GEX,Gas extractors,all,single, -A0_GPR,Gas processors,all,single, -A0_ELC,Electricity generators,all,single, -A0_RES,Residential consumer,all,single, +id,description,regions,decision_rule,decision_lexico_tolerance,agent_type +A0_GEX,Gas extractors,all,single,,portfolio +A0_GPR,Gas processors,all,single,,portfolio +A0_ELC,Electricity generators,all,single,,portfolio +A0_RES,Residential consumer,all,single,,population diff --git a/examples/two_outputs/agents.csv b/examples/two_outputs/agents.csv index ceebf51cd..0325cedcd 100644 --- a/examples/two_outputs/agents.csv +++ b/examples/two_outputs/agents.csv @@ -1,8 +1,8 @@ -id,description,regions,decision_rule,decision_lexico_tolerance -A0_OAG,Oil and gas IOC,all,single, -A0_ELC,Electricity generators,all,single, -A0_RES,Residential consumer,all,single, -A0_TRA,Consumer who drives,all,single, -A0_BPD,Biomass producer,all,single, -A0_BPL,Biomass pelletiser,all,single, -A0_REF,Refiners,all,single, +id,description,regions,decision_rule,decision_lexico_tolerance,agent_type +A0_OAG,Oil and gas IOC,all,single,,portfolio +A0_ELC,Electricity generators,all,single,,portfolio +A0_RES,Residential consumer,all,single,,population +A0_TRA,Consumer who drives,all,single,,population +A0_BPD,Biomass producer,all,single,,portfolio +A0_BPL,Biomass pelletiser,all,single,,portfolio +A0_REF,Refiners,all,single,,portfolio diff --git a/examples/two_regions/agents.csv b/examples/two_regions/agents.csv index 0b290cc3e..969857a55 100644 --- a/examples/two_regions/agents.csv +++ b/examples/two_regions/agents.csv @@ -1,4 +1,4 @@ -id,description,regions,decision_rule -A1_RES,Residential sector agent,R1;R2,single -A1_PWR,Power sector agent,R1;R2,single -A1_GAS,Gas sector agent,R1;R2,single +id,description,regions,decision_rule,agent_type +A1_RES,Residential sector agent,R1;R2,single,population +A1_PWR,Power sector agent,R1;R2,single,portfolio +A1_GAS,Gas sector agent,R1;R2,single,portfolio