Rename "commodity costs" to "levies" everywhere

Closes #552.

Author: alexdewar

docs/generate_input_format_doc.py

@@ -13,7 +13,7 @@
     "Regions": ["regions"],
     "Agents": ["agents", "agent_*"],
     "Assets": ["assets"],
-    "Commodities": ["commodities", "commodity_costs", "demand", "demand_slicing"],
+    "Commodities": ["commodities", "commodity_levies", "demand", "demand_slicing"],
     "Processes": ["processes", "process_*"],
 }
 

docs/glossary.md

@@ -41,8 +41,8 @@ capacity can produce 31.536 PJ energy output in a year.
 produced and/or consumed by *Process*es* in the model. A *Service Demand* is a type of commodity
 that is defined at the end point of the system.
 
-**Commodity Cost:** Represents a tax, levy or other external cost on a commodity. Commodity costs
-can be applied to all commodity production (sum of output of all processes for that commodity), net
+**Commodity Levy:** Represents a tax, levy or other external cost on a commodity. Levies can be
+applied to all commodity production (sum of output of all processes for that commodity), net
 production (sum of output and input for all processes), or all consumption (sum of input for all
 processes). It can also be negative, indicating an incentive on commodity
 production/consumption/net.

examples/simple/commodity_costs.csv examples/simple/commodity_levies.csvexamples/simple/commodity_costs.csv renamed to examples/simple/commodity_levies.csv

@@ -1,4 +1,4 @@
-title: Commodity costs
+title: Commodity levies
 description: |
   Defines levies for commodities (or, if `value` is negative, incentives).
 
@@ -31,4 +31,4 @@ fields:
       `net` (applies to consumption and production)
   - name: value
     type: number
-    title: The value of the commodity cost
+    title: The value of the levy/incentive

schemas/input/commodity_costs.yaml schemas/input/commodity_levies.yamlschemas/input/commodity_costs.yaml renamed to schemas/input/commodity_levies.yaml

@@ -13,8 +13,8 @@ define_id_type! {CommodityID}
 /// A map of [`Commodity`]s, keyed by commodity ID
 pub type CommodityMap = IndexMap<CommodityID, Rc<Commodity>>;
 
-/// A map of [`CommodityCost`]s, keyed by region ID, year and time slice ID
-pub type CommodityCostMap = HashMap<(RegionID, u32, TimeSliceID), CommodityCost>;
+/// A map of [`CommodityLevy`]s, keyed by region ID, year and time slice ID
+pub type CommodityLevyMap = HashMap<(RegionID, u32, TimeSliceID), CommodityLevy>;
 
 /// A map of demand values, keyed by region ID, year and time slice selection
 pub type DemandMap = HashMap<(RegionID, u32, TimeSliceSelection), f64>;
