MESSAGEix-Materials (`model.material`)

Description

This module adds material stock and flow accounting in MESSAGEix-GLOBIOM. The implementation currently includes four key energy/emission-intensive material industries: Iron&Steel, Aluminum, Cement, and Chemicals.

Code reference

Note

See also PR #130/the archived branch materials-migrate for a distinct version of material. That earlier PR was superseded by PR #188, but contains the 1.0.0 version of MESSAGEix-Materials, which was used for the first submission of [120]. The model structure is almost identical to the default model that was added by PR #188. Compared to PR #188 this version differs particularly in the following areas:

Older base year calibration of “other industries” using outdated IEA EWEB data.
Material demands computed in R through rpy2, instead of Python implementation.
Less accurate regional allocation/aggregation of base year demands for cement and steel.
No use of tools.costs.

Data preparation

These scripts are used to prepare and read the data into the model. They can be turned on and off individually under DATA_FUNCTIONS in __init__.py.

Data and parameter generation for the aluminum sector in MESSAGEix-Materials model.

This module provides functions to read, process, and generate parameter data for aluminum technologies, demand, trade, and related constraints.

message_ix_models.model.material.data_aluminum.assign_input_outpt(split, param_name: str, regions: DataFrame, val, t: str, rg: str, glb_reg: str, common: dict, yv_ya: DataFrame, nodes)[source]

Assign input/output or emission_factor parameters for aluminum technologies.

Parameters:

split (list) – Split parameter name.
param_name (str) – Parameter name.
regions (pd.DataFrame) – Regions for the parameter.
val (pd.Series) – Parameter values.
t (str) – Technology name.
rg (str) – Region.
glb_reg (str) – Global region.
common (dict) – Common parameter dictionary.
yv_ya (pd.DataFrame) – Year vintage/active combinations.
nodes (list) – Model nodes.

Returns:

Parameter DataFrame.

Return type:

pd.DataFrame

message_ix_models.model.material.data_aluminum.calibrate_2020_furnaces(s_info)[source]

Calibrate 2020 furnace activity for aluminum refining by fuel.

Parameters:: s_info (ScenarioInfo) – Scenario information object.
Returns:: Dictionary with ‘bound_activity_lo’ and ‘bound_activity_up’ DataFrames.
Return type:: dict

message_ix_models.model.material.data_aluminum.compute_differences(df, ref_col)[source]

Compute positive differences between columns and a reference column.

Parameters:

df (pd.DataFrame) – DataFrame with columns to compare.
ref_col (int or str) – Reference column.

Returns:

DataFrame of positive differences.

Return type:

pd.DataFrame

message_ix_models.model.material.data_aluminum.gen_2020_growth_constraints(s_info)[source]

Generate 2020 growth constraints for soderberg aluminum smelters.

Parameters:: s_info (ScenarioInfo) – Scenario information object.
Returns:: Dictionary with ‘growth_activity_up’ DataFrame.
Return type:: dict

message_ix_models.model.material.data_aluminum.gen_alumina_trade_tecs(s_info)[source]

Generate trade technology parameter data for alumina.

Parameters:: s_info (ScenarioInfo) – Scenario information object.
Returns:: Dictionary of trade technology parameter DataFrames.
Return type:: dict

message_ix_models.model.material.data_aluminum.gen_data_alu_const(data: DataFrame, config: dict, glb_reg: str, years: Iterable, yv_ya: DataFrame, nodes: list[str])[source]

Generate time-independent (constant) parameter data for aluminum technologies.

Parameters:

data (pd.DataFrame) – Constant parameter data.
config (dict) – Technology configuration.
glb_reg (str) – Global region.
years (Iterable) – Model years.
yv_ya (pd.DataFrame) – Year vintage/active combinations.
nodes (list[str]) – Model nodes.

Returns:

Key-value pairs of parameter names and parameter data.

Return type:

dict[str, pd.DataFrame]

message_ix_models.model.material.data_aluminum.gen_data_alu_rel(data: DataFrame, years: list) → dict[str, DataFrame][source]

Generate relation parameter data for the aluminum sector.

Parameters:

data (pd.DataFrame) – Relation data from input file.
years (list) – Model years.

Returns:

Key-value pairs of relation parameter names and data.

Return type:

dict[str, pd.DataFrame]

message_ix_models.model.material.data_aluminum.gen_data_alu_trade(scenario: Scenario) → dict[str, DataFrame][source]

Generate trade-related parameter data for aluminum.

Parameters:: scenario – Scenario instance.
Returns:: Key-value pairs of trade parameter names and data.
Return type:: dict[str, pd.DataFrame]

message_ix_models.model.material.data_aluminum.gen_data_alu_ts(data: DataFrame, nodes: list) → dict[str, DataFrame][source]

Generate time-variable parameter data for the aluminum sector.

Parameters:

data (pd.DataFrame) – Time-variable data from input file.
nodes (list) – Regions of the model.

Returns:

Key-value pairs of parameter names and parameter data.

Return type:

dict[str, pd.DataFrame]

message_ix_models.model.material.data_aluminum.gen_data_aluminum(scenario: Scenario, dry_run: bool = False) → ParameterData[source]

Generate all MESSAGEix parameter data for the aluminum sector.

Parameters:

scenario – Scenario instance to build aluminum model on.
dry_run (bool) – Not implemented.

Returns:

Dictionary with MESSAGEix parameters as keys and parametrization as values.

Return type:

dict[str, pd.DataFrame]

message_ix_models.model.material.data_aluminum.gen_demand(scenario, ssp)[source]

Generate aluminum demand parameter data.

Parameters:

scenario ("Scenario") – Scenario instance.
ssp (str) – Shared Socioeconomic Pathway.

Returns:

Dictionary with ‘demand’ parameter DataFrame.

Return type:

dict

message_ix_models.model.material.data_aluminum.gen_hist_new_cap(s_info)[source]

Generate historical new capacity data for aluminum smelters.

Parameters:: s_info (ScenarioInfo) – Scenario information object.
Returns:: Dictionary with ‘historical_new_capacity’ and ‘fixed_new_capacity’ DataFrames.
Return type:: dict

message_ix_models.model.material.data_aluminum.gen_max_recycling_rel(s_info, ssp)[source]

Generate parametrization for maximum recycling relation.

Parameters:

s_info (ScenarioInfo) – Scenario information object.
ssp (str) – Shared Socioeconomic Pathway.

Returns:

Dictionary with ‘relation_activity’ DataFrame.

Return type:

dict

message_ix_models.model.material.data_aluminum.gen_refining_hist_act()[source]

Generate historical activity and 2020 bounds for alumina refining technologies.

Returns:: Dict with ‘historical_activity’, ‘bound_activity_lo’, and ‘bound_activity_up’.
Return type:: dict

message_ix_models.model.material.data_aluminum.gen_refining_input(s_info)[source]

Generate input parameter for aluminum refining technology.

Parameters:: s_info (ScenarioInfo) – Scenario information object.
Returns:: Dictionary with ‘input’ parameter DataFrame.
Return type:: dict

message_ix_models.model.material.data_aluminum.gen_scrap_prep_heat(s_info, ssp)[source]

Generate heat input parametrization for aluminum scrap preparation.

Parameters:

s_info (ScenarioInfo) – Scenario information object.
ssp (str) – Shared Socioeconomic Pathway.

Returns:

Dictionary with ‘input’ parameter DataFrame.

Return type:

dict

message_ix_models.model.material.data_aluminum.gen_smelting_hist_act()[source]

Generate historical activity and bounds for aluminum smelting technologies.

Returns:: Dict with ‘historical_activity’, ‘bound_activity_up’, and ‘bound_activity_lo’.
Return type:: dict

message_ix_models.model.material.data_aluminum.gen_trade_growth_constraints(s_info)[source]

Generate growth and initial activity constraints for aluminum and alumina trade.

Parameters:: s_info (ScenarioInfo) – Scenario information object.
Returns:: Dictionary of growth and initial activity constraints.
Return type:: dict

message_ix_models.model.material.data_aluminum.get_scrap_prep_cost(s_info, ssp)[source]

Generate variable cost parametrization for aluminum scrap preparation.

Parameters:

s_info (ScenarioInfo) – Scenario information object.
ssp (str) – Shared Socioeconomic Pathway.

Returns:

Dictionary with ‘var_cost’ parameter DataFrame.

Return type:

dict

message_ix_models.model.material.data_aluminum.load_bgs_data(commodity: Literal['aluminum', 'alumina'])[source]

Load and format BGS production data for aluminum or alumina.

