muse2/input/

asset.rs

//! Code for reading user assets from a CSV file.
use super::{input_err_msg, read_csv_optional};
use crate::agent::AgentID;
use crate::asset::{AssetCapacity, UserAsset};
use crate::id::{GetIDValue, IDCollection};
use crate::process::ProcessMap;
use crate::region::RegionID;
use crate::units::Capacity;
use anyhow::{Context, Result, ensure};
use float_cmp::approx_eq;
use indexmap::IndexSet;
use itertools::Itertools;
use log::warn;
use serde::Deserialize;
use std::path::Path;
use std::sync::Arc;

const ASSETS_FILE_NAME: &str = "assets.csv";

#[derive(Deserialize, PartialEq)]
struct AssetRaw {
    process_id: String,
    region_id: String,
    agent_id: String,
    capacity: Capacity,
    #[serde(default)]
    num_tranches: Option<u32>,
    commission_year: u32,
    #[serde(default)]
    max_decommission_year: Option<u32>,
}

/// Read assets CSV file from model directory.
///
/// # Arguments
///
/// * `model_dir` - Folder containing model configuration files
/// * `agent_ids` - All possible agent IDs
/// * `processes` - The model's processes
/// * `region_ids` - All possible region IDs
///
/// # Returns
///
/// A `Vec` of [`UserAsset`]s or an error.
pub fn read_user_assets(
    model_dir: &Path,
    agent_ids: &IndexSet<AgentID>,
    processes: &ProcessMap,
    region_ids: &IndexSet<RegionID>,
) -> Result<Vec<UserAsset>> {
    let file_path = model_dir.join(ASSETS_FILE_NAME);
    let assets_csv = read_csv_optional(&file_path)?;
    read_assets_from_iter(assets_csv, agent_ids, processes, region_ids)
        .with_context(|| input_err_msg(&file_path))
}