@@ -40,7 +40,7 @@ pub struct Commodity {
     /// every combination of parameters. Note that these values can be negative, indicating an
     /// incentive.
     #[serde(skip)]
-    pub costs: CommodityCostMap,
+    pub levies: CommodityLevyMap,
     /// Demand as defined in input files. Will be empty for non-service-demand commodities.
     ///
     /// The [`TimeSliceSelection`] part of the key is always at the same [`TimeSliceLevel`] as the
@@ -67,9 +67,10 @@ pub enum BalanceType {
 
 /// Represents a tax or other external cost on a commodity, as specified in input data.
 ///
-/// For example, a CO2 price could be specified in input data to be applied to net CO2.
+/// For example, a CO2 price could be specified in input data to be applied to net CO2. Note that
+/// the value can also be negative, indicating an incentive.
 #[derive(PartialEq, Clone, Debug)]
-pub struct CommodityCost {
+pub struct CommodityLevy {
     /// Type of balance for application of cost
     pub balance_type: BalanceType,
     /// Cost per unit commodity
@@ -115,16 +116,16 @@ mod tests {
     }
 
     #[test]
-    fn test_commodity_cost_map() {
+    fn test_commodity_levy_map() {
         let ts = TimeSliceID {
             season: "winter".into(),
             time_of_day: "day".into(),
         };
-        let value = CommodityCost {
+        let value = CommodityLevy {
             balance_type: BalanceType::Consumption,
             value: 0.5,
         };
-        let mut map = CommodityCostMap::new();
+        let mut map = CommodityLevyMap::new();
         assert!(map
             .insert(("GBR".into(), 2010, ts.clone()), value.clone())
             .is_none());

src/commodity.rs

@@ -5,7 +5,7 @@ use crate::agent::{
     AgentSearchSpaceMap, DecisionRule,
 };
 use crate::asset::{Asset, AssetPool};
-use crate::commodity::{Commodity, CommodityCostMap, CommodityID, CommodityType, DemandMap};
+use crate::commodity::{Commodity, CommodityID, CommodityLevyMap, CommodityType, DemandMap};
 use crate::process::{
     Process, ProcessEnergyLimitsMap, ProcessFlowsMap, ProcessMap, ProcessParameter,
     ProcessParameterMap,
@@ -62,7 +62,7 @@ pub fn svd_commodity() -> Commodity {
         description: "".into(),
         kind: CommodityType::ServiceDemand,
         time_slice_level: TimeSliceLevel::DayNight,
-        costs: CommodityCostMap::new(),
+        levies: CommodityLevyMap::new(),
         demand: DemandMap::new(),
     }
 }

src/fixture.rs

@@ -194,7 +194,7 @@ mod tests {
     use crate::agent::{
         Agent, AgentCostLimitsMap, AgentObjectiveMap, AgentSearchSpaceMap, DecisionRule,
     };
-    use crate::commodity::{Commodity, CommodityCostMap, CommodityID, CommodityType, DemandMap};
+    use crate::commodity::{Commodity, CommodityID, CommodityLevyMap, CommodityType, DemandMap};
     use crate::time_slice::TimeSliceLevel;
     use std::rc::Rc;
 
@@ -222,7 +222,7 @@ mod tests {
                 description: "A commodity".into(),
                 kind: CommodityType::SupplyEqualsDemand,
                 time_slice_level: TimeSliceLevel::Annual,
-                costs: CommodityCostMap::new(),
+                levies: CommodityLevyMap::new(),
                 demand: DemandMap::new(),
             }),
         )]);
@@ -261,7 +261,7 @@ mod tests {
                 description: "Another commodity".into(),
                 kind: CommodityType::SupplyEqualsDemand,
                 time_slice_level: TimeSliceLevel::Annual,
-                costs: CommodityCostMap::new(),
+                levies: CommodityLevyMap::new(),
                 demand: DemandMap::new(),
             }),
         );

src/input/agent/commodity_portion.rs

@@ -7,8 +7,8 @@ use anyhow::Result;
 use std::collections::HashSet;
 use std::path::Path;
 
-mod cost;
-use cost::read_commodity_costs;
+mod levy;
+use levy::read_commodity_levies;
 mod demand;
 use demand::read_demand;
 mod demand_slicing;
@@ -36,7 +36,7 @@ pub fn read_commodities(
     let commodities =
         read_csv_id_file::<Commodity, CommodityID>(&model_dir.join(COMMODITY_FILE_NAME))?;
     let commodity_ids = commodities.keys().cloned().collect();
-    let mut costs = read_commodity_costs(
+    let mut costs = read_commodity_levies(
         model_dir,
         &commodity_ids,
         region_ids,
@@ -57,7 +57,7 @@ pub fn read_commodities(
         .into_iter()
         .map(|(id, mut commodity)| {
             if let Some(costs) = costs.remove(&id) {
-                commodity.costs = costs;
+                commodity.levies = costs;
             }
             if let Some(demand) = demand.remove(&id) {
                 commodity.demand = demand;

src/input/commodity.rs

@@ -1,6 +1,6 @@
-//! Code for reading in the commodity cost CSV file.
+//! Code for reading in the commodity levies CSV file.
 use super::super::*;
-use crate::commodity::{BalanceType, CommodityCost, CommodityCostMap, CommodityID};
+use crate::commodity::{BalanceType, CommodityID, CommodityLevy, CommodityLevyMap};
 use crate::id::IDCollection;
 use crate::region::{parse_region_str, RegionID};
 use crate::time_slice::TimeSliceInfo;
@@ -10,26 +10,26 @@ use serde::Deserialize;
 use std::collections::{HashMap, HashSet};
 use std::path::Path;
 
-const COMMODITY_COSTS_FILE_NAME: &str = "commodity_costs.csv";
+const COMMODITY_LEVIES_FILE_NAME: &str = "commodity_levies.csv";
 
 /// Cost parameters for each commodity
 #[derive(PartialEq, Debug, Deserialize, Clone)]
-struct CommodityCostRaw {
+struct CommodityLevyRaw {
     /// Unique identifier for the commodity (e.g. "ELC")
     commodity_id: String,
-    /// The region(s) to which the commodity cost applies.
+    /// The region(s) to which the levy applies.
     regions: String,
     /// Type of balance for application of cost.
     balance_type: BalanceType,
     /// The year(s) to which the cost applies.
     years: String,
     /// The time slice to which the cost applies.
     time_slice: String,
-    /// Cost per unit commodity. For example, if a CO2 price is specified in input data, it can be applied to net CO2 via this value.
+    /// Cost per unit commodity
     value: f64,
 }
 
-/// Read costs associated with each commodity from commodity costs CSV file.
+/// Read costs associated with each commodity from levies CSV file.
 ///
 /// # Arguments
 ///
@@ -41,18 +41,18 @@ struct CommodityCostRaw {
 ///
 /// # Returns
 ///
-/// A map containing commodity costs, grouped by commodity ID.
-pub fn read_commodity_costs(
+/// A map containing levies, grouped by commodity ID.
+pub fn read_commodity_levies(
     model_dir: &Path,
     commodity_ids: &HashSet<CommodityID>,
     region_ids: &HashSet<RegionID>,
     time_slice_info: &TimeSliceInfo,
     milestone_years: &[u32],
-) -> Result<HashMap<CommodityID, CommodityCostMap>> {
-    let file_path = model_dir.join(COMMODITY_COSTS_FILE_NAME);
-    let commodity_costs_csv = read_csv::<CommodityCostRaw>(&file_path)?;
-    read_commodity_costs_iter(
-        commodity_costs_csv,
+) -> Result<HashMap<CommodityID, CommodityLevyMap>> {
+    let file_path = model_dir.join(COMMODITY_LEVIES_FILE_NAME);
+    let commodity_levies_csv = read_csv::<CommodityLevyRaw>(&file_path)?;
+    read_commodity_levies_iter(
+        commodity_levies_csv,
         commodity_ids,
         region_ids,
         time_slice_info,
@@ -61,15 +61,15 @@ pub fn read_commodity_costs(
     .with_context(|| input_err_msg(&file_path))
 }
 
-fn read_commodity_costs_iter<I>(
+fn read_commodity_levies_iter<I>(
     iter: I,
     commodity_ids: &HashSet<CommodityID>,
     region_ids: &HashSet<RegionID>,
     time_slice_info: &TimeSliceInfo,
     milestone_years: &[u32],
-) -> Result<HashMap<CommodityID, CommodityCostMap>>
+) -> Result<HashMap<CommodityID, CommodityLevyMap>>
 where
-    I: Iterator<Item = CommodityCostRaw>,
+    I: Iterator<Item = CommodityLevyRaw>,
 {
     let mut map = HashMap::new();
 
@@ -83,13 +83,13 @@ where
         let years = parse_year_str(&cost.years, milestone_years)?;
         let ts_selection = time_slice_info.get_selection(&cost.time_slice)?;
 
-        // Get or create CommodityCostMap for this commodity
+        // Get or create CommodityLevyMap for this commodity
         let map = map
             .entry(commodity_id.clone())
-            .or_insert_with(CommodityCostMap::new);
+            .or_insert_with(CommodityLevyMap::new);
 
-        // Create CommodityCost
-        let cost = CommodityCost {
+        // Create CommodityLevy
+        let cost = CommodityLevy {
             balance_type: cost.balance_type,
             value: cost.value,
         };
@@ -115,14 +115,14 @@ where
     // Validate map
     for (commodity_id, regions) in commodity_regions.iter() {
         let map = map.get(commodity_id).unwrap();
-        validate_commodity_cost_map(map, regions, milestone_years, time_slice_info)
+        validate_commodity_levy_map(map, regions, milestone_years, time_slice_info)
             .with_context(|| format!("Missing costs for commodity {}", commodity_id))?;
     }
     Ok(map)
 }
 
-fn validate_commodity_cost_map(
-    map: &CommodityCostMap,
+fn validate_commodity_levy_map(
+    map: &CommodityLevyMap,
     regions: &HashSet<RegionID>,
     milestone_years: &[u32],
     time_slice_info: &TimeSliceInfo,
@@ -159,58 +159,58 @@ mod tests {
     }
 
     #[fixture]
-    fn cost_map(time_slice: TimeSliceID) -> CommodityCostMap {
-        let cost = CommodityCost {
+    fn cost_map(time_slice: TimeSliceID) -> CommodityLevyMap {
+        let cost = CommodityLevy {
             balance_type: BalanceType::Net,
             value: 1.0,
         };
 
-        let mut map = CommodityCostMap::new();
+        let mut map = CommodityLevyMap::new();
         map.insert(("GBR".into(), 2020, time_slice.clone()), cost.clone());
         map
     }
 
     #[rstest]
-    fn test_validate_commodity_costs_map_valid(
-        cost_map: CommodityCostMap,
+    fn test_validate_commodity_levies_map_valid(
+        cost_map: CommodityLevyMap,
         time_slice_info: TimeSliceInfo,
         region_ids: HashSet<RegionID>,
     ) {
         // Valid map
         assert!(
-            validate_commodity_cost_map(&cost_map, &region_ids, &[2020], &time_slice_info).is_ok()
+            validate_commodity_levy_map(&cost_map, &region_ids, &[2020], &time_slice_info).is_ok()
         );
     }
 
     #[rstest]
-    fn test_validate_commodity_costs_map_invalid_missing_region(
-        cost_map: CommodityCostMap,
+    fn test_validate_commodity_levies_map_invalid_missing_region(
+        cost_map: CommodityLevyMap,
         time_slice_info: TimeSliceInfo,
     ) {
         // Missing region
         let region_ids = HashSet::from(["GBR".into(), "FRA".into()]);
         assert_error!(
-            validate_commodity_cost_map(&cost_map, &region_ids, &[2020], &time_slice_info),
+            validate_commodity_levy_map(&cost_map, &region_ids, &[2020], &time_slice_info),
             "Missing cost for region FRA, year 2020, time slice winter.day"
         );
     }
 
     #[rstest]
-    fn test_validate_commodity_costs_map_invalid_missing_year(
-        cost_map: CommodityCostMap,
+    fn test_validate_commodity_levies_map_invalid_missing_year(
+        cost_map: CommodityLevyMap,
         time_slice_info: TimeSliceInfo,
         region_ids: HashSet<RegionID>,
     ) {
         // Missing year
         assert_error!(
-            validate_commodity_cost_map(&cost_map, &region_ids, &[2020, 2030], &time_slice_info),
+            validate_commodity_levy_map(&cost_map, &region_ids, &[2020, 2030], &time_slice_info),
             "Missing cost for region GBR, year 2030, time slice winter.day"
         );
     }
 
     #[rstest]
-    fn test_validate_commodity_costs_map_invalid(
-        cost_map: CommodityCostMap,
+    fn test_validate_commodity_levies_map_invalid(
+        cost_map: CommodityLevyMap,
         region_ids: HashSet<RegionID>,
     ) {
         // Missing time slice
@@ -224,7 +224,7 @@ mod tests {
             time_slices: [(time_slice.clone(), 0.5), (time_slice.clone(), 0.5)].into(),
         };
         assert_error!(
-            validate_commodity_cost_map(&cost_map, &region_ids, &[2020], &time_slice_info),
+            validate_commodity_levy_map(&cost_map, &region_ids, &[2020], &time_slice_info),
             "Missing cost for region GBR, year 2020, time slice winter.night"
         );
     }

src/input/commodity/cost.rs src/input/commodity/levy.rssrc/input/commodity/cost.rs renamed to src/input/commodity/levy.rs

@@ -280,7 +280,7 @@ fn validate_svd_commodity(
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::commodity::{CommodityCostMap, DemandMap};
+    use crate::commodity::{CommodityLevyMap, DemandMap};
     use crate::fixture::{time_slice, time_slice_info};
     use crate::process::{FlowType, ProcessFlow};
     use crate::time_slice::{TimeSliceID, TimeSliceLevel};
@@ -294,7 +294,7 @@ mod tests {
             description: "SED commodity".into(),
             kind: CommodityType::SupplyEqualsDemand,
             time_slice_level: TimeSliceLevel::Annual,
-            costs: CommodityCostMap::new(),
+            levies: CommodityLevyMap::new(),
             demand: DemandMap::new(),
         }
     }
@@ -367,7 +367,7 @@ mod tests {
             description: "SVD commodity".into(),
             kind: CommodityType::ServiceDemand,
             time_slice_level: TimeSliceLevel::Annual,
-            costs: CommodityCostMap::new(),
+            levies: CommodityLevyMap::new(),
             demand,
         }
     }