<no title>

{

“cells”: [

{

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“# TUTORIAL: Study objective B0, dynamic CC (uncertainty)”

], “id”: “cell-03bb9043e3”

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“AESA Phase B: (dynamic) carrying capacities definition.\n”, “Run aSoCC Monte Carlo uncertainty on extracted AR6 climate change pathways from process_ar6(…) outputs.”

], “id”: “cell-6a7cdf868e”

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“# Before starting…”

], “id”: “cell-118cc6223e”

}, {

“cell_type”: “markdown”, “id”: “f6b02f42”, “metadata”: {}, “source”: [

“### Set workspace”

]

}, {

“cell_type”: “markdown”, “id”: “47c4301c”, “metadata”: {}, “source”: [

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

]

}, {

“cell_type”: “code”, “execution_count”: null, “metadata”: {}, “outputs”: [], “source”: [

“from pyaesa import set_workspacen”, “n”, “# Windows example; update this path before running.n”, “set_workspace(r"C:\Users\username\Documents\aesa_workspace")n”, “n”, “# macOS example; update this path before running.n”, “# set_workspace("/Users/username/Documents/aesa_workspace")”

], “id”: “cell-3c1ccecd33”

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“### Run prerequisitesn”, “n”, “This tutorial assumes that the workspace has already been set, with all prerequisites available (downloads and processing).\n”, “If this is not your case, it is recommended to first go through the core prerequisite notebooks: [tutorials/core_prerequisites/0_set_workspace.ipynb](../../core_prerequisites/0_set_workspace.ipynb), [tutorials/core_prerequisites/1_download_data.ipynb](../../core_prerequisites/1_download_data.ipynb), and [tutorials/core_prerequisites/2_process_data.ipynb](../../core_prerequisites/2_process_data.ipynb).”

], “id”: “cell-2bf8c86ec6”

}, {

“cell_type”: “markdown”, “id”: “1e640f83”, “metadata”: {}, “source”: [

“# Basic features of the uncertainty function”

]

}, {

“cell_type”: “markdown”, “id”: “9e71afe0”, “metadata”: {}, “source”: [

“### In a nutshell”

]

}, {

“cell_type”: “markdown”, “id”: “fd298537”, “metadata”: {}, “source”: [

“The function takes necessary inputs, mainly for two purposes:n”, “- inputs for the deterministic function base_ar6_cc_args, including years, category, ssp_scenario, and dynamic carrying capacity emission route parameters.n”, “- inputs for the configuration of uncertainty analysis (Monte Carlo) through uncertainty_config. The AR6 CC uncertainty source list contains dynamic_ar6_cc_uncertainty, plus mc_parameters for the Monte Carlo run policy. dynamic_ar6_cc_uncertainty is active by default; its nested category_uncertainty option is inactive by default and must be requested explicitly.n”, “n”, “Set category_uncertainty=True when Monte Carlo should sample one AR6 climate category uniformly across the requested categories with retained model-scenario pairs, then sample a retained model-scenario pair within that category pool.n”, “n”, “The uncertainty output folder contains:n”, “- Monte Carlo run values and summary statistics.n”, “- results/README.txt explains the public row identity tables, run value fragments, run interval indexes, summary tables, source method logs, and compact CSV or Parquet reading contract.n”, “- Figures are rendered by default (figures=True). Use figures=False to skip them; figure_format controls the file format and resolution.n”, “- log files, including uncertainty source parameter logs.n”, “n”, “Basic features also involve:n”, “- overwriting of existing values: use the refresh parameter.”

]

}, {

“cell_type”: “markdown”, “id”: “bddd6de6”, “metadata”: {}, “source”: [

“Methodological details on AR6 scenario filtering, harmonization, gross emissions modes, and dynamic carrying capacity construction are documented in <a href="../../methodological_notes/methodological_note_steady_state_dynamic_cc.pdf">methodological_notes/methodological_note_steady_state_dynamic_cc.pdf</a>.n”

]

}, {

“cell_type”: “markdown”, “id”: “cell-026aa99b1a”, “metadata”: {}, “source”: [

“### Public argument checklistn”, “The table lists all arguments; the same definitions are available in the function docstring.n”, “n”, “<div class="pyaesa-argument-legend">n”, “<div class="pyaesa-default-block" style="color:#087f5b">Green items = default if omitted.</div>n”, “<div class="pyaesa-optional-block" style="color:#c45f00">Orange items = optional feature skipped if omitted.</div>n”, “</div>n”, “n”, “Do not write green or orange items when that behavior is intended.n”, “n”, “<details open>n”, “<summary><code>uncertainty_ar6_cc(…)</code> arguments</summary>n”, “n”, “<table>n”, “<thead><tr><th>Argument</th><th>Description</th></tr></thead>n”, “<tbody>n”, “<tr><td style="vertical-align:top; white-space:nowrap;"><code>base_ar6_cc_args</code></td><td>Deterministic AR6 CC selector envelope written as a 
dictionary. Required key: <code>years</code>. Accepted optional keys are 
<code>harmonization</code>, <code>harmonization_method</code>, <code>category</code>, 
<code>ssp_scenario</code>, <code>emission_type</code>, <code>include_afolu</code>, 
<code>emissions_mode</code>, and <code>subset_version</code>. 
  
Nested keys: 
  
• <code>years</code>: Study year selector provided as a consecutive year 
 list or <code>range(start_year, end_year + 1)</code>. The resolved years 
 must contain at least two consecutive years with no gaps. 
• <code>harmonization</code>: Whether to harmonize retained AR6 pathways 
 to the historical baseline. Defaults to <code>True</code>. 
• <code>harmonization_method</code>: Harmonization method applied only when 
 <code>harmonization=True</code>. Defaults to <code>"offset"</code>. The only 
 supported value is currently <code>"offset"</code>. 
 Ignored when <code>harmonization=False</code>. 
• <code>category</code>: AR6 category classification selector for global 
 warming trajectories. Accepts a string such as <code>"C3"</code> or a list such as 
 <code>["C1", "C2"]</code>. Valid values are <code>"C1"</code> through <code>"C8"</code>. 
 Defaults to <code>["C1", "C2", "C3", "C4"]</code>, the categories 
 aligned with the 2015 Paris Agreement. 
• <code>ssp_scenario</code>: SSP label selector as a string, list, or 
 <code>None</code>. Defaults to 
 <code>["SSP1", "SSP2", "SSP3", "SSP4", "SSP5"]</code>. 
• <code>emission_type</code>: Dynamic AR6 emission type. Accepted values 
 are <code>"kyoto_gases"</code> (default) and <code>"co2"</code>. 
 <code>emission_type="kyoto_gases"</code> uses the GWP100 Kyoto Gases 
 aggregate; <code>emission_type="co2"</code> uses direct CO2 pathways. 
• <code>include_afolu</code>: Whether AFOLU emissions are included inside 
 the selected <code>emission_type</code>. Defaults to <code>False</code>. 
• <code>emissions_mode</code>: Dynamic AR6 emissions mode. Accepted 
 values are <code>"net"</code>, <code>"gross"</code>, and <code>"gross_alt"</code>. 
 Defaults to <code>"gross_alt"</code>. <code>"net"</code> uses net AR6 emissions 
 pathways directly. <code>"gross"</code> removes all sequestration 
 sources from net emissions. <code>"gross_alt"</code> 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 
 <code>data_raw/methodological_notes/methodological_note_steady_state_dynamic_cc.pdf</code> 
 for the methodological explanation. 
• <code>subset_version</code>: Optional selector for a subset of AR6 
 model-scenario pairs. Follow 
 <code>data_processed/ar6/<processed_scope>/README_model_scenario_subset.txt</code> 
 to create the subset CSV. Defaults to <code>None</code>.</td></tr>n”, “<tr><td style="vertical-align:top; white-space:nowrap;"><code>uncertainty_config</code></td><td>Monte Carlo configuration dictionary. The default 
signature activates dynamic AR6 CC uncertainty. Category 
uncertainty is inactive by default. Source blocks use an 
<code>active</code> boolean; write <code>active=False</code> to disable dynamic AR6 
CC uncertainty. See 
<code>data_raw/methodological_notes/methodological_note_acc_uncertainty_sources.pdf</code> 
for uncertainty source definitions and mathematical expressions. 
  
Accepted keys: 
  
• <code>mc_parameters</code>: optional dictionary with <code>convergence</code> and 
 <code>fixed</code> mode blocks. Exactly one mode must be active. 
  
 Nested mode blocks: 
 
 • <code>convergence</code>: convergence mode block. This is the default 
 active mode. 
  
 Nested keys: 
 
 • <code>active</code>: Whether convergence mode is active. 
 • <code>max_runs</code>: Maximum number of Monte Carlo runs allowed 
 before stopping. 
 • <code>rtol</code>: Relative tolerance used to decide whether 
 monitored summary statistics have converged. 
 • <code>stable_runs</code>: Number of consecutive accepted runs that 
 must remain within tolerance before the run stops. 
 • <code>convergence_statistics</code>: Statistic monitored for 
 convergence. Monte Carlo convergence is mean only and 
 defaults to <code>["mean"]</code>. 
  
 • <code>fixed</code>: fixed run count mode block. 
  
 Nested keys: 
 
 • <code>active</code>: Whether fixed mode is active. 
 • <code>n_runs</code>: Exact number of Monte Carlo runs. 
  
• <code>dynamic_ar6_cc_uncertainty</code>: optional AR6 CC source block. It 
 defaults to <code>{"active": True, "sampling_method": "srs", "category_uncertainty": False}</code>. <code>sampling_method</code> accepts 
 <code>"srs"</code> for simple random sampling (samples across retained 
 model-scenario pairs matching the requested category and SSP) or 
 <code>"lhs"</code> for Latin hypercube sampling (samples among retained 
 models first, then among retained scenarios for the selected 
 model, category, and SSP to limit over representation of models 
 with more AR6 submissions). The effect of this choice is visible 
 in <code>process_ar6(…)</code> sampling diagnostic figures. 
 <code>category_uncertainty</code> is inactive by default. If <code>True</code>, 
 each Monte Carlo run first samples one retained AR6 category 
 with equal probability in the studied SSP pool. It then applies 
 <code>sampling_method</code> inside that selected category; with 
 <code>sampling_method="lhs"</code>, this means model first, then scenario 
 inside that model. 
  
 Nested keys: 
 
 • <code>active</code>: Whether dynamic AR6 carrying capacity uncertainty 
 is active. 
 • <code>sampling_method</code>: AR6 pathway sampling method. Accepted 
 values are <code>"srs"</code> and <code>"lhs"</code>. 
 • <code>category_uncertainty</code>: Whether each Monte Carlo run samples 
 one retained AR6 category before applying <code>sampling_method</code> 
 inside that category.</td></tr>n”, “<tr class="pyaesa-default-row" style="color:#087f5b;"><td style="vertical-align:top; white-space:nowrap;"><code>output_format</code></td><td>Public uncertainty table format, either 
<code>"csv_compact"</code> or <code>"parquet"</code>. Defaults to 
<code>"csv_compact"</code>.</td></tr>n”, “<tr class="pyaesa-default-row" style="color:#087f5b;"><td style="vertical-align:top; white-space:nowrap;"><code>figures</code></td><td>Whether to render figures. 
Default is <code>True</code>.</td></tr>n”, “<tr class="pyaesa-default-row" style="color:#087f5b;"><td style="vertical-align:top; white-space:nowrap;"><code>figure_format</code></td><td>Figure render settings mapping. Defaults to 
<code>{"format": "png", "dpi": 500}</code>. 
  
Nested keys: 
  
• <code>format</code>: Figure file format. Accepted values are <code>"png"</code>, 
 <code>"pdf"</code>, and <code>"svg"</code>. 
• <code>dpi</code>: Positive integer figure resolution used for raster 
 outputs.</td></tr>n”, “<tr class="pyaesa-default-row" style="color:#087f5b;"><td style="vertical-align:top; white-space:nowrap;"><code>refresh</code></td><td>If <code>True</code>, refresh the matching processed AR6 output scope selected by <code>process_ar6(…)</code>, the resolved deterministic AR6 CC output scope, and the resolved AR6 CC Monte Carlo outputs for this uncertainty request. The Monte Carlo refresh removes matching run folders for the current request under the adjacent <code>monte_carlo</code> root of that deterministic output scope. For example, matching AR6 CC Monte Carlo run folders are refreshed under <code><repo>/data_processed/ar6/2019-2060_harmonization_offset/ar6_cc/gross_alt_kyoto_gases_wo_afolu/C1_SSP1/monte_carlo/mc_<generated_id></code>. Raw downloads and downstream aCC or ASR outputs are not refreshed. Defaults to <code>False</code>.</td></tr>n”, “</tbody>n”, “</table>n”, “n”, “</details>n”

]

}, {

“cell_type”: “markdown”, “id”: “2bc41a33”, “metadata”: {}, “source”: [

“### Dynamic AR6 CC Monte Carlo in default convergence mode”

]

}, {

“cell_type”: “code”, “execution_count”: null, “id”: “73a0ac14”, “metadata”: {}, “outputs”: [], “source”: [

“from pyaesa import uncertainty_ar6_ccn”, “n”, “uncertainty_ar6_cc(n”, “ base_ar6_cc_args={n”, “ "years": range(2020, 2051),n”, “ "category": ["C1", "C2"],n”, “ "ssp_scenario": ["SSP2"],n”, “ },n”, “ uncertainty_config={n”, “ # mc_parameters is omitted, so Monte Carlo uses convergence mode defaults.n”, “ # To change convergence tolerance or maximum run count, add for example:n”, “ # "mc_parameters": {"convergence": {"rtol": 0.02, "max_runs": 100000}},n”, “ "dynamic_ar6_cc_uncertainty": {n”, “ "category_uncertainty": True,n”, “ },n”, “ },n”, “)”

]

}, {

“cell_type”: “markdown”, “id”: “570a502e”, “metadata”: {}, “source”: [

“# What to do next”

]

}, {

“cell_type”: “markdown”, “id”: “a8c0bcc2”, “metadata”: {}, “source”: [

“Beginnersn”, “n”, “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.n”, “Have a look at the other notebooks available at [tutorials/study_objectives/0_study_objectives.md](../0_study_objectives.md)n”, “n”, “Expertsn”, “n”, “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 !”

]

}, {

“cell_type”: “markdown”, “id”: “07ae20ba”, “metadata”: {}, “source”: [

“# Advanced features”

]

}, {

“cell_type”: “markdown”, “id”: “3524122d”, “metadata”: {}, “source”: [

“Advanced features currently available include:n”, “- Changing the sampling method for the Monte Carlo simulationn”, “- Changing convergence tolerance or maximum runs”

]

}, {

“cell_type”: “markdown”, “id”: “a3fe7294”, “metadata”: {}, “source”: [

“### Changing the sampling method for the Monte Carlo simulation”

]

}, {

“cell_type”: “markdown”, “id”: “7122f8b3”, “metadata”: {}, “source”: [

“dynamic_ar6_cc_uncertainty["sampling_method"] selects how retained AR6n”, “model-scenario rows are sampled.n”, “n”, “- "srs" is the default simple random sampling across retained model-scenarion”, “ pairs matching the requested category and SSP filters.n”, “- "lhs" samples a model first, then samples one retained scenario for thatn”, “ model, category, and SSP. This limits over representation of models with moren”, “ AR6 submissions.n”, “n”, “category_uncertainty=True can be combined with either sampling method. Inn”, “that case each Monte Carlo run first samples one retained AR6 category, thenn”, “samples a model-scenario row inside that category.”

]

}, {

“cell_type”: “code”, “id”: “8b5e6aa4”, “metadata”: {}, “source”: [

“uncertainty_ar6_cc(n”, “ base_ar6_cc_args={n”, “ "years": range(2020, 2051),n”, “ "category": ["C1", "C2"],n”, “ "ssp_scenario": ["SSP2"],n”, “ },n”, “ uncertainty_config={n”, “ "mc_parameters": {n”, “ "fixed": {"active": True, "n_runs": 1000},n”, “ "convergence": {"active": False},n”, “ },n”, “ "dynamic_ar6_cc_uncertainty": {n”, “ "sampling_method": "lhs",n”, “ "category_uncertainty": True,n”, “ },n”, “ },n”, “)”

], “execution_count”: null, “outputs”: []

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“### Changing convergence tolerance or maximum runs”

], “id”: “cell-cd62ca67aa”

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“mc_parameters["convergence"] controls convergence mode. Omit mc_parametersn”, “when the default convergence settings are sufficient; write the block only whenn”, “the study needs a different rtol or max_runs value.”

], “id”: “cell-0a49ac16e5”

}, {

“cell_type”: “code”, “metadata”: {}, “source”: [

“uncertainty_ar6_cc(n”, “ base_ar6_cc_args={n”, “ "years": range(2020, 2051),n”, “ "category": ["C1", "C2"],n”, “ "ssp_scenario": ["SSP2"],n”, “ },n”, “ uncertainty_config={n”, “ "mc_parameters": {n”, “ "convergence": {n”, “ "rtol": 0.02,n”, “ },n”, “ },n”, “ },n”, “)”

], “id”: “cell-14b78b4e95”, “execution_count”: null, “outputs”: []

}

], “metadata”: {

“kernelspec”: {
“display_name”: “env-pyaesa-test”, “language”: “python”, “name”: “python3”

}, “language_info”: {

“codemirror_mode”: {
“name”: “ipython”, “version”: 3

}, “file_extension”: “.py”, “mimetype”: “text/x-python”, “name”: “python”, “nbconvert_exporter”: “python”, “pygments_lexer”: “ipython3”, “version”: “3.13.13”

}

}, “nbformat”: 4, “nbformat_minor”: 5

}