Parameters:: commodity (Literal[``”aluminum”, ``"alumina"]) – Commodity to load.
Returns:: Formatted production data.
Return type:: pd.DataFrame

message_ix_models.model.material.data_aluminum.read_data_aluminum(scenario: Scenario) → tuple[DataFrame, DataFrame, DataFrame][source]

Read and clean data from aluminum techno-economic and timeseries files.

Parameters:: scenario – Scenario instance to build aluminum on.
Returns:: Aluminum data in three separate groups: - time independent parameters, - relation parameters, - time dependent parameters.
Return type:: tuple of three pd.DataFrames

Data and parameter generation for the steel sector in MESSAGEix models.

This module provides functions to read, process, and generate parameter data for steel technologies, demand, recycling, CCS, trade and related constraints.

message_ix_models.model.material.data_steel.gen_2020_calibration_relation(s_info: ScenarioInfo, tech: Literal['eaf', 'bof', 'bf']) → dict[str, DataFrame][source]

Generate generic relation data to calibrate 2020 steel production by process.

Parameters:: tech – Steel technology for which to generate historical activity data.

message_ix_models.model.material.data_steel.gen_bof_pig_input(s_info: ScenarioInfo) → ParameterData[source]

Generate BOF feed input coefficients.

Assume 20% scrap share for regions (except CHN and EEU until 2030). EEU needs higher share in 2020 to be feasible with calibrated pig availability. CHN uses less scrap and more pig iron due to high BF activity.

Returns:: Dictionary with ‘input’ parameter DataFrame.
Return type:: dict

message_ix_models.model.material.data_steel.gen_charcoal_bf_bound(s_info: ScenarioInfo) → dict[str, DataFrame][source]

Generate bound activity for blast furnace modes with charcoal input of 0 to calibrate to statistics.

Returns:: Dictionary with ‘bound_activity_up’ parameter DataFrame.
Return type:: dict

message_ix_models.model.material.data_steel.gen_cokeoven_co2_cc(s_info: ScenarioInfo)[source]

Generate relation_activity for CO2 emissions from coke ovens.

Returns:: DataFrame with relation_activity for CO2.
Return type:: pd.DataFrame

message_ix_models.model.material.data_steel.gen_data_steel(scenario: Scenario, dry_run: bool = False)[source]

Generate all MESSAGEix parameter data for the steel sector.

Parameters:

scenario – Scenario instance to build steel model on.
dry_run – If True, do not perform any file writing or scenario modification.

Returns:

Dictionary with MESSAGEix parameters as keys and parametrization as values.

Return type:

dict

message_ix_models.model.material.data_steel.gen_data_steel_rel(data_steel_rel: DataFrame, results: dict, regions: set[str], modelyears: list[int])[source]

Generate relation parameter data for steel sector.

Parameters:

data_steel_rel – DataFrame with relation parameter data.
results – Dictionary to collect parameter DataFrames.
regions – Iterable of region names.
modelyears – List of model years.

message_ix_models.model.material.data_steel.gen_data_steel_ts(data_steel_ts: DataFrame, results: dict[str, list], t: str, nodes: list[str])[source]

Generate time-series parameter data for steel technologies.

Parameters:

data_steel_ts – DataFrame with time-series parameter data.
results – Dictionary to collect parameter DataFrames.
t – Technology name.
nodes – List of model nodes.

message_ix_models.model.material.data_steel.gen_demand(ssp: str) → DataFrame[source]

Generate steel demand DataFrame for the given SSP scenario.

Combines calibrated 2020 and 2025 demand with SSP dependent demand projection.

Returns:: ‘demand’ parameter DataFrame.
Return type:: pd.DataFrame

message_ix_models.model.material.data_steel.gen_dri_act_bound() → dict[str, DataFrame][source]

Read historical DRI activity data of R12 regions: for historical_activity and bound activity parameter.

message_ix_models.model.material.data_steel.gen_dri_cap_calibration() → dict[str, DataFrame][source]

Read historical new DRI capacity data of R12 regions: for historical_activity and bound activity parameter.

message_ix_models.model.material.data_steel.gen_dri_coal_model(s_info: ScenarioInfo)[source]: Generate techno-economic coal based DRI technology model parameters.

message_ix_models.model.material.data_steel.gen_finishing_steel_io(s_info: ScenarioInfo) → dict[str, DataFrame][source]

Generate output parameters for steel finishing process.

The output ratios are derived from worldsteel statistics of 2020.

Returns:: Dictionary with ‘output’ parameter DataFrame.
Return type:: dict

message_ix_models.model.material.data_steel.gen_grow_cap_up(s_info: ScenarioInfo, ssp)[source]

Generate growth constraints for new steel CCS capacity.

Returns:: Dictionary with ‘growth_new_capacity_up’ parameter DataFrame.
Return type:: dict

message_ix_models.model.material.data_steel.gen_iron_ore_cost(s_info: ScenarioInfo, ssp: str) → dict[str, DataFrame][source]

Generate variable cost parameter for iron ore supply based on SSP narrative.

Returns:: Dictionary with ‘var_cost’ parameter DataFrame.
Return type:: dict

message_ix_models.model.material.data_steel.gen_manuf_steel_io(ratio: dict[str, float], s_info: ScenarioInfo) → dict[str, DataFrame][source]

Generate output parameters for steel manufacturing process.

Parameters:: ratio – Map of new scrap yield ratio in manufacturing for each region.
Returns:: Dictionary with ‘output’ parameter DataFrame.
Return type:: dict

message_ix_models.model.material.data_steel.gen_max_recycling_rel(s_info: ScenarioInfo, ssp)[source]

Generate maximum recycling relation activity for steel.

Returns:: Dictionary with ‘relation_activity’ DataFrame.
Return type:: dict

message_ix_models.model.material.data_steel.gen_mock_demand_steel(scenario: Scenario) → DataFrame[source]

Generate mock steel demand time series for MESSAGEix regions. ** Not used anymore **

Parameters:: scenario – Scenario instance to build steel demand on.
Returns:: DataFrame with columns [‘node’, ‘year’, ‘value’] for steel demand.
Return type:: pd.DataFrame

message_ix_models.model.material.data_steel.gen_ssp_demand(ssp: str) → DataFrame[source]

Generate steel demand projections based on SSP scenarios.

Timeseries is currently read from pre-computed data file.

Returns:: ‘demand’ parameter DataFrame.
Return type:: pd.DataFrame

message_ix_models.model.material.data_steel.get_data_steel_const(data_steel: DataFrame, results: dict[str, list], params: Iterable, t: str, yv_ya: DataFrame, nodes: list[str], global_region: str)[source]

Generate time-independent (constant) parameter data for steel technologies.

Parameters:

data_steel – DataFrame with constant parameter data.
results – Dictionary to collect parameter DataFrames.
params – Iterable of parameter names.
t – Technology name.
yv_ya – DataFrame with year vintage and year active combinations.
nodes – List of model nodes.
global_region – Name of the global region.

message_ix_models.model.material.data_steel.get_scrap_prep_cost(s_info: ScenarioInfo, ssp: str) → ParameterData[source]

Generate variable cost parameter for steel scrap preparation technologies.

Returns:: Dictionary with ‘var_cost’ parameter DataFrame.
Return type:: dict

message_ix_models.model.material.data_steel.read_hist_cap(tec: Literal['eaf', 'bof', 'bf']) → dict[str, DataFrame][source]

Read historical new capacity data for a given technology.

Parameters:: tec – Steel technology for which to read historical capacity data.
Returns:: Dictionary with ‘historical_new_capacity’ parameter DataFrame.
Return type:: dict

message_ix_models.model.material.data_steel.scale_fse_demand(demand: DataFrame, new_scrap_ratio: dict[str, float])[source]

Helper function to convert crude steel demand to finished steel demand by scaling with new scrap ratio.

Parameters:

demand – Steel demand projection data.
new_scrap_ratio – Map of new scrap ratios for each region.

Data input, processing, and parameter generation for the cement sector.

message_ix_models.model.material.data_cement.drop_redundant_rows(results: ParameterData) → MutableParameterData[source]

Drop duplicate row and those where \(y^A - y^V > 25\) years.

Parameters:: results – A dictionary of dataframes with parameter names as keys.
Return type:: ParameterData

message_ix_models.model.material.data_cement.gen_addon_conv_ccs(nodes: list[str], years: list[int]) → ParameterData[source]: Generate addon conversion parameters for clinker CCS cement.

message_ix_models.model.material.data_cement.gen_clinker_ratios(s_info: ScenarioInfo) → ParameterData[source]

