diff --git a/benches/assets.rs b/benches/assets.rs index 1a48bbd16..322c253bc 100644 --- a/benches/assets.rs +++ b/benches/assets.rs @@ -2,7 +2,7 @@ //! assets (from among existing and candidate assets) to meet demand for a given commodity/region //! market during agent investment. use criterion::{BatchSize, BenchmarkId, Criterion, criterion_group, criterion_main}; -use muse2::asset::{AssetPool, AssetRef}; +use muse2::asset::{AssetIterator, AssetPool, AssetRef}; use muse2::example::Example; use muse2::input::load_model; use muse2::model::Model; @@ -10,7 +10,7 @@ use muse2::output::DataWriter; use muse2::process::{Process, ProcessID}; use muse2::simulation::candidate_assets_for_next_year; use muse2::simulation::investment::collect_preset_demands_for_year; -use muse2::simulation::investment::competitive::{get_asset_options, select_best_assets}; +use muse2::simulation::investment::competitive::{get_candidate_assets, select_best_assets}; use muse2::simulation::market::{ collect_agent_limits, get_demand_portion_for_market, get_responsible_agents, }; @@ -196,16 +196,25 @@ fn criterion_benchmark(c: &mut Criterion) { Arc::new(build_synthetic_processes(&templates, n)), ); - let opt_assets: Vec = get_asset_options( - &existing_assets, + let processes: Vec<_> = agent + .iter_search_space(region_id, &commodity.id, YEAR) + .cloned() + .collect(); + let mut opt_assets: Vec = existing_assets + .iter() + .filter_agent(&agent.id) + .filter_region(region_id) + .filter_primary_producers_of(&commodity.id) + .cloned() + .collect(); + opt_assets.extend(get_candidate_assets( &demand, - &agent, - commodity, + &processes, region_id, + commodity, YEAR, model.parameters.capacity_tranche_fraction, - ) - .collect(); + )); let agent_addition_limits = collect_agent_limits( &agent, region_id, @@ -240,6 +249,7 @@ fn criterion_benchmark(c: &mut Criterion) { let run = || { select_best_assets( black_box(&model), + &[], opt_assets, agent_addition_limits, agent_total_limits, diff --git a/src/graph/investment.rs b/src/graph/investment.rs index 67063426f..ea9617a11 100644 --- a/src/graph/investment.rs +++ b/src/graph/investment.rs @@ -157,7 +157,7 @@ fn find_feedback_processes( /// feedback process, i.e. one whose inputs from within the SCC all appear after the market in the /// order. Producers with no inputs from within the SCC always qualify. This ensures that every /// market still has a producer when feedback processes are excluded in the second investment -/// pass (see `select_assets_for_cycle`). +/// pass (see `run_agents_for_cycle`). /// * The objective minimises the number of “forward” edges (edges that would point from an earlier /// market to a later one), counted within the original SCC and treated as unit penalties. A small /// bias (<1) is added to nudge exporters earlier without outweighing the main objective (a bias diff --git a/src/output.rs b/src/output.rs index 6dd825cf1..3d3bc9aa5 100644 --- a/src/output.rs +++ b/src/output.rs @@ -4,7 +4,8 @@ use crate::asset::{Asset, AssetID, AssetRef}; use crate::commodity::CommodityID; use crate::process::ProcessID; use crate::region::RegionID; -use crate::simulation::optimisation::{FlowMap, Solution}; +use crate::simulation::activity::FlowMap; +use crate::simulation::optimisation::Solution; use crate::simulation::prices::PriceMap; use crate::time_slice::TimeSliceID; use crate::units::{Activity, Capacity, Flow, Money, MoneyPerActivity, MoneyPerFlow}; diff --git a/src/simulation.rs b/src/simulation.rs index cc65a2221..dd7060144 100644 --- a/src/simulation.rs +++ b/src/simulation.rs @@ -12,10 +12,12 @@ use log::info; use std::path::Path; use std::sync::Arc; +pub mod activity; +use activity::FlowMap; pub mod optimisation; -use optimisation::{DispatchRun, FlowMap}; +use optimisation::DispatchRun; pub mod investment; -use investment::{collect_preset_demands_for_year, perform_agent_investment}; +use investment::{AgentRunMode, collect_preset_demands_for_year, run_agents_for_year}; pub mod market; pub mod prices; pub use prices::PriceMap; @@ -82,9 +84,17 @@ pub fn run(model: &Model, output_path: &Path, debug_model: bool) -> Result<()> { // Perform agent investment info!("Running agent investment..."); - let selected_assets = - perform_agent_investment(model, year, &existing_assets, &prices, &mut writer) - .context("Agent investment failed")?; + // NB: activities from asset selection are not currently used + let selected_assets = run_agents_for_year( + model, + year, + &existing_assets, + AgentRunMode::Invest, + &prices, + &mut writer, + ) + .context("Agent investment failed")? + .assets; // Run dispatch optimisation to get updated prices for the next iteration info!("Running dispatch optimisation..."); diff --git a/src/simulation/activity.rs b/src/simulation/activity.rs new file mode 100644 index 000000000..6e5be01f2 --- /dev/null +++ b/src/simulation/activity.rs @@ -0,0 +1,30 @@ +//! Types representing the activities of assets and the commodity flows derived from them. +use crate::asset::AssetRef; +use crate::commodity::CommodityID; +use crate::time_slice::TimeSliceID; +use crate::units::{Activity, Flow}; +use indexmap::IndexMap; + +/// A map of asset activities in each time slice +pub type ActivityMap = IndexMap<(AssetRef, TimeSliceID), Activity>; + +/// A map of commodity flows for assets in each time slice +pub type FlowMap = IndexMap<(AssetRef, CommodityID, TimeSliceID), Flow>; + +/// Create a map of commodity flows from asset activities. +/// +/// The flow of each commodity is the asset's activity multiplied by its flow coefficient. +pub fn create_flow_map<'a, I>(activity: I) -> FlowMap +where + I: IntoIterator, +{ + let mut flows = FlowMap::new(); + for (asset, time_slice, activity) in activity { + for flow in asset.iter_flows() { + let flow_key = (asset.clone(), flow.commodity.id.clone(), time_slice.clone()); + flows.insert(flow_key, activity * flow.coeff); + } + } + + flows +} diff --git a/src/simulation/investment.rs b/src/simulation/investment.rs index b0b50d850..5c2e9706f 100644 --- a/src/simulation/investment.rs +++ b/src/simulation/investment.rs @@ -1,9 +1,11 @@ //! Code for performing agent investment. -use super::optimisation::{DispatchRun, FlowMap}; +use super::activity::{ActivityMap, FlowMap, create_flow_map}; +use super::optimisation::DispatchRun; use crate::asset::{Asset, AssetRef}; use crate::commodity::{Commodity, CommodityID, CommodityMap}; use crate::model::Model; use crate::output::DataWriter; +use crate::process::Process; use crate::region::RegionID; use crate::simulation::prices::Prices; use crate::time_slice::{TimeSliceInfo, TimeSliceLevel, TimeSliceSelection}; @@ -15,6 +17,7 @@ use indexmap::IndexMap; use itertools::Itertools; use log::debug; use std::collections::HashMap; +use std::sync::Arc; use strum::IntoEnumIterator; pub mod competitive; @@ -23,38 +26,136 @@ pub mod portfolio; /// A map of demand across time-slice selections for a specific market pub type DemandMap = IndexMap; +/// The assets selected by agents, along with the activities determined during asset selection +#[derive(Clone, Default)] +pub struct Selection { + /// The selected assets (including retained commissioned assets) + pub assets: Vec, + /// The activity of each selected asset in each time slice + pub activity: ActivityMap, +} + +impl Selection { + /// Create a [`Selection`] from the results of an asset selection optimisation. + /// + /// `selected` pairs each asset as it appears in `activity` with the asset that was ultimately + /// selected. These may compare unequal (e.g. candidates are assigned an agent on selection), so + /// activities are re-keyed to the selected assets. Activities of assets which were not selected + /// are discarded. + pub fn from_optimisation(selected: Vec<(AssetRef, AssetRef)>, activity: &ActivityMap) -> Self { + let activity = { + let selected_by_original: HashMap<_, _> = + selected.iter().map(|(old, new)| (old, new)).collect(); + activity + .iter() + .filter_map(|((asset, time_slice), activity)| { + let asset = selected_by_original.get(asset)?; + Some((((*asset).clone(), time_slice.clone()), *activity)) + }) + .collect::() + }; + debug_assert!( + selected + .iter() + .all(|(_, new)| activity.keys().any(|(asset, _)| asset == new)), + "All selected assets must have activities" + ); + let assets = selected.into_iter().map(|(_, new)| new).collect(); + + Self { assets, activity } + } + + /// Whether no assets were selected + pub fn is_empty(&self) -> bool { + self.assets.is_empty() + } + + /// Add the assets and activities from another [`Selection`] + pub fn extend(&mut self, other: Selection) { + debug_assert!( + other + .assets + .iter() + .all(|asset| !self.assets.contains(asset)), + "Assets cannot be selected more than once" + ); + self.assets.extend(other.assets); + self.activity.extend(other.activity); + } + + /// Retain only the assets (and their activities) for which `predicate` returns true + pub fn retain(&mut self, predicate: F) + where + F: Fn(&AssetRef) -> bool, + { + self.assets.retain(&predicate); + self.activity.retain(|(asset, _), _| predicate(asset)); + } + + /// Create a map of commodity flows from the activities of the selected assets + pub fn flow_map(&self) -> FlowMap { + create_flow_map( + self.activity + .iter() + .map(|((asset, time_slice), activity)| (asset, time_slice, *activity)), + ) + } +} + +/// How agents are run for a milestone year +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum AgentRunMode { + /// Agents dispatch their existing assets as committed assets, without investment options + Dispatch, + /// Agents choose which existing assets to retain and which candidates to invest in + Invest, +} + +/// The assets and processes available to an agent to meet its share of demand for one market +#[derive(Default)] +pub struct AssetOptions { + /// Assets with fixed capacity: they are dispatched but cannot be expanded, reduced or mothballed + pub committed: Vec, + /// Existing assets which may be retained in full, in part or not at all + pub existing: Vec, + /// Processes from which the algorithm may create candidate assets + pub processes: Vec>, +} + /// Demand for a given combination of commodity, region and time-slice selection pub type AllDemandMap = IndexMap<(CommodityID, RegionID, TimeSliceSelection), Flow>; -/// Perform agent investment to determine capacity investment of new assets for next milestone year. +/// Run agents for a milestone year, either dispatching committed assets or choosing investments. /// /// # Arguments /// /// * `model` - The model -/// * `year` - Current milestone year -/// * `existing_assets` - The asset pool (commissioned and otherwise) +/// * `year` - Milestone year being processed +/// * `assets` - The asset pool (commissioned and otherwise) +/// * `mode` - Whether agents dispatch committed assets or make investment decisions /// * `prices` - Commodity prices calculated in the previous full system dispatch /// * `writer` - Data writer /// /// # Returns /// -/// The assets selected (including retained commissioned assets) for the given planning `year` or an +/// The assets returned by the agents for the given `year`, along with their activities, or an /// error. #[context_manager::wrap(InvestmentTimer)] -pub fn perform_agent_investment( +pub fn run_agents_for_year( model: &Model, year: u32, - existing_assets: &[AssetRef], + assets: &[AssetRef], + mode: AgentRunMode, prices: &Prices, writer: &mut DataWriter, -) -> Result> { +) -> Result { // Initialise net demand map let preset_demands = collect_preset_demands_for_year(&model.commodities, year); let mut net_demand = preset_demands.clone(); - // Keep a list of all the assets selected + // Keep track of all the assets selected // This includes Commissioned assets that are selected for retention, and new Ready assets - let mut all_selected_assets = Vec::new(); + let mut all_selected = Selection::default(); let investment_order = &model.investment_order[&year]; debug!( @@ -70,8 +171,8 @@ pub fn perform_agent_investment( // Iterate over market sets in the investment order for this year for market_set in investment_order { // Select assets for this market set - let selected_assets = - market_set.select_assets(model, year, &net_demand, existing_assets, prices, writer)?; + let selection = + market_set.run_agents(model, year, mode, &net_demand, assets, prices, writer)?; // Update our list of seen markets for market in market_set.iter_markets() { @@ -81,13 +182,14 @@ pub fn perform_agent_investment( // If no assets have been selected, skip dispatch optimisation // **TODO**: this probably means there's no demand for the market, which we could // presumably preempt - if selected_assets.is_empty() { + if selection.is_empty() { debug!("No assets selected for '{market_set}'"); continue; } // Add the selected assets to the list of all selected assets - all_selected_assets.extend(selected_assets.iter().cloned()); + let selected_assets = selection.assets.clone(); + all_selected.extend(selection); // Perform dispatch optimisation with assets that have been selected so far // **TODO**: presumably we only need to do this for selected_assets, as assets added in @@ -96,7 +198,7 @@ pub fn perform_agent_investment( // As upstream markets by definition will not yet have producers, we explicitly set // their prices using external values so that they don't appear free - let solution = DispatchRun::new(model, &all_selected_assets, year, &preset_demands) + let solution = DispatchRun::new(model, &all_selected.assets, year, &preset_demands) .without_commodity_constraints() .with_market_balance_subset(&seen_markets) .with_input_prices(&prices.shadow) @@ -110,7 +212,7 @@ pub fn perform_agent_investment( ); } - Ok(all_selected_assets) + Ok(all_selected) } /// Collect the preset commodity demands for a given year into a map of commodity, region and @@ -258,13 +360,13 @@ mod tests { use super::*; use crate::commodity::Commodity; use crate::fixture::{ - asset, process, process_activity_limits_map, process_flows_map, svd_commodity, time_slice, - time_slice_info, time_slice_info2, + agent_id, asset, process, process_activity_limits_map, process_flows_map, svd_commodity, + time_slice, time_slice_info, time_slice_info2, }; use crate::process::{ActivityLimits, FlowType, Process, ProcessFlow}; use crate::time_slice::{TimeSliceID, TimeSliceInfo, TimeSliceSelection}; use crate::units::Dimensionless; - use crate::units::{Flow, FlowPerActivity, MoneyPerFlow}; + use crate::units::{Activity, Flow, FlowPerActivity, MoneyPerFlow}; use indexmap::indexmap; use rstest::rstest; @@ -413,4 +515,91 @@ mod tests { assert_eq!(result, Capacity(20.0)); } + + fn candidate(process: &Process, commission_year: u32) -> AssetRef { + Asset::new_candidate( + Arc::new(process.clone()), + "GBR".into(), + Capacity(1.0), + commission_year, + ) + .unwrap() + .into() + } + + #[rstest] + fn selection_from_optimisation_rekeys_activity(process: Process, time_slice: TimeSliceID) { + let selected_candidate = candidate(&process, 2015); + let unselected_candidate = candidate(&process, 2016); + let mut selected_asset = selected_candidate.clone(); + selected_asset + .make_mut() + .select_candidate_for_investment(agent_id()); + assert_ne!(selected_candidate, selected_asset); + + let activity = indexmap! { + (selected_candidate.clone(), time_slice.clone()) => Activity(1.0), + (unselected_candidate, time_slice.clone()) => Activity(2.0), + }; + let selection = Selection::from_optimisation( + vec![(selected_candidate, selected_asset.clone())], + &activity, + ); + + assert_eq!(selection.assets, [selected_asset.clone()]); + assert_eq!( + selection.activity, + indexmap! { (selected_asset, time_slice) => Activity(1.0) } + ); + } + + #[rstest] + fn selection_retain_filters_assets_and_activity(process: Process, time_slice: TimeSliceID) { + let asset1 = candidate(&process, 2015); + let asset2 = candidate(&process, 2016); + let mut selection = Selection { + assets: vec![asset1.clone(), asset2.clone()], + activity: indexmap! { + (asset1.clone(), time_slice.clone()) => Activity(1.0), + (asset2.clone(), time_slice.clone()) => Activity(2.0), + }, + }; + + selection.retain(|asset| *asset == asset2); + + assert_eq!(selection.assets, std::slice::from_ref(&asset2)); + assert_eq!( + selection.activity, + indexmap! { (asset2, time_slice) => Activity(2.0) } + ); + } + + #[rstest] + fn selection_flow_map_multiplies_activity_by_coeff( + mut process: Process, + svd_commodity: Commodity, + time_slice: TimeSliceID, + ) { + let commodity = Arc::new(svd_commodity); + let process_flow = ProcessFlow { + commodity: Arc::clone(&commodity), + coeff: FlowPerActivity(2.0), + kind: FlowType::Fixed, + cost: MoneyPerFlow(0.0), + }; + process.flows = process_flows_map( + process.regions.clone(), + Arc::new(indexmap! { commodity.id.clone() => process_flow }), + ); + let asset = candidate(&process, 2015); + let selection = Selection { + assets: vec![asset.clone()], + activity: indexmap! { (asset.clone(), time_slice.clone()) => Activity(3.0) }, + }; + + assert_eq!( + selection.flow_map(), + indexmap! { (asset, commodity.id.clone(), time_slice) => Flow(6.0) } + ); + } } diff --git a/src/simulation/investment/competitive.rs b/src/simulation/investment/competitive.rs index 97de9cb6e..d5afd04c7 100644 --- a/src/simulation/investment/competitive.rs +++ b/src/simulation/investment/competitive.rs @@ -1,4 +1,4 @@ -//! The competitive asset selection algorithm. +//! 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. @@ -10,34 +10,38 @@ mod optimisation; mod output; use crate::agent::{Agent, AgentID}; -use crate::asset::{Asset, AssetCapacity, AssetIterator, AssetRef}; +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::DemandMap; +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::{Capacity, Dimensionless, Flow, FlowPerCapacity}; -use anyhow::{Result, ensure}; +use anyhow::{Result, anyhow}; use coefficients::calculate_coefficients_for_assets; -use indexmap::IndexMap; -use indexmap::IndexSet; use itertools::{Itertools, chain}; use log::{debug, warn}; 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; -/// Select assets for an agent to meet its share of demand for a commodity in a region. +/// Run the competitive algorithm for an agent to meet its share of demand for a commodity in a +/// region. /// -/// Existing assets of the agent which produce the commodity compete with candidate assets from the -/// agent's search space. Processes in `excluded_processes` are not considered. +/// 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 /// @@ -46,8 +50,7 @@ use std::collections::HashMap; /// * `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 -/// * `existing_assets` - The asset pool (commissioned and otherwise) -/// * `excluded_processes` - Processes which may not be selected +/// * `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 from the previous full system dispatch @@ -56,39 +59,40 @@ use std::collections::HashMap; /// /// # Returns /// -/// The assets selected (including retained commissioned assets), or an error. +/// 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 select_assets( +pub fn run_agent( model: &Model, agent: &Agent, commodity: &Commodity, region_id: &RegionID, demand: &DemandMap, - existing_assets: &[AssetRef], - excluded_processes: &IndexSet, + options: &AssetOptions, agent_addition_limits: HashMap, agent_total_limits: HashMap, prices: &Prices, year: u32, debug_writer: Option<&mut DebugDataWriter>, -) -> Result> { +) -> Result { // Existing and candidate assets from which to choose - let mut opt_assets = get_asset_options( - existing_assets, - demand, - agent, - commodity, - region_id, - year, - model.parameters.capacity_tranche_fraction, + let opt_assets = chain( + options.existing.iter().cloned(), + get_candidate_assets( + demand, + &options.processes, + region_id, + commodity, + year, + model.parameters.capacity_tranche_fraction, + ), ) .collect::>(); - // Exclude certain processes from the options - opt_assets.retain(|asset| !excluded_processes.contains(asset.process_id())); - select_best_assets( model, + &options.committed, opt_assets, agent_addition_limits, agent_total_limits, @@ -102,38 +106,7 @@ pub fn select_assets( ) } -/// Get options from existing and potential assets for the given parameters -pub fn get_asset_options<'a>( - all_existing_assets: &'a [AssetRef], - demand: &'a DemandMap, - agent: &'a Agent, - commodity: &'a Commodity, - region_id: &'a RegionID, - year: u32, - capacity_tranche_fraction: Dimensionless, -) -> impl Iterator + 'a { - // Get existing assets which produce the commodity of interest - let existing_assets = all_existing_assets - .iter() - .filter_agent(&agent.id) - .filter_region(region_id) - .filter_primary_producers_of(&commodity.id) - .cloned(); - - // Get candidates assets which produce the commodity of interest - let candidate_assets = get_candidate_assets( - demand, - agent, - region_id, - commodity, - year, - capacity_tranche_fraction, - ); - - chain(existing_assets, candidate_assets) -} - -/// Get candidate assets which produce a particular commodity for a given agent +/// 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`. @@ -141,36 +114,33 @@ pub fn get_asset_options<'a>( /// 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. -fn get_candidate_assets<'a>( +pub fn get_candidate_assets<'a>( demand: &'a DemandMap, - agent: &'a Agent, + processes: &'a [Arc], region_id: &'a RegionID, commodity: &'a Commodity, year: u32, capacity_tranche_fraction: Dimensionless, ) -> impl Iterator + 'a { - agent - .iter_search_space(region_id, &commodity.id, year) - .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() - }) + 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. @@ -236,9 +206,13 @@ fn log_on_equal_appraisal_outputs( } /// 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, @@ -249,7 +223,7 @@ pub fn select_best_assets( demand: &DemandMap, year: u32, mut debug_writer: Option<&mut DebugDataWriter>, -) -> Result> { +) -> Result { let objective_type = agent.objectives[&year]; // Remaining addition limits for candidate processes @@ -268,7 +242,7 @@ pub fn select_best_assets( let coefficients = calculate_coefficients_for_assets( model, objective_type, - &opt_assets, + &chain(committed_assets, &opt_assets).cloned().collect_vec(), &prices.market, &prices.fallback, year, @@ -276,9 +250,18 @@ pub fn select_best_assets( // Iteratively select the best asset until demand is met let mut round = 0; - let mut selected_assets: Vec = Vec::new(); + let mut selected_assets: Vec = committed_assets.to_vec(); let mut unmet_demand = demand.clone(); - let mut previous_solution = IndexMap::new(); + 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, unmet_demand) = + solve_for_assets(model, &selected_assets, commodity, &coefficients, demand)?; + } + + let has_options = !opt_assets.is_empty(); while is_any_remaining_demand( &unmet_demand, model.parameters.remaining_demand_absolute_tolerance, @@ -291,13 +274,15 @@ pub fn select_best_assets( true, ); remove_assets_exceeding_agent_limits(&mut opt_assets, &remaining_agent_total_limits, false); - ensure!( - !opt_assets.is_empty(), - "Failed to meet demand for commodity '{}' in region '{}' with provided investment \ - options. This may be due to overly restrictive process investment constraints.", - commodity.id, - region_id - ); + 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. @@ -385,17 +370,62 @@ pub fn select_best_assets( round += 1; } - // Convert Candidate assets to Ready - // At this point we also assign the agent ID to the asset - for asset in &mut selected_assets { - if asset.is_candidate() { - asset - .make_mut() - .select_candidate_for_investment(agent.id.clone()); - } - } + 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 from the final round covers exactly the selected assets. Committed and +/// commissioned assets are unchanged. +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) +} - Ok(selected_assets) +/// 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. diff --git a/src/simulation/investment/competitive/metrics.rs b/src/simulation/investment/competitive/metrics.rs index a7b5438b6..9f4d9b48e 100644 --- a/src/simulation/investment/competitive/metrics.rs +++ b/src/simulation/investment/competitive/metrics.rs @@ -7,6 +7,7 @@ use crate::asset::{Asset, AssetRef}; use crate::commodity::Commodity; use crate::finance::{lcox, snas}; use crate::model::Model; +use crate::simulation::activity::ActivityMap; use crate::simulation::investment::DemandMap; use crate::time_slice::TimeSliceID; use crate::units::{Activity, MoneyPerActivity, MoneyPerCapacity}; @@ -56,7 +57,7 @@ pub struct AppraisalOutput { /// Activity coefficients and metric costs used in the appraisal pub coefficients: Arc, /// Full solution to the optimisation - pub solution: IndexMap<(AssetRef, TimeSliceID), Activity>, + pub solution: ActivityMap, } impl AppraisalOutput { @@ -217,7 +218,7 @@ fn calculate_lcox( commodity: &Commodity, coefficients: &HashMap>, demand: &DemandMap, - previous_solution: &IndexMap<(AssetRef, TimeSliceID), Activity>, + previous_solution: &ActivityMap, ) -> Result { let results = perform_optimisation( model, @@ -256,7 +257,7 @@ fn calculate_npv( commodity: &Commodity, coefficients: &HashMap>, demand: &DemandMap, - previous_solution: &IndexMap<(AssetRef, TimeSliceID), Activity>, + previous_solution: &ActivityMap, ) -> Result { let results = perform_optimisation( model, @@ -304,7 +305,7 @@ pub fn appraise_investment( objective_type: ObjectiveType, coefficients: &HashMap>, demand: &DemandMap, - previous_solution: &IndexMap<(AssetRef, TimeSliceID), Activity>, + previous_solution: &ActivityMap, ) -> Result { let appraisal_method = match objective_type { ObjectiveType::LevelisedCostOfX => calculate_lcox, diff --git a/src/simulation/investment/competitive/optimisation.rs b/src/simulation/investment/competitive/optimisation.rs index c29c1b915..d74378211 100644 --- a/src/simulation/investment/competitive/optimisation.rs +++ b/src/simulation/investment/competitive/optimisation.rs @@ -8,6 +8,7 @@ use super::record_asset_selection; use crate::asset::AssetRef; use crate::commodity::Commodity; use crate::model::Model; +use crate::simulation::activity::ActivityMap; use crate::simulation::investment::DemandMap; use crate::simulation::optimisation::ModelError; use crate::simulation::optimisation::apply_highs_options_from_toml; @@ -34,7 +35,7 @@ pub struct ResultsMap { /// Remaining unmet demand per time slice, computed post-solve pub unmet_demand: DemandMap, /// Full solution to the optimisation (activities of all assets) - pub solution: IndexMap<(AssetRef, TimeSliceID), Activity>, + pub solution: ActivityMap, } /// Adds activity variables to the problem, one per time slice. @@ -87,7 +88,7 @@ fn add_constraints( fn compute_unmet_demand( demand: &DemandMap, assets: &[AssetRef], - activity: &IndexMap<(AssetRef, TimeSliceID), Activity>, + activity: &ActivityMap, commodity: &Commodity, time_slice_info: &TimeSliceInfo, ) -> DemandMap { @@ -118,29 +119,25 @@ fn compute_unmet_demand( .collect() } -/// Performs optimisation for an asset, given the coefficients and demand. -pub fn perform_optimisation( +/// Solves the appraisal optimisation for a fixed set of assets. +/// +/// Returns the activity of every asset in every time slice, and the remaining unmet demand. +pub fn solve_for_assets( model: &Model, - selected_assets: &[AssetRef], - asset: &AssetRef, + assets: &[AssetRef], commodity: &Commodity, coefficients: &HashMap>, demand: &DemandMap, - previous_solution: &IndexMap<(AssetRef, TimeSliceID), Activity>, -) -> Result { - // Record hypothetical asset selection - let mut assets = selected_assets.to_vec(); - record_asset_selection(asset.clone(), &mut assets); - +) -> Result<(ActivityMap, DemandMap)> { // Create problem let mut problem = Problem::default(); - let activity_vars = add_activity_vars(&mut problem, &assets, coefficients); + let activity_vars = add_activity_vars(&mut problem, assets, coefficients); // Add constraints add_constraints( &mut problem, model, - &assets, + assets, commodity, &activity_vars, demand, @@ -163,19 +160,39 @@ pub fn perform_optimisation( // Extract asset activities and calculate unmet demand let solution_values = solution.columns(); - let all_activity = activity_vars + let all_activity: ActivityMap = activity_vars .keys() .zip(solution_values.iter()) .map(|(key, &value)| (key.clone(), Activity::new(value))) .collect(); let unmet_demand = compute_unmet_demand( demand, - &assets, + assets, &all_activity, commodity, &model.time_slice_info, ); + Ok((all_activity, unmet_demand)) +} + +/// Performs optimisation for an asset, given the coefficients and demand. +pub fn perform_optimisation( + model: &Model, + selected_assets: &[AssetRef], + asset: &AssetRef, + commodity: &Commodity, + coefficients: &HashMap>, + demand: &DemandMap, + previous_solution: &ActivityMap, +) -> Result { + // Record hypothetical asset selection + let mut assets = selected_assets.to_vec(); + record_asset_selection(asset.clone(), &mut assets); + + let (all_activity, unmet_demand) = + solve_for_assets(model, &assets, commodity, coefficients, demand)?; + // Collect equivalence group for the asset of interest let equivalence_groups = group_dispatch_equivalent_assets(assets.iter()); let asset_group = equivalence_groups diff --git a/src/simulation/investment/portfolio.rs b/src/simulation/investment/portfolio.rs index 2971d2ff2..f118d4a4c 100644 --- a/src/simulation/investment/portfolio.rs +++ b/src/simulation/investment/portfolio.rs @@ -1,21 +1,21 @@ -//! The portfolio asset selection algorithm. +//! The portfolio agent algorithm. //! //! Rather than selecting assets one at a time, a single optimisation chooses the capacities of all //! existing and candidate assets at once so as to meet demand at least cost. use crate::agent::Agent; -use crate::asset::{Asset, AssetCapacity, AssetIterator, AssetRef}; +use crate::asset::{Asset, AssetCapacity, AssetRef}; use crate::commodity::Commodity; 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::DemandMap; +use crate::simulation::investment::{AssetOptions, DemandMap, Selection}; use crate::simulation::prices::Prices; use crate::units::Capacity; -use anyhow::Result; -use indexmap::IndexSet; +use anyhow::{Context, Result, ensure}; use itertools::chain; use std::collections::HashMap; +use std::sync::Arc; mod constraints; mod costs; @@ -24,11 +24,12 @@ mod output; use optimisation::perform_optimisation; use output::write_debug_info; -/// Select assets for an agent to meet its share of demand for a commodity in a region. +/// Run the portfolio algorithm for an agent to meet its share of demand for a commodity in a +/// region. /// -/// Existing assets of the agent which produce the commodity and one candidate for each process in -/// the agent's search space are considered together in a single optimisation. Processes in -/// `excluded_processes` are not considered. +/// Committed assets (with fixed capacity), existing assets of the agent which produce the commodity +/// and one candidate for each available process are considered together in a single optimisation. +/// Committed assets are always returned unchanged. /// /// # Arguments /// @@ -37,8 +38,7 @@ use output::write_debug_info; /// * `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 -/// * `existing_assets` - The asset pool (commissioned and otherwise) -/// * `excluded_processes` - Processes which may not be selected +/// * `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 from the previous full system dispatch @@ -47,48 +47,77 @@ use output::write_debug_info; /// /// # Returns /// -/// The assets selected (including retained commissioned assets), or an error. +/// The assets selected (including committed assets and retained commissioned assets) along with +/// their activities from the optimisation, or an error. An error is also returned if demand cannot +/// be met. #[allow(clippy::too_many_arguments)] #[allow( clippy::needless_pass_by_value, - reason = "Match competitive::select_assets for shared function-pointer dispatch" + reason = "Match competitive::run_agent for shared function-pointer dispatch" )] -pub fn select_assets( +pub fn run_agent( model: &Model, agent: &Agent, commodity: &Commodity, region_id: &RegionID, demand: &DemandMap, - existing_assets: &[AssetRef], - excluded_processes: &IndexSet, + options: &AssetOptions, agent_addition_limits: HashMap, agent_total_limits: HashMap, prices: &Prices, year: u32, writer: Option<&mut DebugDataWriter>, -) -> Result> { - // Existing and candidate assets from which to choose - let mut opt_assets = - get_asset_options(existing_assets, agent, commodity, region_id, year).collect::>(); +) -> Result { + // Committed assets come first, followed by existing and candidate assets + let num_committed = options.committed.len(); + let opt_assets = chain!( + options.committed.iter().cloned(), + options.existing.iter().cloned(), + get_candidate_assets(&options.processes, region_id, year), + ) + .collect::>(); - // Exclude certain processes from the options - opt_assets.retain(|asset| !excluded_processes.contains(asset.process_id())); + let agent_id = &agent.id; + let commodity_id = &commodity.id; + + // With no assets there is nothing to optimise (the LP would be empty) + if opt_assets.is_empty() { + let tolerance = model.parameters.remaining_demand_absolute_tolerance; + ensure!( + demand.values().all(|flow| *flow <= tolerance), + "Agent '{agent_id}' cannot meet its demand for commodity '{commodity_id}' in region \ + '{region_id}' in year {year} with its existing assets" + ); + return Ok(Selection::default()); + } // Perform optimisation let results = perform_optimisation( model, &opt_assets, + num_committed, commodity, prices, year, &agent_addition_limits, &agent_total_limits, demand, - )?; + ) + .with_context(|| { + if options.processes.is_empty() { + format!( + "Agent '{agent_id}' cannot meet its demand for commodity '{commodity_id}' in \ + region '{region_id}' in year {year} with its existing assets" + ) + } else { + format!( + "Portfolio optimisation failed for agent '{agent_id}', commodity \ + '{commodity_id}', region '{region_id}' in year {year}" + ) + } + })?; // Write optimisation results - let commodity_id = &commodity.id; - let agent_id = &agent.id; if let Some(writer) = writer { write_debug_info( writer, @@ -99,8 +128,13 @@ pub fn select_assets( } // Assemble assets from optimisation result - let mut selected_assets = Vec::new(); - for (asset, result) in results.capacities { + // Committed assets are returned unchanged, even with zero activity + let mut selected = options + .committed + .iter() + .map(|asset| (asset.clone(), asset.clone())) + .collect::>(); + for (asset, result) in results.capacities.iter().skip(num_committed) { // Solver noise can give tiny negative values let capacity = asset .capacity() @@ -110,61 +144,124 @@ pub fn select_assets( } // Selected assets are unmothballed. This must happen before `set_capacity`. - let mut selected = asset.with_no_mothballed_capacity(); - let inner = selected.make_mut(); + let mut selected_asset = asset.clone().with_no_mothballed_capacity(); + let inner = selected_asset.make_mut(); if inner.is_candidate() { inner.select_candidate_for_investment(agent.id.clone()); } inner.set_capacity(capacity); - selected_assets.push(selected); + selected.push((asset.clone(), selected_asset)); } - Ok(selected_assets) -} - -/// Get options from existing and potential assets for the given parameters -fn get_asset_options<'a>( - all_existing_assets: &'a [AssetRef], - agent: &'a Agent, - commodity: &'a Commodity, - region_id: &'a RegionID, - year: u32, -) -> impl Iterator + 'a { - // Get existing assets which produce the commodity of interest - let existing_assets = all_existing_assets - .iter() - .filter_agent(&agent.id) - .filter_region(region_id) - .filter_primary_producers_of(&commodity.id) - .cloned(); - - // Get candidates assets which produce the commodity of interest - let candidate_assets = get_candidate_assets(agent, region_id, commodity, year); - - chain(existing_assets, candidate_assets) + Ok(Selection::from_optimisation(selected, &results.activities)) } -/// Get candidate assets which produce a particular commodity for a given agent +/// Get candidate assets which produce a particular commodity from the given processes. /// /// Candidates have zero capacity, as the investment optimisation determines how much to build. /// Capacity is discrete (in tranches of `tranche_size`) for processes with a defined /// `tranche_size` and continuous otherwise. fn get_candidate_assets<'a>( - agent: &'a Agent, + processes: &'a [Arc], region_id: &'a RegionID, - commodity: &'a Commodity, year: u32, ) -> impl Iterator + 'a { - agent - .iter_search_space(region_id, &commodity.id, year) - .map(move |process| { - let tranche_size = process.tranche_size.unwrap_or(Capacity(0.0)); - let mut asset = - 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() - }) + processes.iter().map(move |process| { + let tranche_size = process.tranche_size.unwrap_or(Capacity(0.0)); + let mut asset = + 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() + }) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::agent::AgentID; + use crate::asset::AssetPool; + use crate::commodity::CommodityID; + use crate::fixture::build_patched_simple_tempdir; + use crate::input::load_model; + use crate::output::DataWriter; + use crate::units::Flow; + use itertools::assert_equal; + use tempfile::tempdir; + + /// Run the portfolio algorithm with only committed assets for the residential consumer in the + /// simple example, with the given demand in each time slice. Returns the model's committed + /// assets alongside the result. + fn run_committed(demand_per_time_slice: Flow) -> (Vec, Result) { + 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 mut pool = AssetPool::new(); + pool.commission_new(year, &mut model.user_assets.clone()); + + let agent = &model.agents[&AgentID::from("A0_RES")]; + let commodity = &model.commodities[&CommodityID::from("RSHEAT")]; + let region_id = RegionID::from("GBR"); + let committed = pool + .iter() + .filter(|asset| asset.agent_id() == Some(&agent.id)) + .cloned() + .collect::>(); + let options = AssetOptions { + committed: committed.clone(), + ..AssetOptions::default() + }; + let demand = model + .time_slice_info + .iter_selections_at_level(commodity.time_slice_level) + .map(|selection| (selection, demand_per_time_slice)) + .collect(); + + let dir = tempdir().unwrap(); + let mut writer = DataWriter::create(dir.path(), dir.path(), false).unwrap(); + let result = run_agent( + &model, + agent, + commodity, + ®ion_id, + &demand, + &options, + HashMap::new(), + HashMap::new(), + &Prices::default(), + year, + writer.debug_writer(), + ); + (committed, result) + } + + #[test] + fn run_agent_returns_committed_assets_unchanged() { + let (committed, result) = run_committed(Flow(1.0)); + let selection = result.unwrap(); + + assert_ne!(committed.len(), 0); + assert_equal(&selection.assets, &committed); + for asset in &committed { + assert!( + selection + .activity + .keys() + .any(|(activity_asset, _)| activity_asset == asset) + ); + } + } + + #[test] + fn run_agent_errors_if_committed_assets_cannot_meet_demand() { + let (_, result) = run_committed(Flow(1e12)); + let error = result.err().unwrap(); + assert_eq!( + error.to_string(), + "Agent 'A0_RES' cannot meet its demand for commodity 'RSHEAT' in region 'GBR' in \ + year 2020 with its existing assets" + ); + assert!(error.chain().count() > 1); + } } diff --git a/src/simulation/investment/portfolio/optimisation.rs b/src/simulation/investment/portfolio/optimisation.rs index cae053bf9..f307e9993 100644 --- a/src/simulation/investment/portfolio/optimisation.rs +++ b/src/simulation/investment/portfolio/optimisation.rs @@ -3,6 +3,7 @@ use crate::asset::AssetRef; use crate::commodity::Commodity; use crate::model::Model; use crate::process::ProcessID; +use crate::simulation::activity::ActivityMap; use crate::simulation::investment::DemandMap; use crate::simulation::optimisation::ModelError; use crate::simulation::optimisation::{apply_highs_options_from_toml, solve_optimal}; @@ -31,7 +32,7 @@ pub struct ResultsMap { /// Capacities pub capacities: IndexMap, /// Activity variables in each time slice - pub activities: IndexMap<(AssetRef, TimeSliceID), Activity>, + pub activities: ActivityMap, } /// Adds capacity variables to the problem, one per asset. @@ -42,25 +43,34 @@ pub struct ResultsMap { /// unbounded) /// - for existing assets, their total capacity, including any mothballed capacity (they can be /// reduced, but not increased) +/// +/// The first `num_committed` assets are committed: their capacity is fixed at their active capacity. fn add_capacity_vars( problem: &mut Problem, assets: &[AssetRef], + num_committed: usize, addition_limits: &HashMap, ) -> IndexMap { assert!(problem.num_cols() > 0); // must come after activity variables assets .iter() - .map(|asset| { - let upper_bound = if asset.is_candidate() { - addition_limits.get(asset.process_id()).copied() - } else { - Some(asset.total_capacity()) - }; - + .enumerate() + .map(|(i, asset)| { let cost = annual_fixed_cost(asset).value(); - let var = match upper_bound { - Some(upper) => problem.add_column(cost, 0.0..=upper.value()), - None => problem.add_column(cost, 0.0..), + let var = if i < num_committed { + // For committed assets, only consider non-mothballed (active) capacity + let capacity = asset.active_capacity().value(); + problem.add_column(cost, capacity..=capacity) + } else if asset.is_candidate() { + match addition_limits.get(asset.process_id()) { + Some(limit) => problem.add_column(cost, 0.0..=limit.value()), + None => problem.add_column(cost, 0.0..), + } + } else { + // We allow non-committed existing assets to be de-mothballed, so use the whole + // capacity + let capacity = asset.total_capacity().value(); + problem.add_column(cost, 0.0..=capacity) }; (asset.clone(), var) }) @@ -126,11 +136,14 @@ fn add_constraints( // add_equal_utilisation_constraints(problem, activity_vars, &model.time_slice_info, assets); } -/// Performs optimisation for an asset, given the prices and demand. +/// Performs optimisation for the given assets, given the prices and demand. +/// +/// The first `num_committed` assets are committed and have fixed capacity. #[allow(clippy::too_many_arguments)] pub fn perform_optimisation( model: &Model, assets: &[AssetRef], + num_committed: usize, commodity: &Commodity, prices: &Prices, year: u32, @@ -142,7 +155,7 @@ pub fn perform_optimisation( let mut problem = Problem::default(); let activity_vars = add_activity_vars(&mut problem, assets, &model.time_slice_info, prices, year); - let capacity_vars = add_capacity_vars(&mut problem, assets, addition_limits); // must come after activity vars + let capacity_vars = add_capacity_vars(&mut problem, assets, num_committed, addition_limits); // must come after activity vars // Add constraints add_constraints( @@ -176,7 +189,7 @@ pub fn perform_optimisation( let (activity_values, remaining_values) = solution_values.split_at(activity_vars.len()); let capacity_values = &remaining_values[..capacity_vars.len()]; - let activities: IndexMap<_, _> = activity_vars + let activities: ActivityMap = activity_vars .keys() .zip(activity_values) .map(|(key, &value)| (key.clone(), Activity::new(value))) diff --git a/src/simulation/market.rs b/src/simulation/market.rs index 7b5a02f33..8a5e6fb17 100644 --- a/src/simulation/market.rs +++ b/src/simulation/market.rs @@ -1,13 +1,17 @@ //! Code for creating sets of markets. -use super::optimisation::{DispatchRun, FlowMap}; +use super::activity::FlowMap; +use super::investment::Selection; +use super::optimisation::DispatchRun; use crate::agent::{Agent, AgentType}; -use crate::asset::AssetRef; +use crate::asset::{AssetIterator, AssetRef}; use crate::commodity::{Commodity, CommodityID}; use crate::model::Model; use crate::output::DataWriter; use crate::process::{Process, ProcessID}; use crate::region::RegionID; -use crate::simulation::investment::{AllDemandMap, DemandMap, update_net_demand_map}; +use crate::simulation::investment::{ + AgentRunMode, AllDemandMap, AssetOptions, DemandMap, update_net_demand_map, +}; use crate::simulation::investment::{competitive, portfolio}; use crate::simulation::prices::Prices; use crate::time_slice::TimeSliceInfo; @@ -22,10 +26,10 @@ use std::fmt::Display; /// Represents a set of markets which are invested in together. #[derive(PartialEq, Debug, Clone, Eq)] pub enum MarketSet { - /// Assets are selected for a single market using [`select_assets_for_single_market`] + /// Assets are selected for a single market using [`run_agents_for_single_market`] Single((CommodityID, RegionID)), /// Assets are selected for a group of markets which forms a cycle using - /// [`select_assets_for_cycle`] + /// [`run_agents_for_cycle`] Cycle { /// The markets in the cycle, in investment order markets: Vec<(CommodityID, RegionID)>, @@ -48,34 +52,42 @@ impl MarketSet { } } - /// Selects assets for this market set variant and passes through the shared - /// context needed by single-market, cycle, or layered selection. + /// Runs agents for this market set variant and passes through the shared + /// context needed by single-market, cycle, or layered runs. /// /// # Arguments /// /// * `model` – Simulation model supplying parameters, processes, and dispatch. /// * `year` – Planning year being solved. + /// * `mode` – Whether agents dispatch committed assets or make investment decisions. /// * `demand` – Net demand profiles available to all markets before selection. - /// * `existing_assets` – Assets already commissioned in the system. + /// * `assets` – Assets available to agents in this market. /// * `prices` – Commodity price assumptions to use when valuing investments. /// * `writer` – Data sink used to log optimisation artefacts. - pub fn select_assets( + /// + /// # Returns + /// + /// The selected assets along with their activities from the agent runs. + #[allow(clippy::too_many_arguments)] + pub fn run_agents( &self, model: &Model, year: u32, + mode: AgentRunMode, demand: &AllDemandMap, - existing_assets: &[AssetRef], + assets: &[AssetRef], prices: &Prices, writer: &mut DataWriter, - ) -> Result> { + ) -> Result { match self { - MarketSet::Single((commodity_id, region_id)) => select_assets_for_single_market( + MarketSet::Single((commodity_id, region_id)) => run_agents_for_single_market( model, commodity_id, region_id, year, + mode, demand, - existing_assets, + assets, prices, &IndexSet::new(), writer, @@ -85,19 +97,20 @@ impl MarketSet { feedback_processes, } => { debug!( - "Starting investment for cycle '{self}' with feedback processes: [{}]", + "Starting agent runs for cycle '{self}' with feedback processes: [{}]", feedback_processes .iter() .map(|(process_id, region_id)| format!("{process_id}|{region_id}")) .join(", ") ); - select_assets_for_cycle( + run_agents_for_cycle( model, markets, feedback_processes, year, + mode, demand, - existing_assets, + assets, prices, writer, ) @@ -111,21 +124,15 @@ impl MarketSet { }) } MarketSet::Layer(investment_sets) => { - debug!("Starting asset selection for layer '{self}'"); - let mut all_assets = Vec::new(); + debug!("Starting agent runs for layer '{self}'"); + let mut layer_selection = Selection::default(); for investment_set in investment_sets { - let assets = investment_set.select_assets( - model, - year, - demand, - existing_assets, - prices, - writer, - )?; - all_assets.extend(assets); + let selection = investment_set + .run_agents(model, year, mode, demand, assets, prices, writer)?; + layer_selection.extend(selection); } - debug!("Completed asset selection for layer '{self}'"); - Ok(all_assets) + debug!("Completed agent runs for layer '{self}'"); + Ok(layer_selection) } } } @@ -151,29 +158,31 @@ impl Display for MarketSet { } } -/// Select assets for a single market in a given year +/// Run the responsible agents for a single market in a given year. /// -/// Returns a list of assets that are selected for investment for this market in this year. +/// Returns the assets returned by agents for this market in this year, along with their +/// activities. #[allow(clippy::too_many_arguments)] -pub fn select_assets_for_single_market( +pub fn run_agents_for_single_market( model: &Model, commodity_id: &CommodityID, region_id: &RegionID, year: u32, + mode: AgentRunMode, demand: &AllDemandMap, - existing_assets: &[AssetRef], + assets: &[AssetRef], prices: &Prices, excluded_processes: &IndexSet, writer: &mut DataWriter, -) -> Result> { +) -> Result { let commodity = &model.commodities[commodity_id]; - let mut selected_assets = Vec::new(); + let mut market_selection = Selection::default(); for (agent, commodity_portion) in get_responsible_agents(model.agents.values(), commodity_id, region_id, year) { debug!( - "Running asset selection for agent '{}' in market '{}|{}'", + "Running agent '{}' in market '{}|{}'", agent.id, commodity_id, region_id ); @@ -186,90 +195,133 @@ pub fn select_assets_for_single_market( commodity_portion, ); - // Calculate the agent's share of addition limits for candidate processes - let agent_addition_limits = collect_agent_limits( - agent, - region_id, - commodity_id, - year, - commodity_portion, - Process::agent_addition_limit, - ); + // Collect the relevant assets owned by this agent + let agent_assets: Vec = assets + .iter() + .filter_agent(&agent.id) + .filter_region(region_id) + .filter_primary_producers_of(commodity_id) + .cloned() + .collect(); - // Calculate the agent's share of total capacity limits for all processes - let agent_total_limits = collect_agent_limits( - agent, - region_id, - commodity_id, - year, - commodity_portion, - Process::agent_total_limit, - ); + let (options, agent_addition_limits, agent_total_limits) = match mode { + AgentRunMode::Dispatch => ( + AssetOptions { + committed: agent_assets, + existing: Vec::new(), + processes: Vec::new(), + }, + HashMap::new(), + HashMap::new(), + ), + AgentRunMode::Invest => { + // Calculate the agent's share of addition limits for candidate processes + let agent_addition_limits = collect_agent_limits( + agent, + region_id, + commodity_id, + year, + commodity_portion, + Process::agent_addition_limit, + ); + + // Calculate the agent's share of total capacity limits for all processes + let agent_total_limits = collect_agent_limits( + agent, + region_id, + commodity_id, + year, + commodity_portion, + Process::agent_total_limit, + ); + + // Filter available assets and processes before running the agent + let options = AssetOptions { + committed: Vec::new(), + existing: agent_assets + .iter() + .filter(|asset| !excluded_processes.contains(asset.process_id())) + .cloned() + .collect(), + processes: agent + .iter_search_space(region_id, commodity_id, year) + .filter(|process| !excluded_processes.contains(&process.id)) + .cloned() + .collect(), + }; + (options, agent_addition_limits, agent_total_limits) + } + }; // Choose assets from among existing pool and candidates - let select_assets = match agent.agent_type { - AgentType::Competitive => competitive::select_assets, - AgentType::Portfolio => portfolio::select_assets, + let run_agent = match agent.agent_type { + AgentType::Competitive => competitive::run_agent, + AgentType::Portfolio => portfolio::run_agent, }; - let best_assets = select_assets( + let selection = run_agent( model, agent, commodity, region_id, &demand_portion_for_market, - existing_assets, - excluded_processes, + &options, agent_addition_limits, agent_total_limits, prices, year, writer.debug_writer(), )?; - selected_assets.extend(best_assets); + market_selection.extend(selection); } - Ok(selected_assets) + Ok(market_selection) } -/// Iterates through a pre-ordered set of markets forming a cycle, selecting assets for each -/// market in turn. +/// Iterates through a pre-ordered set of markets forming a cycle, running agents for each market in +/// turn. /// -/// `feedback_processes` are producers of cycle markets which consume a market from earlier in the -/// investment order. Assets for these are selected in a first pass over the markets and retained, -/// then the remaining assets are reselected in a second pass excluding feedback processes. A -/// dispatch optimisation is performed after each market is visited in each pass, to calculate the -/// demand which the selected assets place on other markets. +/// `feedback_processes` identifies process-region pairs that produce a cycle market and consume a +/// market earlier in the investment order. In `Invest` mode, assets for these pairs are selected +/// in the first pass and retained, then the remaining assets are selected in a second pass that +/// excludes those processes. In `Dispatch` mode, there is no reselection, so all assets from the +/// first pass are returned. A dispatch optimisation after each market updates demand for subsequent +/// markets. #[allow(clippy::too_many_arguments, clippy::too_many_lines)] -pub fn select_assets_for_cycle( +pub fn run_agents_for_cycle( model: &Model, markets: &[(CommodityID, RegionID)], feedback_processes: &IndexSet<(ProcessID, RegionID)>, year: u32, + mode: AgentRunMode, demand: &AllDemandMap, - existing_assets: &[AssetRef], + assets: &[AssetRef], prices: &Prices, writer: &mut DataWriter, -) -> Result> { +) -> Result { // Precompute a joined string for logging let markets_str = markets.iter().map(|(c, r)| format!("{c}|{r}")).join(", "); + let is_feedback_asset = |asset: &AssetRef| { + feedback_processes.contains(&(asset.process_id().clone(), asset.region_id().clone())) + }; // First pass: iterate over the markets in order, considering all processes let mut net_demand = demand.clone(); let mut assets_for_first_pass = Vec::new(); - let mut retained_first_pass_assets = Vec::new(); + let mut retained_first_pass = Selection::default(); let mut excluded_flows = FlowMap::new(); for market in markets { let (commodity_id, region_id) = market.clone(); // Select assets for this market debug!("Running {commodity_id}|{region_id} selection pass 1"); - let selected_assets = select_assets_for_single_market( + let selection = run_agents_for_single_market( model, &commodity_id, ®ion_id, year, + mode, &net_demand, - existing_assets, + assets, prices, &IndexSet::new(), writer, @@ -277,24 +329,21 @@ pub fn select_assets_for_cycle( debug!("Completed {commodity_id}|{region_id} selection pass 1"); // If no assets have been selected, skip to the next market - if selected_assets.is_empty() { + if selection.is_empty() { debug!("No assets selected for '{commodity_id}|{region_id}'"); continue; } - assets_for_first_pass.extend(selected_assets.iter().cloned()); - retained_first_pass_assets.extend( - selected_assets - .iter() - .filter(|asset| { - feedback_processes - .contains(&(asset.process_id().clone(), asset.region_id().clone())) - }) - .cloned(), - ); + + if mode == AgentRunMode::Invest { + assets_for_first_pass.extend(selection.assets.iter().cloned()); + } + let mut retained = selection.clone(); + retained.retain(|asset| mode == AgentRunMode::Dispatch || is_feedback_asset(asset)); + retained_first_pass.extend(retained); // Run dispatch debug!("Running cycle ({markets_str}) post {commodity_id}|{region_id} investment pass 1"); - let solution = DispatchRun::new(model, &selected_assets, year, &net_demand) + let solution = DispatchRun::new(model, &selection.assets, year, &net_demand) .without_commodity_constraints() .with_market_balance_subset(std::slice::from_ref(market)) .with_input_prices(&prices.shadow) @@ -308,22 +357,25 @@ pub fn select_assets_for_cycle( // Update demand map with flows from newly selected assets let flows = solution.create_flow_map(); for ((asset, commodity_id, time_slice), flow) in &flows { - if feedback_processes.contains(&(asset.process_id().clone(), asset.region_id().clone())) - { + if mode == AgentRunMode::Invest && is_feedback_asset(asset) { excluded_flows .entry((asset.clone(), commodity_id.clone(), time_slice.clone())) .and_modify(|stored_flow| *stored_flow += *flow) .or_insert(*flow); } } - update_net_demand_map(&mut net_demand, &flows, &selected_assets); + update_net_demand_map(&mut net_demand, &flows, &selection.assets); + } + + if mode == AgentRunMode::Dispatch { + return Ok(retained_first_pass); } // Second pass: iterate over the markets in the same order, excluding feedback processes, with // demand updated to account for the flows of feedback assets retained from the first pass let mut net_demand = demand.clone(); update_net_demand_map(&mut net_demand, &excluded_flows, &assets_for_first_pass); - let mut assets_for_second_pass = Vec::new(); + let mut second_pass = Selection::default(); for market in markets { let (commodity_id, region_id) = market.clone(); let feedback_processes: IndexSet = feedback_processes @@ -333,13 +385,14 @@ pub fn select_assets_for_cycle( // Select assets for this market debug!("Running {commodity_id}|{region_id} selection pass 2"); - let selected_assets = select_assets_for_single_market( + let selection = run_agents_for_single_market( model, &commodity_id, ®ion_id, year, + mode, &net_demand, - existing_assets, + assets, prices, &feedback_processes, writer, @@ -347,15 +400,14 @@ pub fn select_assets_for_cycle( debug!("Completed {commodity_id}|{region_id} selection pass 2"); // If no assets have been selected, skip to the next market - if selected_assets.is_empty() { + if selection.is_empty() { debug!("No assets selected for '{commodity_id}|{region_id}'"); continue; } - assets_for_second_pass.extend(selected_assets.iter().cloned()); // Run dispatch debug!("Running cycle ({markets_str}) post {commodity_id}|{region_id} investment pass 2"); - let solution = DispatchRun::new(model, &selected_assets, year, &net_demand) + let solution = DispatchRun::new(model, &selection.assets, year, &net_demand) .without_commodity_constraints() .with_market_balance_subset(std::slice::from_ref(market)) .with_input_prices(&prices.shadow) @@ -370,14 +422,13 @@ pub fn select_assets_for_cycle( update_net_demand_map( &mut net_demand, &solution.create_flow_map(), - &selected_assets, + &selection.assets, ); + second_pass.extend(selection); } - Ok(retained_first_pass_assets - .into_iter() - .chain(assets_for_second_pass) - .collect()) + retained_first_pass.extend(second_pass); + Ok(retained_first_pass) } /// Get a portion of the demand profile for this market diff --git a/src/simulation/optimisation.rs b/src/simulation/optimisation.rs index fd5baf237..6714d50b3 100644 --- a/src/simulation/optimisation.rs +++ b/src/simulation/optimisation.rs @@ -8,6 +8,7 @@ use crate::model::Model; use crate::output::DataWriter; use crate::region::RegionID; use crate::simulation::PriceMap; +use crate::simulation::activity::{FlowMap, create_flow_map}; use crate::simulation::investment::AllDemandMap; use crate::time_slice::{TimeSliceID, TimeSliceInfo, TimeSliceSelection}; use crate::units::{Activity, Flow, Money, MoneyPerActivity, MoneyPerFlow}; @@ -23,9 +24,6 @@ mod constraints; pub(crate) use constraints::group_dispatch_equivalent_assets; use constraints::{ConstraintKeys, add_model_constraints}; -/// A map of commodity flows calculated during the optimisation -pub type FlowMap = IndexMap<(AssetRef, CommodityID, TimeSliceID), Flow>; - /// A decision variable in the optimisation /// /// Note that this type does **not** include the value of the variable; it just refers to a @@ -179,18 +177,7 @@ pub struct Solution<'a> { impl Solution<'_> { /// Create a map of commodity flows for each asset's coeffs at every time slice pub fn create_flow_map(&self) -> FlowMap { - // The decision variables represent assets' activity levels, not commodity flows. We - // multiply this value by the flow coeffs to get commodity flows. - let mut flows = FlowMap::new(); - for (asset, time_slice, activity) in self.iter_activity_for_existing() { - for flow in asset.iter_flows() { - let flow_key = (asset.clone(), flow.commodity.id.clone(), time_slice.clone()); - let flow_value = activity * flow.coeff; - flows.insert(flow_key, flow_value); - } - } - - flows + create_flow_map(self.iter_activity_for_existing()) } /// Activity for all assets (existing and candidate, if present)