TUTORIAL: Study objective B0, dynamic CC (deterministic)

AESA Phase B: (dynamic) carrying capacities definition.

Extract AR6 climate change pathways from process_ar6(...) outputs.

Before starting…

Set workspace

Run set_workspace(...) before any later function call. It sets the active workspace root for the current Python session, creates or reuses the workspace, imports package prerequisites under data_raw/, and records setup guidance in data_raw/summary.log.

[ ]:

from pyaesa import set_workspace

# Windows example; update this path before running.
set_workspace(r"C:\Users\username\Documents\aesa_workspace")

# macOS example; update this path before running.
# set_workspace("/Users/username/Documents/aesa_workspace")

Run prerequisites

This tutorial assumes that the workspace has already been set, with all prerequisites available (downloads and processing).

If this is not your case, it is recommended to first go through the core prerequisite notebooks: tutorials/core_prerequisites/0_set_workspace.ipynb, tutorials/core_prerequisites/1_download_data.ipynb, and tutorials/core_prerequisites/2_process_data.ipynb.

Basic features of the deterministic function

In a nutshell

The function takes necessary inputs:

years (must contain at least two consecutive years).
category and ssp_scenario, which restrict the retained AR6 pathway pool.
emission_type, include_afolu, and emissions_mode, which select the dynamic carrying capacity emission route.

The deterministic output folder contains:

dynamic AR6 carrying capacity tables for the selected emission variable and years.
Figures are rendered by default (figures=True). Use figures=False to skip them; figure_format controls the file format and resolution.
log files

Basic features also involve:

overwriting of existing values: use the refresh parameter.

Methodological details on AR6 scenario filtering, harmonization, gross emissions modes, and dynamic carrying capacity construction are documented in methodological_notes/methodological_note__steady_state__dynamic_cc.pdf.

Public argument checklist

The table lists all arguments; the same definitions are available in the function docstring.

Green items = default if omitted.

Orange items = optional feature skipped if omitted.

Do not write green or orange items when that behavior is intended.

deterministic_ar6_cc(…) arguments

Argument	Description
years	Study year selector provided as a consecutive year list or range(start_year, end_year + 1). The resolved years must contain at least two consecutive years with no gaps.
harmonization	Whether to harmonize retained AR6 pathways to the historical baseline. Defaults to True.
harmonization_method	Harmonization method applied only when harmonization=True. Defaults to “offset”. The only supported value is currently “offset”. Ignored when harmonization=False.
category	AR6 category classification selector for global warming trajectories. Accepts a string such as “C3” or a list such as [“C1”, “C2”]. Valid values are “C1” through “C8”. Defaults to [“C1”, “C2”, “C3”, “C4”], the categories aligned with the 2015 Paris Agreement.
ssp_scenario	SSP scenario filter. Defaults to [“SSP1”, “SSP2”, “SSP3”, “SSP4”, “SSP5”]. Pass a string such as “SSP2” or a list such as [“SSP1”, “SSP2”] to restrict.
emission_type	Dynamic AR6 emission type. Accepted values are “kyoto_gases” (default) and “co2”. emission_type=”kyoto_gases” uses the GWP100 Kyoto Gases aggregate; emission_type=”co2” uses direct CO2 pathways.
include_afolu	Whether AFOLU emissions are included inside the selected emission_type. Defaults to False.
emissions_mode	Dynamic AR6 emissions mode. Accepted values are “net”, “gross”, and “gross_alt”. Defaults to “gross_alt”. “net” uses net AR6 emissions pathways directly. “gross” removes all sequestration sources from net emissions. “gross_alt” removes all sequestration sources except CCS. CCS is retained because IPCC AR6 treats CCS as capture at fossil or industrial point sources rather than direct removal of CO2 from the atmosphere, so it is kept separate from net negative sequestration. Gross modes write positive emissions rows and signed negative sequestration companion rows; downstream aCC and ASR consume only the positive emissions rows. See data_raw/methodological_notes/methodological_note__steady_state__dynamic_cc.pdf for the methodological explanation.
subset_version	Optional selector for a subset of AR6 model-scenario pairs. Follow data_processed/ar6/<processed_scope>/README_model_scenario_subset.txt to create the subset CSV. Omit this argument to use every retained model-scenario pair. Defaults to None.
output_format	Persisted output file format: “csv” (default), “pickle”, or “parquet”.
figures	Whether to render figures. Default is True.
figure_format	Figure render settings mapping. Defaults to {“format”: “png”, “dpi”: 500}. Nested keys: • format: Figure file format. Accepted values are “png”, “pdf”, and “svg”. • dpi: Positive integer figure resolution used for raster outputs.
refresh	If True, clear and recompute the resolved deterministic AR6 CC output scope for the requested study period, harmonization flag, harmonization method, emission variables, and subset version, plus the matching processed AR6 output scope selected by process_ar6(…) for that request. The cleared AR6 CC scope is the selector-specific ar6_cc deterministic output folder beside that processed AR6 scope. For example, for years 2019 to 2060, default harmonization, default Kyoto gas settings, category [“C1”], and SSP [“SSP1”], the refreshed path is <repo>/data_processed/ar6/2019-2060_harmonization_offset/ar6_cc/gross_alt_kyoto_gases_wo_afolu/C1__SSP1/deterministic. Raw downloads and downstream aCC or ASR outputs are not refreshed. Defaults to False.