Generate regionally differentiated clinker input for cement production.

2020 ratios taken from doi:10.1016/j.ijggc.2024.104280, Appendix B.

message_ix_models.model.material.data_cement.gen_data_cement(scenario: Scenario, dry_run: bool = False) → ParameterData[source]

Generate data for materials representation of cement industry.

Parameters:

scenario (message_ix.Scenario)
dry_run (bool)

Return type:

dict[str, pd.DataFrame]

message_ix_models.model.material.data_cement.gen_grow_cap_up(s_info: ScenarioInfo, ssp: str) → ParameterData[source]: Generate growth constraints for new clinker CCS capacity.

message_ix_models.model.material.data_cement.read_furnace_2020_bound() → ParameterData[source]: Read the 2020 bound activity data for cement.

Data and parameter generation for the petrochemicals sector in MESSAGEix models.

This module provides functions to read, process, and generate parameter data for petrochemical technologies, demand, trade, emissions, and related constraints.

message_ix_models.model.material.data_petro.assign_input_outpt(split: str, param_name: str, regions: DataFrame, val: float | int, t: str, rg: str, global_region: str, common: dict, nodes: list[str]) → DataFrame[source]

Assign input/output parameters for petrochemical technologies.

Parameters:

split – Split parameter name.
param_name – Parameter name.
regions – Regions for the parameter.
val – Parameter values.
t – Technology name.
rg – Region name
global_region – Name of the global region.
common – Common parameter dictionary.
nodes – Model nodes.

message_ix_models.model.material.data_petro.broadcast_to_regions(df: DataFrame, global_region: str, nodes: list[str])[source]

Broadcast a DataFrame to all regions if node_loc is not the global region.

Parameters:

df – DataFrame to broadcast regions.
global_region – Name of the global region.
nodes – List of model nodes.

message_ix_models.model.material.data_petro.gen_data_petro_chemicals(scenario: Scenario, dry_run: bool = False) → ParameterData[source]

Generate all MESSAGEix parameter data for the petrochemicals sector.

Parameters:

scenario – Scenario instance to build petrochemicals model on.
dry_run – Not used, but kept for compatibility.

message_ix_models.model.material.data_petro.gen_data_petro_ts(data_petro_ts: DataFrame, results: dict[list], tec_ts: set[str], nodes: list[str]) → None[source]

Generate time-series parameter data for petrochemical technologies.

Parameters:

data_petro_ts – DataFrame with time-series parameter data.
results – Dictionary to collect parameter DataFrames.
tec_ts – Set of technology names.
nodes – List of model nodes.

message_ix_models.model.material.data_petro.gen_mock_demand_petro(scenario: Scenario, gdp_elasticity_2020: float, gdp_elasticity_2030: float) → DataFrame[source]

Generate petrochemicals demand time series for MESSAGEix regions using GDP elasticities.

TODO: Remove this function since a copy was moved to demand.

Parameters:

scenario – Scenario instance to build demand on.
gdp_elasticity_2020 – GDP elasticity for years before 2030.
gdp_elasticity_2030 – GDP elasticity for years from 2030 onward.

Returns:

DataFrame with demand for petrochemicals by region and year.

Return type:

pd.DataFrame

message_ix_models.model.material.data_petro.read_data_petrochemicals(fname) → DataFrame[source]

Read and clean data from the petrochemicals techno-economic files.

Returns:: Cleaned techno-economic data for petrochemicals.
Return type:: pd.DataFrame

message_ix_models.model.material.data_power_sector.gen_data_power_sector(scenario: Scenario, dry_run: bool = False) → dict[str, DataFrame][source]: Generate data for materials representation of power industry.

Data and parameter generation for generic furnace and boiler technologies in MESSAGEix-Materials model.

This module provides functions to read, process, and generate parameter data for generic furnace and boiler technologies, including emission coefficients and generic relations.

message_ix_models.model.material.data_generic.add_ind_therm_link_relations(tecs: List[str], years: List[str], nodes: List[str])[source]

Generate industrial thermal demand link relation values for given technologies.

Parameters:

tecs – List of technology names.
years – List of years for relation activity.
nodes – List of model nodes.

Returns:

DataFrame with relation_activity for industrial thermal demand links.

Return type:

pd.DataFrame

message_ix_models.model.material.data_generic.add_non_co2_emission_coefficients(scen: Scenario, df_input: DataFrame, method='from_disk')[source]

Derive non-CO2 emission coefficients for furnaces.

Parameters:

scen (Scenario) – Scenario instance.
df_input (pd.DataFrame) – DataFrame of furnace input parameters.
method (str, optional) – Method to obtain emission coefficients (“from_disk” or “from_scenario”).

Returns:

DataFrame with non-CO2 emission coefficients for furnaces.

Return type:

pd.DataFrame

message_ix_models.model.material.data_generic.calculate_furnace_non_co2_emi_coeff(df_furn: DataFrame, df_emi: DataFrame) → DataFrame[source]

Scale emission factors of furnace technologies with input coefficients.

input and CO2_ind relation_activity DataFrames are used to scale non-CO2 emission factors for furnaces.

Parameters:

df_furn – DataFrame containing input parametrization of furnaces.
df_emi – DataFrame containing input-normalized non-CO2 emission coefficients.

Returns:

DataFrame with relation_activity for non-CO2 emissions from furnaces.

Return type:

pd.DataFrame

message_ix_models.model.material.data_generic.gen_data_generic(scenario: Scenario, dry_run: bool = False) → ParameterData[source]

Generate all parameter data for sectoral furnace and boiler technologies.

Parameters:

scenario – Scenario instance to build generic technologies on.
dry_run – If True, do not perform any file writing or scenario modification.

Returns:

Dictionary with MESSAGEix parameters as keys and parametrization as values.

Return type:

dict[str, pd.DataFrame]

message_ix_models.model.material.data_generic.get_furnace_inputs(scen: Scenario, first_year: int) → DataFrame[source]

Query input coefficients for furnace technologies from a Scenario instance.

Parameters:

scen – Scenario instance to pull input parameter from.
first_year – Earliest year for which furnace input parameter should be retrieved.

Returns:

Furnace input parameters indexed by node, year, commodity, and technology.

Return type:

pd.DataFrame

message_ix_models.model.material.data_generic.get_thermal_industry_emi_coefficients(scen: Scenario) → DataFrame[source]

Retrieve and normalize non-CO2 emission coefficients of i_therm technologies.

Parameters:: scen – Scenario instance to retrieve emission coefficients from.
Returns:: Normalized emission coefficients indexed by node, year, and technology.
Return type:: pd.DataFrame

message_ix_models.model.material.data_generic.read_data_generic(scenario: Scenario) → tuple[DataFrame, DataFrame][source]

Read and clean data from the generic furnace and boiler techno-economic file.

Parameters:

scenario (Scenario) – Scenario instance to build generic technologies on.

Returns:

DataFrame with static techno-economic data.
DataFrame with time-series data.

Return type:

tuple of pd.DataFrame

Data and parameter generation for the ammonia fertilizer sector in MESSAGEix-Materials model.

This module provides functions to read, process, and generate parameter data for ammonia fertilizer technologies, demand, trade, and related constraints.

message_ix_models.model.material.data_ammonia.broadcast_years(df_new: DataFrame, max_lt: int, act_years: Series, vtg_years: Series) → DataFrame[source]

Broadcast parameter DataFrame over scenario years and vintages.

Parameters:

df_new – DataFrame to broadcast.
max_lt – Maximum technical lifetime.
act_years – Years in modelling horizon
vtg_years – Vintage model years

message_ix_models.model.material.data_ammonia.experiment_lower_CPA_SAS_costs(par_dict: dict[str, DataFrame]) → dict[str, DataFrame][source]

Lower coal and fueloil based production costs for CPA and SAS regions.

Parameters:: par_dict – Dictionary with parameter data including cost parameters.

message_ix_models.model.material.data_ammonia.gen_all_NH3_fert(scenario: Scenario, dry_run: bool = False) → ParameterData[source]

Generate all MESSAGEix parameter data for the ammonia fertilizer sector.

Parameters:

scenario – Scenario instance to build ammonia fertilizer model on.
dry_run – If True, do not perform any file writing or scenario modification.

message_ix_models.model.material.data_ammonia.gen_ccs_bounds(s_info) → ParameterData[source]

Generate bounds for CCS technologies for 2020 and 2025.

Parameters:: s_info – Scenario information used to determine the nodes and years.