/// Process assets from an iterator.
///
/// # Arguments
///
/// * `iter` - Iterator of `AssetRaw`s
/// * `agent_ids` - All possible agent IDs
/// * `processes` - The model's processes
/// * `region_ids` - All possible region IDs
///
/// # Returns
///
/// A [`Vec`] of [`UserAsset`]s or an error.
fn read_assets_from_iter<I>(
    iter: I,
    agent_ids: &IndexSet<AgentID>,
    processes: &ProcessMap,
    region_ids: &IndexSet<RegionID>,
) -> Result<Vec<UserAsset>>
where
    I: Iterator<Item = AssetRaw>,
{
    iter.map(|asset| -> Result<_> {
        let agent_id = agent_ids.get_id(&asset.agent_id)?;
        let (process_id, process) = processes
            .get_id_value(&asset.process_id)?;
        let region_id = region_ids.get_id(&asset.region_id)?;

        // Validate commission year. It should be within the process valid range...
        ensure!(
            process.years.contains(&asset.commission_year),
            "Agent {} has asset with commission year {}, not within process {} commission years: {:?}",
            asset.agent_id,
            asset.commission_year,
            process_id,
            process.years
        );
        // ... and also have associated process parameters and flows
        ensure!(
            process.parameters.contains_key(&(region_id.clone(), asset.commission_year)),
            "Parameters for process {} do not contain entry for year {}, required for asset in agent {}",
            process_id,
            asset.commission_year,
            asset.agent_id,
        );
        ensure!(
            process.flows.contains_key(&(region_id.clone(), asset.commission_year)),
            "Flows for process {} do not contain entry for year {}, required for asset in agent {}",
            process_id,
            asset.commission_year,
            asset.agent_id,
        );

        // Split overall capacity into tranches
        ensure!(
            asset.capacity > Capacity(0.0),
            "Asset capacity must be positive"
        );
        let asset_capacity = if let Some(num_tranches) = asset.num_tranches {
            // A provided tranche count takes precedence over the process tranche_size.
            ensure!(num_tranches > 0, "num_tranches must be positive");

            let tranche_size = Capacity(asset.capacity.value() / num_tranches as f64);
            AssetCapacity::new(num_tranches, tranche_size)
        } else if let Some(tranche_size) = process.tranche_size {
            // No tranche count was provided, so use the process tranche_size to determine
            // how many tranches are needed to cover the asset's capacity.
            let ratio = (asset.capacity / tranche_size).value();
            let num_tranches = ratio.ceil();

            // Rounding up can increase the combined capacity of the resulting tranches.
            if !approx_eq!(f64, ratio, ratio.ceil()) {
                warn!(
                    "Asset capacity {} for process {} is not a multiple of tranche size {}. \
                    Asset will be divided into {} tranches with combined capacity of {}.",
                    asset.capacity,
                    process_id,
                    tranche_size,
                    num_tranches,
                    tranche_size.value() * num_tranches
                );
            }

            #[allow(clippy::cast_sign_loss, clippy::cast_possible_truncation)]
            AssetCapacity::new(num_tranches as u32, tranche_size)
        } else {
            // Without a process tranche_size, lack of num_tranches implies the asset is indivisible
            // (consists of a single tranche).
            AssetCapacity::single(asset.capacity)
        };

        UserAsset::new(
            agent_id.clone(),
            Arc::clone(process),
            region_id.clone(),
            asset_capacity,
            asset.commission_year,
            asset.max_decommission_year,
        )
    })
    .try_collect()
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::fixture::{processes, region_ids};

    use itertools::assert_equal;
    use rstest::{fixture, rstest};
    use std::iter;

    #[fixture]
    fn agent_ids() -> IndexSet<AgentID> {
        IndexSet::from(["agent1".into()])
    }

    #[rstest]
    #[case::max_decommission_year_provided(Some(2015))]
    #[case::max_decommission_year_not_provided(None)]
    fn read_assets_from_iter_valid(
        #[case] max_decommission_year: Option<u32>,
        agent_ids: IndexSet<AgentID>,
        processes: ProcessMap,
        region_ids: IndexSet<RegionID>,
    ) {
        let asset_in = AssetRaw {
            agent_id: "agent1".into(),
            process_id: "process1".into(),
            region_id: "GBR".into(),
            capacity: Capacity(1.0),
            num_tranches: Some(1),
            commission_year: 2010,
            max_decommission_year,
        };
        let asset_out = UserAsset::new(
            "agent1".into(),
            Arc::clone(processes.values().next().unwrap()),
            "GBR".into(),
            AssetCapacity::single(Capacity(1.0)),
            2010,
            max_decommission_year,
        )
        .unwrap();
        assert_equal(
            read_assets_from_iter(iter::once(asset_in), &agent_ids, &processes, &region_ids)
                .unwrap(),
            iter::once(asset_out),
        );
    }

    #[rstest]
    fn explicit_tranche_count_sets_tranche_size(
        agent_ids: IndexSet<AgentID>,
        processes: ProcessMap,
        region_ids: IndexSet<RegionID>,
    ) {
        let asset = AssetRaw {
            process_id: "process1".into(),
            region_id: "GBR".into(),
            agent_id: "agent1".into(),
            capacity: Capacity(6.0),
            num_tranches: Some(3),
            commission_year: 2010,
            max_decommission_year: None,
        };

        let assets =
            read_assets_from_iter(iter::once(asset), &agent_ids, &processes, &region_ids).unwrap();

        assert_eq!(assets[0].capacity(), AssetCapacity::new(3, Capacity(2.0)));
    }

    #[rstest]
    fn missing_tranche_count_uses_process_tranche_size(
        agent_ids: IndexSet<AgentID>,
        mut processes: ProcessMap,
        region_ids: IndexSet<RegionID>,
    ) {
        Arc::get_mut(processes.get_mut("process1").unwrap())
            .unwrap()
            .tranche_size = Some(Capacity(4.0));
        let asset = AssetRaw {
            process_id: "process1".into(),
            region_id: "GBR".into(),
            agent_id: "agent1".into(),
            capacity: Capacity(9.0),
            num_tranches: None,
            commission_year: 2010,
            max_decommission_year: None,
        };

        let assets =
            read_assets_from_iter(iter::once(asset), &agent_ids, &processes, &region_ids).unwrap();

        assert_eq!(assets[0].capacity(), AssetCapacity::new(3, Capacity(4.0)));
    }

    #[rstest]
    #[case(AssetRaw { // Bad process ID
            agent_id: "agent1".into(),
            process_id: "process2".into(),
            region_id: "GBR".into(),
            capacity: Capacity(1.0),
            num_tranches: None,
            commission_year: 2010,
            max_decommission_year: None,
        })]
    #[case(AssetRaw { // Bad agent ID
            agent_id: "agent2".into(),
            process_id: "process1".into(),
            region_id: "GBR".into(),
            capacity: Capacity(1.0),
            num_tranches: None,
            commission_year: 2010,
            max_decommission_year: None,
        })]
    #[case(AssetRaw { // Bad region ID: not in region_ids
            agent_id: "agent1".into(),
            process_id: "process1".into(),
            region_id: "FRA".into(),
            capacity: Capacity(1.0),
            num_tranches: None,
            commission_year: 2010,
            max_decommission_year: None,
        })]
    #[case(AssetRaw { // Bad max_decommission_year: before commission_year
            agent_id: "agent1".into(),
            process_id: "process1".into(),
            region_id: "GBR".into(),
            capacity: Capacity(1.0),
            num_tranches: None,
            commission_year: 2010,
            max_decommission_year: Some(2005),
        })]
    #[case(AssetRaw { // Bad max_decommission_year: equal to commission_year
            agent_id: "agent1".into(),
            process_id: "process1".into(),
            region_id: "GBR".into(),
            capacity: Capacity(1.0),
            num_tranches: None,
            commission_year: 2010,
            max_decommission_year: Some(2010),
        })]
    fn read_assets_from_iter_invalid(
        #[case] asset: AssetRaw,
        agent_ids: IndexSet<AgentID>,
        processes: ProcessMap,
        region_ids: IndexSet<RegionID>,
    ) {
        read_assets_from_iter(iter::once(asset), &agent_ids, &processes, &region_ids).unwrap_err();
    }
}