muse2/
commodity.rs

1//! Commodities are substances or forms of energy that can be produced and consumed by processes.
2use crate::id::{define_id_getter, define_id_type};
3use crate::region::RegionID;
4use crate::time_slice::{TimeSliceID, TimeSliceLevel, TimeSliceSelection};
5use crate::units::{Flow, MoneyPerFlow};
6use indexmap::IndexMap;
7use serde::Deserialize;
8use serde_string_enum::DeserializeLabeledStringEnum;
9use std::collections::HashMap;
10use std::rc::Rc;
11
12define_id_type! {CommodityID}
13
14/// A map of [`Commodity`]s, keyed by commodity ID
15pub type CommodityMap = IndexMap<CommodityID, Rc<Commodity>>;
16
17/// A map of [`MoneyPerFlow`]s, keyed by region ID, year and time slice ID for a specific levy
18pub type CommodityLevyMap = HashMap<(RegionID, u32, TimeSliceID), MoneyPerFlow>;
19
20/// A map of demand values, keyed by region ID, year and time slice selection
21pub type DemandMap = HashMap<(RegionID, u32, TimeSliceSelection), Flow>;
22
23/// A commodity within the simulation.
24///
25/// Represents a substance (e.g. CO2) or form of energy (e.g. electricity) that can be produced or
26/// consumed by processes.
27#[derive(PartialEq, Debug, Deserialize, Clone)]
28pub struct Commodity {
29    /// Unique identifier for the commodity (e.g. "ELC")
30    pub id: CommodityID,
31    /// Text description of commodity (e.g. "electricity")
32    pub description: String,
33    /// Commodity balance type
34    #[serde(rename = "type")] // NB: we can't name a field type as it's a reserved keyword
35    pub kind: CommodityType,
36    /// The time slice level for commodity balance
37    pub time_slice_level: TimeSliceLevel,
38    /// Production levies for this commodity for different combinations of region, year and time slice.
39    ///
40    /// May be empty if there are no production levies for this commodity, otherwise there must be
41    /// entries for every combination of parameters. Note that these values can be negative,
42    /// indicating an incentive.
43    #[serde(skip)]
44    pub levies_prod: CommodityLevyMap,
45    /// Consumption levies for this commodity for different combinations of region, year and time slice.
46    ///
47    /// May be empty if there are no consumption levies for this commodity, otherwise there must be
48    /// entries for every combination of parameters. Note that these values can be negative,
49    /// indicating an incentive.
50    #[serde(skip)]
51    pub levies_cons: CommodityLevyMap,
52    /// Demand as defined in input files. Will be empty for non-service-demand commodities.
53    ///
54    /// The [`TimeSliceSelection`] part of the key is always at the same [`TimeSliceLevel`] as the
55    /// `time_slice_level` field. E.g. if the `time_slice_level` is seasonal, then there will be
56    /// keys representing each season (and not e.g. individual time slices).
57    #[serde(skip)]
58    pub demand: DemandMap,
59}
60define_id_getter! {Commodity, CommodityID}
61
62/// Type of balance for application of cost
63#[derive(Eq, PartialEq, Clone, Debug, DeserializeLabeledStringEnum, Hash)]
64pub enum BalanceType {
65    /// Applies to production, with an equal and opposite levy/incentive on consumption
66    #[string = "net"]
67    Net,
68    /// Applies to consumption only
69    #[string = "cons"]
70    Consumption,
71    /// Applies to production only
72    #[string = "prod"]
73    Production,
74}
75
76/// Commodity balance type
77#[derive(PartialEq, Debug, DeserializeLabeledStringEnum, Clone)]
78pub enum CommodityType {
79    /// Supply and demand of this commodity must be balanced
80    #[string = "sed"]
81    SupplyEqualsDemand,
82    /// Specifies a demand (specified in input files) which must be met by the simulation
83    #[string = "svd"]
84    ServiceDemand,
85    /// Either an input or an output to the simulation.
86    ///
87    /// This represents a commodity which can either be produced or consumed, but not both.
88    #[string = "oth"]
89    Other,
90}
91
92#[cfg(test)]
93mod tests {
94    use super::*;
95    use crate::time_slice::TimeSliceSelection;
96
97    #[test]
98    fn test_demand_map() {
99        let ts_selection = TimeSliceSelection::Single(TimeSliceID {
100            season: "all-year".into(),
101            time_of_day: "all-day".into(),
102        });
103        let value = Flow(0.25);
104        let mut map = DemandMap::new();
105        map.insert(("North".into(), 2020, ts_selection.clone()), value);
106
107        assert_eq!(map[&("North".into(), 2020, ts_selection)], value)
108    }
109
110    #[test]
111    fn test_commodity_levy_map() {
112        let ts = TimeSliceID {
113            season: "winter".into(),
114            time_of_day: "day".into(),
115        };
116        let value = MoneyPerFlow(0.5);
117        let mut map = CommodityLevyMap::new();
118        assert!(
119            map.insert(("GBR".into(), 2010, ts.clone()), value.clone())
120                .is_none()
121        );
122        assert_eq!(map[&("GBR".into(), 2010, ts)], value);
123    }
124}
muse2/commodity.rs

muse2/
commodity.rs