message_ix_models.model.material.data_ammonia.gen_data(scenario: Scenario, s_info: ScenarioInfo, lower_costs: bool = False) → ParameterData[source]

Generate time-independent parameter data for ammonia fertilizer technologies.

Parameters:

scenario – Scenario instance to generate ammonia model data for.
lower_costs – Switch to apply experimental lower costs for certain regions.

message_ix_models.model.material.data_ammonia.gen_data_rel(s_info: ScenarioInfo) → ParameterData[source]

Generate relation parameter data for ammonia fertilizer sector.

Parameters:: s_info – Scenario information to infer model regions and years.

message_ix_models.model.material.data_ammonia.gen_data_ts(s_info: ScenarioInfo) → ParameterData[source]

Generate time-series parameter data for ammonia fertilizer sector.

Parameters:: s_info – Scenario information to infer model regions.

message_ix_models.model.material.data_ammonia.gen_demand() → ParameterData[source]: Generate adjusted i_feed demand with explicit ammonia demand.

message_ix_models.model.material.data_ammonia.gen_land_input(scenario: Scenario) → ParameterData[source]

Read fertilizer demand from GLOBIOM soft-link and return as land input parameter.

Parameters:: scenario – Scenario to query fertilizer demand from.

message_ix_models.model.material.data_ammonia.gen_resid_demand_NH3(scenario: Scenario) → ParameterData[source]

Generate residual demand for ammonia excluding fertilizer use.

Parameters:: scenario – Scenario to generate residual demand for.

message_ix_models.model.material.data_ammonia.read_demand() → dict[str, DataFrame | Series][source]: Read and clean demand and trade data for ammonia fertilizer.

message_ix_models.model.material.data_ammonia.set_exp_imp_nodes(df: DataFrame) → None[source]

Helper to set import/export node_dest/origin to GLB for input/output technologies

Parameters:: df – DataFrame with technology and node columns.

Data and parameter generation for the methanol sector in MESSAGEix-Materials model.

This module provides functions to read, process, and generate parameter data for methanol technologies, demand, trade, and related constraints.

message_ix_models.model.material.data_methanol.broadcast_nodes(df_bc_node: DataFrame, df_final: DataFrame, node_cols: list[str], node_cols_codes: dict[str, Series], i: int) → DataFrame[source]

Broadcast nodes that were stored in pivoted row.

Parameters:

df_bc_node – DataFrame containing parameter data with node values pivoted
df_final – Full list of pivoted parameter data
node_cols – list of node columns of the respective parameter
node_cols_codes – list of node codes used for broadcasting
i – index of the row in df_final to be broadcasted

message_ix_models.model.material.data_methanol.broadcast_years(df_bc_node: DataFrame, yr_col_out: list[str], yr_cols_codes: dict[str, list[str]], col: str) → DataFrame[source]

Broadcast years that were stored in pivoted row.

Parameters:

df_bc_node – DataFrame containing parameter data with year values pivoted
yr_col_out – list of year columns to be broadcasted
yr_cols_codes – list of year codes used for broadcasting
col – name of year column to be broadcasted

message_ix_models.model.material.data_methanol.gen_data_methanol(scenario: Scenario) → ParameterData[source]: Generate parameter data for methanol industry model.

message_ix_models.model.material.data_methanol.gen_meth_fs_downstream(s_info: ScenarioInfo) → ParameterData[source]

Generate input and output parametrization for methanol downstream use technology.

Parameters:: s_info – Scenario info object to infer regions and years from.

message_ix_models.model.material.data_methanol.unpivot_input_data(df: DataFrame, par_name: str) → DataFrame[source]

Unpivot data that already contains columns for respective MESSAGEix parameter.

Parameters:

df – DataFrame containing parameter data with year and node values pivoted
par_name – name of MESSAGEix parameter

message_ix_models.model.material.demand.format_to_demand_par(df: DataFrame, material: str)[source]

Format given dataframe to MESSAGEix demand parameter.

Parameters:

df – DataFrame containing columns: [region, year, demand_tot]
material – commodity code

message_ix_models.model.material.demand.gen_demand_petro(scenario: Scenario, chemical: Literal['HVC', 'methanol', 'NH3'], gdp_elasticity_2020: float, gdp_elasticity_2030: float)[source]

Generate petrochemical demand projections based on GDP elasticity.

This function calculates the demand for petrochemicals (HVC, methanol, NH3) using distinct GDP elasticity values for 2020-2030 and post-2030. GDP projections are queried from scenario if available or read from external data file.

Parameters:

scenario – The MESSAGEix scenario containing input data.
chemical – The petrochemical for which demand is being projected.
gdp_elasticity_2020 – GDP elasticity value for the period up to 2020.
gdp_elasticity_2030 – GDP elasticity value for the period after 2030.

Returns:

demand parameter data

Return type:

pd.DataFrame

message_ix_models.model.material.demand.prepare_model_input(df_pop: DataFrame, df_gdp: DataFrame, df_base_demand: DataFrame) → DataFrame[source]: Prepare input dataframe for applying regression model.

message_ix_models.model.material.demand.project_demand(df: DataFrame, phi: float, mu: float)[source]

Project material demand over time using a convergence function.

This function calculates the projected demand for materials by applying a Gompertz convergence function to historical demand data. It adjusts demand per capita and total demand based on population and other factors.

Parameters:

df – Input DataFrame containing historical demand data with the following columns: - demand.tot.base: Base year total demand. - pop.mil: Population in millions. - demand_pcap0: Initial demand per capita. - year: Year of the data.
phi – Shape parameter for the Gompertz function.
mu – Rate parameter for the Gompertz function.

Returns:

A DataFrame containing projected demand data with the following columns: - region: Region name. - year: Year of the data. - demand_tot: Projected total demand.

Return type:

pd.DataFrame

message_ix_models.model.material.demand.read_base_demand(filepath: str | Path)[source]

Read base year demand data from a YAML file.

Parameters:: filepath – Path to the YAML file containing base demand data.
Returns:: DataFrame with columns: region, year, value.
Return type:: pd.DataFrame

message_ix_models.model.material.demand.read_gdp_ppp_from_scen(scen: Scenario) → DataFrame[source]

Extract GDP (PPP) data from a MESSAGEix scenario.

If GDP (PPP) data is not directly available, it calculates it using GDP (MER) and a MER-to-PPP conversion factor.

Parameters:: scen – The MESSAGEix scenario containing GDP data.
Returns:: A DataFrame containing GDP (PPP) data with the following columns: - year: Year of the data. - region: Region name. - gdp_ppp: GDP (PPP) value.
Return type:: pd.DataFrame

message_ix_models.model.material.demand.read_hist_mat_demand(material: Literal['cement', 'steel', 'aluminum'])[source]

Read historical material demand data for a specified commodity.

This function retrieves historical data on material consumption, population, and GDP for the specified material. It processes the data from various sources and formats it into a consistent structure.

Parameters:: material – Commodity for which historical demand data is being read.
Returns:: DataFrame containing historical material demand data with the following columns: - region: Region name. - reg_no: Region number. - year: Year of the data. - consumption: Material consumption. - pop: Population data. - gdp_pcap: GDP per capita. - cons_pcap: Consumption per capita. - del_t: Time difference from the base year (2010).
Return type:: pd.DataFrame

message_ix_models.model.material.demand.read_pop_from_scen(scen: Scenario) → DataFrame[source]

Extract population data from a MESSAGEix scenario.

Filters the data to include only years from 2020 onwards and renames columns.

Parameters:: scen ("Scenario") – The MESSAGEix scenario containing population data.
Returns:: A DataFrame containing population data with the following columns: - region: Region name. - year: Year of the data. - pop.mil: Population in millions.
Return type:: pd.DataFrame

message_ix_models.model.material.demand.read_socio_economic_projection(scen: Scenario) → tuple[DataFrame, DataFrame][source]: Read socio-economic projections (population and GDP)

message_ix_models.model.material.demand.read_timer_gdp(datapath: str | Path, material: Literal['cement', 'steel', 'aluminum'])[source]

Read GDP per capita data for a given material from TIMER Excel files.

Parameters:

datapath – Path to the directory containing the TIMER data files.
material – The material type for which GDP per capita data is being read.

Returns:

A DataFrame containing GDP per capita data with the following columns: - region: Region name. - reg_no: Region number. - year: Year of the data. - gdp_pcap: GDP per capita value.

Return type:

pd.DataFrame

message_ix_models.model.material.demand.read_timer_pop(datapath: str | Path, material: Literal['cement', 'steel', 'aluminum'])[source]

Read population data for a given material from TIMER model.

Parameters:

datapath
material

Returns:

DataFrame containing population data with columns: [region, reg_no, year, pop]

Return type:

pd.DataFrame

message_ix_models.model.material.data_util.add_cement_ccs_co2_tr_relation(scen: Scenario) → None[source]

Adds CCS technologies to the co2_trans_disp and bco2_trans_disp relations.

Parameters:: scen – Scenario instance to add CCS emission factor parametrization to

message_ix_models.model.material.data_util.add_elec_i_ini_act(scenario: Scenario) → None[source]

Adds initial_activity_up parametrization for elec_i technology.

Values are copied from hp_el_i technology

Parameters:: scenario – Scenario to update parametrization for

message_ix_models.model.material.data_util.add_emission_accounting(scen: Scenario) → None[source]

Parameters:: scen

message_ix_models.model.material.data_util.add_macro_materials(scen: Scenario, filename: str, check_converge: bool = False) → Scenario[source]

Prepare data for MACRO calibration by reading data from xlsx file.

Parameters:

scen – Scenario to be calibrated
filename – name of xlsx calibration data file
check_converge (bool) – parameter passed to MACRO calibration function

Returns:

MACRO-calibrated Scenario instance

Return type:

message_ix.Scenario

message_ix_models.model.material.data_util.add_water_par_data(scenario: Scenario) → None[source]

Adds water supply technologies that are required for the Materials build.

Parameters:: scenario – instance to check for water technologies and add if missing

message_ix_models.model.material.data_util.calculate_ini_new_cap(df_demand: DataFrame, technology: str, material: str, ssp: str) → DataFrame[source]

Derive initial_new_capacity_up data for CCS from projected cement demand.

Parameters:

df_demand – DataFrame containing “demand” MESSAGEix parametrization.
technology – Name of CCS technology to be parametrized.
material – Name of the material/industry sector.

Returns:

initial_new_capacity_up parameter data.

Return type:

pd.DataFrame

message_ix_models.model.material.data_util.calibrate_for_SSPs(scenario: Scenario) → None[source]

Calibrate technologies activity bounds and growth constraints.

This is necessary to avoid base year infeasibilities in year 2020. Originally developed for the SSP_dev_* scenarios, where most technology activities are fixed in 2020.

Parameters:: scenario – instance to apply parameter changes to

message_ix_models.model.material.data_util.gen_chemicals_co2_ind_factors(info, species: Literal['methanol', 'HVCs']) → ParameterData[source]

Generate CO2_ind relation_activity values for chemical production.

The values represent the carbon in chemical feedstocks which is oxidized in the short-term (i.e. during the model horizon) in downstream products. Oxidation either through natural oxidation or combustion as the end-of-life treatment of plastics.

The calculation considers:

carbon content of feedstocks,
the share that is converted to oxidizable chemicals
the end-of-life treatment shares (i.e. incineration, landfill, etc.)

NOTE: Values are positive since they need to be added to bottom-up emission accounting.

Parameters:: species – feedstock species to generate relation for

message_ix_models.model.material.data_util.gen_ethanol_to_ethylene_emi_factor(info: ScenarioInfo) → ParameterData[source]

Generate CO2_ind relation_activity values for ethanol_to_ethylene_petro.

The values represent the carbon in chemical feedstocks which is oxidized in the short-term (i.e. during the model horizon) in downstream products. Oxidation either through natural oxidation or combustion as the end-of-life treatment of plastics.

The calculation considers:

carbon content of feedstocks,

the share that is converted to oxidizable chemicals

the end-of-life treatment shares (i.e. incineration, landfill, etc.)

NOTE: Values are positive since they are added to bottom-up CO2 accounting.

message_ix_models.model.material.data_util.gen_plastics_emission_factors(info, species: Literal['methanol', 'HVCs', 'ethanol']) → ParameterData[source]

Generate “CO2_Emission” relation parameter to account stored carbon in plastics.

The calculation considers:

carbon content of feedstocks,
the share that is converted to plastics
the end-of-life treatment (i.e. incineration, landfill, etc.)

NOTE: Values are negative since they need to be deducted from top-down accounting, which assumes that all extracted carbonaceous resources are released as carbon emissions. (Which would not be correct for carbon used in long-lived products)

Parameters:: species – feedstock species to generate relation for

message_ix_models.model.material.data_util.gen_te_projections(scen: Scenario, ssp: Literal['all', 'LED', 'SSP1', 'SSP2', 'SSP3', 'SSP4', 'SSP5'] = 'SSP2', method: Literal['constant', 'convergence', 'gdp'] = 'convergence', ref_reg: str = 'R12_NAM', module='materials', reduction_year=2100) → tuple[DataFrame, DataFrame][source]

Generate cost parameter data for scenario technology set.

Calls message_ix_models.tools.costs with config for MESSAGEix-Materials and return inv_cost and fix_cost projections for energy and industry technologies.

Parameters:

scen – Scenario instance is required to get technology set.
ssp – SSP to use for projection assumptions.
method – method to use for cost convergence over time.
ref_reg – reference region to use for regional cost differentiation.

Returns:

tuple with inv_cost and fix_cost data

Return type:

tuple[pd.DataFrame, pd.DataFrame]

message_ix_models.model.material.data_util.get_region_map() → Mapping[str, str][source]

Construct a mapping from “COUNTRY” IDs to regions (nodes in the “R12” codelist).

These “COUNTRY” IDs are produced by a certain script for processing the IEA Extended World Energy Balances; this script is not in message_ix_models; i.e. it is not the same as tools.iea.web. They include some ISO 3166-1 alpha-3 codes, but also other values like “GREENLAND” (instead of “GRL”), “KOSOVO”, and “IIASA_SAS”.

This function reads the material-region annotation on items in the R12 node codelist, expecting a list of strings. Of these:

The special value “*” is interpreted to mean “include the IDs all of the child nodes of this node (i.e. their ISO 3166-1 alpha-3 codes) in the mapping”.
All other values are mapped directly.

The return value is cached for reuse.

Returns:: Mapping from e.g. “KOSOVO” to e.g. “R12_EEU”.
Return type:: dict

message_ix_models.model.material.data_util.get_ssp_soc_eco_data(context: Context, model: str, measure: str, tec: str) → DataFrame[source]

Generate GDP and POP data of SSP 3.0 in bound_activity_* format.

Parameters:

context – context used to prepare genno.Computer
model – model name of projections to read
measure – Indicator to read (GDP or Population)
tec – name to use for “technology” column

Returns:

DataFrame with SSP indicator data in bound_activity_* parameter format.

Return type:

pd.DataFrame

message_ix_models.model.material.data_util.map_iea_db_to_msg_regs(df_iea: DataFrame) → DataFrame[source]

Add a “REGION” column to df_iea.

Parameters:: df_iea – Data frame containing the IEA energy balances data set. This must have a “COUNTRY” column.
Returns:: with added column “REGION” containing node IDs according to get_region_map().
Return type:: pandas.DataFrame

message_ix_models.model.material.data_util.read_iea_tec_map(tec_map_fname: str) → DataFrame[source]

Reads mapping file and returns relevant columns needed for technology mapping.

Parameters:: tec_map_fname – name of mapping file used to map IEA flows and products to existing MESSAGEix technologies
Returns:: returns df with mapped technologies
Return type:: pd.DataFrame

message_ix_models.model.material.data_util.read_rel(scenario: Scenario, material: str, ssp: str | None, filename: str) → DataFrame[source]

Read relation_* type parameter data for specific industry

Parameters:

ssp – if relations are available for different SSPs, the respective file is selected
scenario – scenario used to get structural information like
material – name of material folder where xlsx is located
filename – name of xlsx file

Returns:

DataFrame containing relation_* parameter data

Return type:

pd.DataFrame

message_ix_models.model.material.data_util.read_sector_data(scenario: Scenario, sectname: str, ssp: str | None, filename: str) → DataFrame[source]

Read sector data for industry with sectname.

Parameters:

scenario – Scenario used to get structural information like model regions and years.
sectname – Name of industry sector.
ssp – If sector data should be read from an SSP-specific file.
filename – Name of input file with suffix.

Return type:

pd.DataFrame

message_ix_models.model.material.data_util.read_timeseries(scenario: Scenario, material: str, ssp: str | None, filename: str) → DataFrame[source]

Read ‘time-series’ data from a material-specific filename.

Read “timeseries” type data from a sector-specific input file to data frame and format as MESSAGE parameter data.

Parameters:

scenario – Scenario used to get structural information like model regions and years.
material – Name of material folder (‘sector’) where filename is located.
ssp – If timeseries is available for different SSPs, the respective file is selected.
filename – Name of data file including .csv or .xlsx suffix.

Returns:

DataFrame containing the timeseries data for MESSAGEix parameters

Return type:

pd.DataFrame

Post-processing and reporting

Build and solve the model from CLI

Note: To include material stocks from power sector message_ix should be the following version from source: https://github.com/iiasa/message_ix/tree/material_stock

Use mix-models materials-ix {SSP} build to add the material implementation on top of existing standard global (R12) scenarios, also giving the base scenario and indicating the relevant data location, e.g.:

mix-models \
    --url="ixmp://ixmp_dev/MESSAGEix-GLOBIOM 1.1-R12/baseline_DEFAULT#21" \
    --local-data "./data" material-ix SSP2 build --tag test --nodes R12

The output scenario name will be baseline_DEFAULT_test. An additional tag --tag can be used to add an additional suffix to the new scenario name. The mode option --mode has two different inputs ‘by_url’ (by default) or ‘by_copy’. The first one uses the provided --url to add the materials implementation on top of the scenario from the url. This is the default option. The latter is used to create a 2 degree mitigation scenario with materials by copying carbon prices to the scenario that is specified by --scenario_name:

mix-models --url="ixmp://ixmp_dev/MESSAGEix-Materials/scenario_name" material-ix \
 build --tag test --mode by_copy

This command line only builds the scenario but does not solve it. To solve the scenario, use mix-models materials-ix solve, giving the scenario name, e.g.:

mix-models --url="ixmp://ixmp_dev/MESSAGEix-Materials/scenario_name" material-ix \
 SSP2 solve --add_calibration False --add_macro False

The solve command has the --add_calibration option to add MACRO calibration to a baseline scenario with a valid calibration file specified with --macro-file. The --add_macro option determines whether the scenario should be solved with MESSAGE or MESSAGE-MACRO. MESSAGEix-Materials provides one calibration file that is only compatible with scenarios with first model year 2025 and the common model structure of a MESSAGEix-GLOBIOM scenario. To first calibrate the scenario and then solve that scenario with MACRO both options should be set to :any`True`.

It is also possible to shift the first model year and solve a clone with shifted years with --shift_model_year. If --shift_model_year is set together with the macro options the model year will be shifted before the MACRO calibration.

All three options are False by default.

Reporting

The reporting generates specific variables related to materials, mainly Production and Final Energy. The resulting reporting file is generated under message_ix_models/data/material/reporting_output with the name “New_Reporting_MESSAGEix-Materials_scenario_name.xlsx”. More detailed variables related to the whole energy system and emissions are not included in this reporting.

Reporting is executed by the following command:

mix-models --url="ixmp://ixmp_dev/MESSAGEix-Materials/scenario_name" \
    --local-data "./data" material-ix SSP2 report

To remove any existing timeseries in the scenario the following command can be used:

mix-models --url="ixmp://ixmp_dev/MESSAGEix-Materials/scenario_name" material-ix \
    SSP2 report --remove_ts True

Data, metadata, and configuration

Binary/raw data files

The code relies on the following input files, stored in data/material/:

Cement

CEMENT.BvR2010.xlsx: Historical cement demand data
Global_cement_MESSAGE.xlsx: Techno-economic parametrization data for cement sector combined (R12)
demand_cement.yaml: Base year demand data

Aluminum

demand_aluminum.xlsx: Historical aluminum demand data
aluminum_trade_data.csv: Data retrieved from IAI MFA model and used for trade calibration
aluminum_techno_economic.xlsx: Techno-economic parametrization data for aluminum sector
demand_aluminum.yaml: Base year aluminum demand data

Iron and Steel

STEEL_database_2012.xlsx: Historical steel demand data
Global_steel_MESSAGE.xlsx: Techno-economic parametrization data for steel sector combined (R12)
worldsteel_steel_trade.xlsx: Historical data from worldsteel Association
demand_steel.yaml: Base year steel demand data

Chemicals

nh3_fertilizer_demand.xlsx: Nitrogen fertilizer demand
fert_techno_economic.xlsx: Techno-economic parameters for NH3 production technologies
cost_conv_nh3.xlsx: Regional cost convergence settings for NH3 production technologies over time
methanol demand.xlsx: Methanol demand
methanol_sensitivity_pars.xlsx: Methanol sensitivity parameters
methanol_techno_economic.xlsx: Techno-economic parameters for methanol production technologies
petrochemicals_techno_economic.xls: Techno-economic parameters for refinery and high-value chemicals production technologies
steam_cracking_hist_act.csv: Steam cracker historical activities in R12 regions
steam_cracking_hist_new_cap.csv: Steam cracker historical capacities in R12 regions
ammonia/demand_NH3.yaml: Ammonia demand in each R12 region in year 2020
petrochemicals/demand_HVC.yaml: HVC demand in each R12 region in year 2020
methanol/demand_methanol.yaml: Methanol demand in each R12 region in year 2020
/methanol/results_material_SHAPE_comm.csv: Commercial sector data from MESSAGEix-Buidings SHAPE scenario used to get wood demands from buildings to estimate resin demands
/methanol/results_material_SHAPE_resid.csv: Residential sector data from MESSAGEix-Buidings SHAPE scenario used to get wood demands from buildings to estimate resin demands
/methanol/results_material_SSP2_comm.csv: Commercial sector data from MESSAGEix-Buidings SSP2 scenario used to get wood demands from buildings to estimate resin demands
/methanol/results_material_SSP2_resid.csv: Residential sector data from MESSAGEix-Buidings SSP2 scenario used to get wood demands from buildings to estimate resin demands

Power sector

NTNU_LCA_coefficients.xlsx: Material intensity (and other) coefficients for power plants based on lifecycle assessment (LCA) data from the THEMIS database, compiled in the ADVANCE project.
MESSAGE_global_model_technologies.xlsx: Technology list of global MESSAGEix-GLOBIOM model with mapping to LCA technology dataset.
LCA_region_mapping.xlsx: Region mapping of global 11-regional MESSAGEix-GLOBIOM model to regions of THEMIS LCA dataset.
LCA_commodity_mapping.xlsx: Commodity mapping (for materials) of global 11-regional MESSAGEix-GLOBIOM model to commodities of THEMIS LCA dataset.

Buildings

buildings/LED_LED_report_IAMC_sensitivity_R12.csv: Data from MESSAGEix-Buidings LED scenarios used to get steel/cement/aluminum demands from buildings
buildings/report_IRP_SSP2_BL_comm_R12.csv: Commerical sector data from MESSAGEix-Buidings used to get steel/cement/aluminum demands from buildings
buildings/report_IRP_SSP2_BL_resid_R12.csv: Residential sector data from MESSAGEix-Buidings used to get steel/cement/aluminum demands from buildings

Other

generic_furnace_boiler_techno_economic.xlsx: Techno-economic parametrization data for generic furnace technologies
iamc_db ENGAGE baseline GDP PPP.xlsx: SSP GDP projection used for material demand projections
MESSAGEix-Materials_final_energy_industry.xlsx: Final energy values to calibrate base year values for industries
residual_industry_2019.xlsx: Final energy values to calculate the residual industry demand
SSP_UE_dyn_input.xlsx: Calibration file for industry end-use energy demands
SSP_UE_dyn_input_all.xlsx: Calibration file for end-use energy demands
iea_mappings/all_technologies.csv: Mapping of MESSAGEix-GLOBIOM technologies to IEA EWEB flows and products
iea_mappings/chemicals.csv: Mapping of MESSAGEix-GLOBIOM industry technologies to IEA EWEB products of chemical sector flows
iea_mappings/industry.csv: Mapping of MESSAGEix-GLOBIOM industry technologies to IEA EWEB products of industry sector flows not covered by MESSAGEix-Materials
other/mer_to_ppp_default.csv: Default conversion factors for GDP MER to PPP used in MESSAGEix-GLOBIOM SSP2 scenarios. Used to create demand projections for steel/cement/aluminum/chemicals if GDP_PPP data is not in scenario

`material/set.yaml`

# Set configuration for the MESSAGE-Materials model

# For each set in the MESSAGEix framework, the group contains:
# - 'require': elements that must be present for the model to be set up.
# - 'remove': elements to remove.
# - 'add': elements to add.