Extract dynamic AR6 CC for default AR6 categories and SSPs, using defaults where omitted

[ ]:

from pyaesa import deterministic_ar6_cc

deterministic_ar6_cc(
    years=range(2020, 2051),
)

GHG (Kyoto gases) or CO2 emissions

[ ]:

deterministic_ar6_cc(
    years=range(2020, 2051),
    category=["C1", "C2"],
    ssp_scenario=["SSP2"],
    emission_type="co2",
)

What to do next

Beginners

If you are a new user in the process of discovering pyaesa, it is recommend that you first discover all study objectives with the basic features available. Have a look at the other notebooks available at tutorials/study_objectives/0_study_objectives.md

Experts

If you are already familiar with pyaesa and if you want to discover advanced features available, check out examples in the next section of this tutorial !

Advanced features

Advanced features currently available include:

Subset of model-scenarios
Net, gross, and gross_alt emissions
Including or excluding AFOLU emissions
Changing the emissions harmonization method (not yet available!)

Subset of model-scenarios

subset_version selects a custom model-scenario pair subset prepared from data_processed/ar6/<processed_scope>/README_model_scenario_subset.txt.

[ ]:

deterministic_ar6_cc(
    years=range(2020, 2051),
    category=["C1", "C2"],
    ssp_scenario=["SSP2"],
    subset_version="selected_pairs",
)

Net, gross, and gross_alt emissions

emissions_mode selects the dynamic AR6 emissions basis used to build dynamic carrying capacity values. The default is "gross_alt".

"net" uses net AR6 emissions pathways directly.
"gross" removes all sequestration sources from net emissions.
"gross_alt" removes sequestration sources except CCS. CCS is retained because IPCC AR6 treats CCS as capture at fossil or industrial point sources rather than direct removal of CO2 from the atmosphere, so it is kept separate from net negative sequestration.

Gross modes also write signed sequestration companion rows for interpretation. Downstream aCC and ASR runs consume the positive rows.

[ ]:

deterministic_ar6_cc(
    years=range(2020, 2051),
    category=["C1", "C2"],
    ssp_scenario=["SSP2"],
    emissions_mode="net",
)

deterministic_ar6_cc(
    years=range(2020, 2051),
    category=["C1", "C2"],
    ssp_scenario=["SSP2"],
    emissions_mode="gross",
)

Including or excluding AFOLU emissions

include_afolu=False is the default and excludes Agriculture, Forestry and Other Land Use (AFOLU) emissions for the selected emission_type. Use include_afolu=True when the study objective requires Agriculture, Forestry and Other Land Use (AFOLU) emissions for the selected emission_type.

[ ]:

deterministic_ar6_cc(
    years=range(2020, 2051),
    category=["C1", "C2"],
    ssp_scenario=["SSP2"],
    include_afolu=True,
)