muse2/
agent.rs

1//! Agents drive the economy of the MUSE 2.0 simulation, through relative investment in different
2//! assets.
3use crate::commodity::CommodityID;
4use crate::id::define_id_type;
5use crate::process::Process;
6use crate::region::RegionID;
7use crate::units::{Dimensionless, Money};
8use indexmap::{IndexMap, IndexSet};
9use serde_string_enum::DeserializeLabeledStringEnum;
10use std::collections::HashMap;
11use std::rc::Rc;
12
13define_id_type! {AgentID}
14
15/// A map of [`Agent`]s, keyed by agent ID
16pub type AgentMap = IndexMap<AgentID, Agent>;
17
18/// A map of cost limits for an agent, keyed by year
19pub type AgentCostLimitsMap = HashMap<u32, AgentCostLimits>;
20
21/// A map of commodity portions for an agent, keyed by commodity and year
22pub type AgentCommodityPortionsMap = HashMap<(CommodityID, u32), Dimensionless>;
23
24/// A map for the agent's search space, keyed by commodity and year
25pub type AgentSearchSpaceMap = HashMap<(CommodityID, u32), Rc<Vec<Rc<Process>>>>;
26
27/// A map of objectives for an agent, keyed by commodity and year.
28///
29/// NB: As we currently only support the "single" decision rule, the only parameter we need for
30/// objectives is the type.
31pub type AgentObjectiveMap = HashMap<u32, ObjectiveType>;
32
33/// An agent in the simulation
34#[derive(Debug, Clone, PartialEq)]
35pub struct Agent {
36    /// A unique identifier for the agent.
37    pub id: AgentID,
38    /// A text description of the agent.
39    pub description: String,
40    /// The proportion of the commodity production that the agent is responsible for.
41    pub commodity_portions: AgentCommodityPortionsMap,
42    /// The processes that the agent will consider investing in.
43    pub search_space: AgentSearchSpaceMap,
44    /// The decision rule that the agent uses to decide investment.
45    pub decision_rule: DecisionRule,
46    /// Cost limits (e.g. capital cost, annual operating cost)
47    pub cost_limits: AgentCostLimitsMap,
48    /// The regions in which this agent operates.
49    pub regions: IndexSet<RegionID>,
50    /// The agent's objectives.
51    pub objectives: AgentObjectiveMap,
52}
53
54impl Agent {
55    /// Get all the processes in this agent's search space which produce the commodity in the given
56    /// year
57    pub fn iter_possible_producers_of<'a>(
58        &'a self,
59        region_id: &RegionID,
60        commodity_id: &'a CommodityID,
61        year: u32,
62    ) -> impl Iterator<Item = &'a Rc<Process>> + use<'a> {
63        let flows_key = (region_id.clone(), year);
64        self.search_space[&(commodity_id.clone(), year)]
65            .iter()
66            .filter(move |process| process.flows[&flows_key][commodity_id].is_output())
67    }
68}
69
70/// The cost limits for an agent in a particular year
71#[derive(Debug, Clone, PartialEq)]
72pub struct AgentCostLimits {
73    /// The maximum capital cost the agent will pay.
74    pub capex_limit: Option<Money>,
75    /// The maximum annual operating cost (fuel plus var_opex etc) that the agent will pay.
76    pub annual_cost_limit: Option<Money>,
77}
78
79/// The decision rule for a particular objective
80#[derive(Debug, Clone, PartialEq)]
81pub enum DecisionRule {
82    /// Used when there is only a single objective
83    Single,
84    /// A simple weighting of objectives
85    Weighted,
86    /// Objectives are considered in a specific order
87    Lexicographical {
88        /// The tolerance around the main objective to consider secondary objectives. This is an absolute value of maximum deviation in the units of the main objective.
89        tolerance: f64,
90    },
91}
92
93/// The type of objective for the agent
94#[derive(Debug, Clone, Copy, PartialEq, DeserializeLabeledStringEnum)]
95pub enum ObjectiveType {
96    /// Average cost of one unit of output commodity over its lifetime
97    #[string = "lcox"]
98    LevelisedCostOfX,
99    /// Net present value
100    #[string = "npv"]
101    NetPresentValue,
102}
muse2/agent.rs

muse2/
agent.rs