common:
  node:
    add:
    - R12_GLB

  technology:
    add:
    - extract__freshwater_supply
    remove:
    # remove deprecated technologies that are sometimes still existent in older MESSAGEix-GLOBIOM versions
    - hp_gas_i
    - sp_coal_I
    - hp_gas_rc

  commodity:
    require:
    - coal
    - gas
    - electr
    - ethanol
    - methanol
    - fueloil
    - lightoil
    - hydrogen
    - lh2
    - d_heat
    - biomass
    add:
    - water
    - fresh_water_supply
    - freshwater_supply

  level:
    add:
    - water_supply

    require:
    - primary
    - secondary
    - useful
    - final
    #- water_supply
    - export
    - import

# Not used at the moment
# maybe to be used in updated legacy reporting
#  type_tec:
#    add:
#    - industry

  mode:
    add:
    - M1
    - M2

  emission:
    add:
    - CO2
    - CH4
    - N2O
    - NOx
    - SO2
    - PM2p5 # Just add there since it is already in Shaohui's data
    - CF4
    - CO2_industry
    - CO2_transport
    - CO2_transformation

  year:
    require:
    - 1980
    - 1990
    - 1995
    - 2000
    - 2005
    - 2010
    - 2015

  unit:
    add:
    - t/kW
    - Mt
    - Mt/yr
    - USD/kW


generic:
  commodity:
    add:
    - ht_heat
    - lt_heat

  level:
    add:
    - useful_steel
    - useful_cement
    - useful_aluminum
    - useful_refining
    - useful_petro
    - useful_resins

  technology:
    add:
    - furnace_foil_steel
    - furnace_loil_steel
    - furnace_biomass_steel
    - furnace_ethanol_steel
    - furnace_methanol_steel
    - furnace_gas_steel
    - furnace_coal_steel
    - furnace_elec_steel
    - furnace_h2_steel
    - hp_elec_steel
    - fc_h2_steel
    - solar_steel
    - dheat_steel
    - furnace_foil_cement
    - furnace_loil_cement
    - furnace_biomass_cement
    - furnace_ethanol_cement
    - furnace_methanol_cement
    - furnace_gas_cement
    - furnace_coal_cement
    - furnace_elec_cement
    - furnace_h2_cement
    - hp_elec_cement
    - fc_h2_cement
    - solar_cement
    - dheat_cement
    - furnace_coal_aluminum
    - furnace_foil_aluminum
    - furnace_loil_aluminum
    - furnace_ethanol_aluminum
    - furnace_biomass_aluminum
    - furnace_methanol_aluminum
    - furnace_gas_aluminum
    - furnace_elec_aluminum
    - furnace_h2_aluminum
    - hp_elec_aluminum
    - fc_h2_aluminum
    - solar_aluminum
    - dheat_aluminum
    - furnace_coke_petro
    - furnace_coal_petro
    - furnace_foil_petro
    - furnace_loil_petro
    - furnace_ethanol_petro
    - furnace_biomass_petro
    - furnace_methanol_petro
    - furnace_gas_petro
    - furnace_elec_petro
    - furnace_h2_petro
    - hp_elec_petro
    - fc_h2_petro
    - solar_petro
    - dheat_petro
    - furnace_coke_refining
    - furnace_coal_refining
    - furnace_foil_refining
    - furnace_loil_refining
    - furnace_ethanol_refining
    - furnace_biomass_refining
    - furnace_methanol_refining
    - furnace_gas_refining
    - furnace_elec_refining
    - furnace_h2_refining
    - hp_elec_refining
    - fc_h2_refining
    - solar_refining
    - dheat_refining
    - furnace_coal_resins
    - furnace_foil_resins
    - furnace_loil_resins
    - furnace_ethanol_resins
    - furnace_biomass_resins
    - furnace_methanol_resins
    - furnace_gas_resins
    - furnace_elec_resins
    - furnace_h2_resins
    - hp_elec_resins
    - fc_h2_resins
    - solar_resins
    - dheat_resins

  mode:
    add:
    - low_temp
    - high_temp

petro_chemicals:
  commodity:
    require:
    - crudeoil
    add:
    - HVC
    - naphtha
    - kerosene
    - diesel
    - atm_residue
    - refinery_gas
    - atm_gasoil
    - atm_residue
    - vacuum_gasoil
    - vacuum_residue
    - gasoline
    - heavy_foil
    - light_foil
    - propylene
    - pet_coke
    - ethane
    - propane
    - ethylene
    - BTX
    remove:
    - i_feed

  level:
    require:
    - secondary
    - final
    add:
    - pre_intermediate
    - desulfurized
    - intermediate
    - secondary_material
    - final_material
    - demand
    - refinery

  balance_equality:
    add:
      - ["lightoil", "import"]
      - ["lightoil", "export"]
      - ["fueloil", "import"]
      - ["fueloil", "export"]

  mode:
    add:
    - atm_gasoil
    - vacuum_gasoil
    - naphtha
    - kerosene
    - diesel
    - cracking_gasoline
    - cracking_loil
    - ethane
    - propane
    - light_foil
    - refinery_gas
    - refinery_gas_int
    - heavy_foil
    - pet_coke
    - atm_residue
    - vacuum_residue
    - gasoline
    - ethylene
    - propylene
    - BTX

  technology:
    add:
    - atm_distillation_ref
    - vacuum_distillation_ref
    - hydrotreating_ref
    - catalytic_cracking_ref
    - visbreaker_ref
    - coking_ref
    - catalytic_reforming_ref
    - hydro_cracking_ref
    - steam_cracker_petro
    - ethanol_to_ethylene_petro
    - agg_ref
    - gas_processing_petro
    - trade_petro
    - import_petro
    - export_petro
    - feedstock_t/d
    - production_HVC
    remove:
    # Any representation of refinery.
    - ref_hil
    - ref_lol
    - coal_fs
    - ethanol_fs
    - gas_fs
    - foil_fs
    - loil_fs
    - methanol_fs

  shares:
    add:
    - steam_cracker

  sector:
    remove:
    - i_feed

steel:
  mode:
    add:
    - M3
    - M4

  commodity:
    add:
    - steel
    - pig_iron
    - pig_iron_dummy
    - charcoal
    - sponge_iron
    - sinter_iron
    - pellet_iron
    - ore_iron
    - limestone_iron
    - coke_iron
    - slag_iron
    - co_gas
    - bf_gas
    - off_gas

  level:
    add:
    - new_scrap
    - old_scrap_1
    - old_scrap_2
    - old_scrap_3
    - primary_material
    - secondary_material
    - tertiary_material
    - final_material
    - useful_material
    - waste_material
    - product
    - demand
    - dummy_emission
    - end_of_life
    - dummy_end_of_life_1
    - dummy_end_of_life_2
    - dummy_end_of_life_3
    - dummy_ccs

  technology:
    add:
    - cokeoven_steel
    - sinter_steel
    - pellet_steel
    - bf_steel
    - bf_ccs_steel
    - dri_steel
    - dri_coal_steel
    - dri_gas_steel
    - dri_gas_ccs_steel
    - dri_h2_steel
    - sr_steel
    - bof_steel
    - eaf_steel
    - prep_secondary_steel_1
    - prep_secondary_steel_2
    - prep_secondary_steel_3
    - finishing_steel
    - manuf_steel
    - scrap_recovery_steel_1
    - scrap_recovery_steel_2
    - scrap_recovery_steel_3
    - DUMMY_ore_supply
    - DUMMY_limestone_supply_steel
    - DUMMY_coal_supply
    - DUMMY_gas_supply
    - trade_steel
    - import_steel
    - export_steel
    - other_EOL_steel
    - total_EOL_steel
    - bf_biomass_steel
    - prod_charcoal_steel

  relation:
    add:
      - minimum_recycling_steel
      - max_global_recycling_steel
      - max_regional_recycling_steel
      - eaf_bound_2020
      - bof_bound_2020
      - bf_bound_2020

#  balance_equality:
#    add:
#      - ["steel","old_scrap_1"]
#      - ["steel","old_scrap_2"]
#      - ["steel","old_scrap_3"]
#      - ["steel","end_of_life"]
#      - ["steel","product"]
#      - ["steel","new_scrap"]
#      - ["steel","useful_material"]
#      - ["steel","final_material"]

  addon:
    add:
      - bf_ccs_steel
      - dri_coal_steel
      - dri_gas_ccs_steel
      - dri_gas_steel
      - dri_h2_steel

  type_addon:
    add:
      - bf_ccs_steel_addon
      - dri_gas_ccs_steel_addon
      - dri_steel_addon

  map_tec_addon:
    add:
      - [bf_steel, bf_ccs_steel_addon]
      - [dri_gas_steel, dri_gas_ccs_steel_addon]
      - [dri_steel, dri_steel_addon]

  cat_addon:
    add:
      - [bf_ccs_steel_addon, bf_ccs_steel]
      - [dri_gas_ccs_steel_addon, dri_gas_ccs_steel]
      - [dri_steel_addon, dri_coal_steel]
      - [dri_steel_addon, dri_gas_steel]
      - [dri_steel_addon, dri_h2_steel]

