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, 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    pub kind: CommodityType,
35    /// The time slice level for commodity balance
36    pub time_slice_level: TimeSliceLevel,
37    /// Defines the strategy used for calculating commodity prices
38    pub pricing_strategy: PricingStrategy,
39    /// Production levies for this commodity for different combinations of region, year and time slice.
40    ///
41    /// May be empty if there are no production levies for this commodity, otherwise there must be
42    /// entries for every combination of parameters. Note that these values can be negative,
43    /// indicating an incentive.
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    pub levies_cons: CommodityLevyMap,
51    /// Demand as defined in input files. Will be empty for non-service-demand commodities.
52    ///
53    /// The [`TimeSliceSelection`] part of the key is always at the same [`TimeSliceLevel`] as the
54    /// `time_slice_level` field. E.g. if the `time_slice_level` is seasonal, then there will be
55    /// keys representing each season (and not e.g. individual time slices).
56    pub demand: DemandMap,
57}
58define_id_getter! {Commodity, CommodityID}
59
60/// Type of balance for application of cost
61#[derive(Eq, PartialEq, Clone, Debug, DeserializeLabeledStringEnum, Hash)]
62pub enum BalanceType {
63    /// Applies to production, with an equal and opposite levy/incentive on consumption
64    #[string = "net"]
65    Net,
66    /// Applies to consumption only
67    #[string = "cons"]
68    Consumption,
69    /// Applies to production only
70    #[string = "prod"]
71    Production,
72}
73
74/// Commodity balance type
75#[derive(PartialEq, Debug, DeserializeLabeledStringEnum, Clone)]
76pub enum CommodityType {
77    /// Supply and demand of this commodity must be balanced
78    #[string = "sed"]
79    SupplyEqualsDemand,
80    /// Specifies a demand (specified in input files) which must be met by the simulation
81    #[string = "svd"]
82    ServiceDemand,
83    /// Either an input or an output to the simulation.
84    ///
85    /// This represents a commodity which can either be produced or consumed, but not both.
86    #[string = "oth"]
87    Other,
88}
89
90/// The strategy used for calculating commodity prices
91#[derive(Debug, PartialEq, Clone, Deserialize, Hash, Eq)]
92pub enum PricingStrategy {
93    /// Take commodity prices directly from the shadow prices
94    #[serde(rename = "shadow")]
95    Shadow,
96    /// Adjust shadow prices for scarcity
97    #[serde(rename = "scarcity")]
98    ScarcityAdjusted,
99    /// Use marginal cost of highest-cost active asset producing the commodity
100    #[serde(rename = "marginal")]
101    MarginalCost,
102    /// Use full cost of highest-cost active asset producing the commodity
103    #[serde(rename = "full")]
104    FullCost,
105    /// Commodities that should not have prices calculated
106    #[serde(rename = "unpriced")]
107    Unpriced,
108}
109
110#[cfg(test)]
111mod tests {
112    use super::*;
113    use crate::time_slice::TimeSliceSelection;
114
115    #[test]
116    fn demand_map_works() {
117        let ts_selection = TimeSliceSelection::Single(TimeSliceID {
118            season: "all-year".into(),
119            time_of_day: "all-day".into(),
120        });
121        let value = Flow(0.25);
122        let mut map = DemandMap::new();
123        map.insert(("North".into(), 2020, ts_selection.clone()), value);
124
125        assert_eq!(map[&("North".into(), 2020, ts_selection)], value);
126    }
127
128    #[test]
129    fn commodity_levy_map_works() {
130        let ts = TimeSliceID {
131            season: "winter".into(),
132            time_of_day: "day".into(),
133        };
134        let value = MoneyPerFlow(0.5);
135        let mut map = CommodityLevyMap::new();
136        assert!(
137            map.insert(("GBR".into(), 2010, ts.clone()), value)
138                .is_none()
139        );
140        assert_eq!(map[&("GBR".into(), 2010, ts)], value);
141    }
142}
muse2/commodity.rs

muse2/
commodity.rs