cement:
  commodity:
    add:
    - cement
    - clinker_cement
    - raw_meal_cement
    - limestone_cement

  level:
    add:
    - primary_material
    - secondary_material
    - tertiary_material
    - final_material
    - useful_material
    - demand
    - dummy_end_of_life
    - end_of_life

  technology:
    add:
    - raw_meal_prep_cement
    - clinker_dry_cement
    - clinker_wet_cement
    - clinker_dry_ccs_cement
    - clinker_wet_ccs_cement
    - grinding_ballmill_cement
    - grinding_vertmill_cement
    - DUMMY_limestone_supply_cement
    - total_EOL_cement
    - other_EOL_cement
    - scrap_recovery_cement

    remove:
    - cement_co2scr
    - cement_CO2

  relation:
    remove:
    - cement_pro
    - cement_scrub_lim

  balance_equality:
    add:
      - ["cement","end_of_life"]

  addon:
    add:
    - clinker_dry_ccs_cement
    - clinker_wet_ccs_cement

  type_addon:
    add:
    - wet_ccs_cement
    - dry_ccs_cement

  map_tec_addon:
    add:
    - [clinker_dry_cement, dry_ccs_cement]
    - [clinker_wet_cement, wet_ccs_cement]

  cat_addon:
    add:
    - [dry_ccs_cement, clinker_dry_ccs_cement]
    - [wet_ccs_cement, clinker_wet_ccs_cement]

aluminum:
  commodity:
    add:
    - aluminum
    - bauxite
    - alumina

  level:
    add:
    - new_scrap
    - old_scrap_1
    - old_scrap_2
    - old_scrap_3
    - useful_aluminum
    - final_material
    - useful_material
    - product
    - secondary_material
    - primary_material
    - demand
    - end_of_life
    - dummy_end_of_life_1
    - dummy_end_of_life_2
    - dummy_end_of_life_3

  technology:
    add:
    - trade_alumina
    - import_alumina
    - export_alumina
    - refining_aluminum
    - soderberg_aluminum
    - prebake_aluminum
    - secondary_aluminum
    - prep_secondary_aluminum_1
    - prep_secondary_aluminum_2
    - prep_secondary_aluminum_3
    - finishing_aluminum
    - manuf_aluminum
    - scrap_recovery_aluminum_1
    - scrap_recovery_aluminum_2
    - scrap_recovery_aluminum_3
    - DUMMY_bauxite_supply
    - trade_aluminum
    - import_aluminum
    - export_aluminum
    - other_EOL_aluminum
    - total_EOL_aluminum

  relation:
    add:
      - minimum_recycling_aluminum
      - maximum_recycling_aluminum

  balance_equality:
    add:
      - ["aluminum","old_scrap_1"]
      - ["aluminum","old_scrap_2"]
      - ["aluminum","old_scrap_3"]
      - ["aluminum","end_of_life"]
      - ["aluminum","product"]
      - ["aluminum","new_scrap"]

fertilizer:
  commodity:
    require:
    - electr
    add:
    - NH3
    - Fertilizer Use|Nitrogen
    - wastewater

  level:
    add:
    - secondary_material
    - final_material
    - wastewater

  technology:
    require:
    - h2_bio_ccs  # Reference for vent-to-storage ratio
    add:
    - biomass_NH3
    - electr_NH3
    - gas_NH3
    - coal_NH3
    - fueloil_NH3
    - NH3_to_N_fertil
    - trade_NFert
    - export_NFert
    - import_NFert
    - trade_NH3
    - export_NH3
    - import_NH3
    - residual_NH3
    - biomass_NH3_ccs
    - gas_NH3_ccs
    - coal_NH3_ccs
    - fueloil_NH3_ccs

  relation:
    add:
      - NH3_trd_cap
      - NFert_trd_cap

methanol:
  commodity:
    require:
    - electr
    - biomass
    - hydrogen
    - d_heat
    add:
    - methanol
    - ht_heat
    - formaldehyde
    - ethylene
    - propylene
    - fcoh_resin

  level:
    add:
    - final_material
    - secondary_material
    - primary_material
    - export_fs
    - import_fs

  mode:
    add:
    - feedstock
    - fuel
    - ethanol

  technology:
    add:
    - meth_bio
    - meth_bio_ccs
    - meth_h2
    - meth_t_d_material
    - MTO_petro
    - CH2O_synth
    - CH2O_to_resin
    - meth_coal
    - meth_coal_ccs
    - meth_ng
    - meth_ng_ccs
    - meth_t_d
    - meth_bal
    - meth_trd
    - meth_exp
    - meth_imp
    - meth_ind_fs
    remove:
    - sp_meth_I
    - meth_rc
    - meth_ic_trp
    - meth_fc_trp
    - meth_i
    - meth_coal
    - meth_coal_ccs
    - meth_ng
    - meth_ng_ccs
    - meth_t_d
    - meth_bal
    - meth_trd
    - meth_exp
    - meth_imp

  addon:
    add:
      - meth_h2

  type_addon:
    add:
      - methanol_synthesis_addon

  map_tec_addon:
    add:
      - [h2_elec, methanol_synthesis_addon]

  cat_addon:
    add:
      - [methanol_synthesis_addon, meth_h2]

  relation:
    add:
      - CO2_PtX_trans_disp_split
      - meth_exp_tot

  balance_equality:
    add:
    - ["methanol","export"]
    - ["methanol","export_fs"]
    - ["methanol","import"]
    - ["methanol","import_fs"]
    - ["methanol","final"]

  emission:
    add:
    - BCA
    - CO
    - HFC
    - OCA
    - NH3
    - SF6
    - VOC

buildings:
  level:
    add:
    - service

  commodity:
    add:
    - floor_area

  technology:
    add:
    - buildings

power_sector:
  unit:
    add:
      - t/kW

# NB this codelist added by #125

# iron-steel:
#   name: Iron and Steel
#   description: Iron is a chemical element with the symbol Fe, while steel is an alloy of iron and carbon and, sometimes, other elements. Measured as the total mass of material.
#   unit: Mt
#
# non-ferrous:
#   name: Non-ferrous metals
#   description: Metals and alloys which do not contain iron. Measured as the total mass of material.
#   unit: Mt
#
# aluminum:
#   name: Aluminum
#   description: Aluminum (or aluminium) is a chemical element with the symbol Al. Measured as the total mass of material.
#   unit: Mt
#   parent: non-ferrous
#
# copper:
#   name: Copper
#   description: Copper is a chemical element with the symbol Cu. Measured as the total mass of material.
#   unit: Mt
#   parent: non-ferrous
#
# minerals:
#   name: Minerals
#   description: Non-metallic minerals are minerals that have no metallic luster, break easily and include, e.g., sand, limestone, marble, clay and salt. Measured as the FE-equivalent mass of material using LCA midpoint characterization factors.
#   unit: MtFe-eq
#
# cement:
#   name: Cement
#   description: Cement is a binder used for construction that sets, hardens, and adheres to other materials to bind them together. Measured as the total mass of material.
#   unit: Mt
#   parent: minerals
#
# chemicals:
#   name: Chemicals
#   description: Industrial chemicals that form the basis of many products. Measured as the total mass of material.
#   unit: Mt
#
# ethylene:
#   name: Ethylene
#   description: Ethylene is a hydrocarbon with the formula C2H4. Measured as the total mass of material.
#   unit: Mt
#   parent: chemicals
#
# ammonia:
#   name: Ammonia
#   description: Ammonia is a compound of nitrogen and hydrogen with the formula NH3. Measured as the total mass of material.
#   unit: Mt
#   parent: chemicals
#
# paper-pulp:
#   name: Paper and pulp for paper
#   description: Pulp is a lignocellulosic fibrous material prepared by chemically or mechanically separating cellulose fibers and the raw material for making paper. Measured as the total mass of material.
#   unit: Mt

Release notes

This is the list of changes to MESSAGEix-Materials between each release.

MESSAGEix-Materials (model.material)

Description

Code reference

Data preparation

Post-processing and reporting

Build and solve the model from CLI

Reporting

Data, metadata, and configuration

Binary/raw data files

material/set.yaml

Release notes

MESSAGEix-Materials (`model.material`)

`material/set.yaml`