Skip to content

Pathway Allocation Functions

Pathway allocation functions generate annual emission allocation shares over time.

Overview

All pathway allocation approaches return a PathwayAllocationResult containing:

  • approach: Name of the allocation approach used
  • parameters: Dictionary of parameters used in the calculation
  • relative_shares_pathway_emissions: DataFrame of annual shares (sum to 1.0 each year)

Per Capita Pathways

equal_per_capita

fair_shares.library.allocations.pathways.per_capita.equal_per_capita

Python
equal_per_capita(
    population_ts: TimeseriesDataFrame,
    first_allocation_year: int,
    emission_category: str,
    preserve_first_allocation_year_shares: bool = False,
    group_level: str = "iso3c",
    unit_level: str = "unit",
    ur: PlainRegistry = get_default_unit_registry(),
) -> PathwayAllocationResult

Equal per capita pathway allocation based on population shares.

Allocates emissions in proportion to population, with no adjustments for pre-allocation responsibility or economic capability.

Mathematical Foundation

Mode 1: Dynamic shares (preserve_first_allocation_year_shares=False, default)

Population shares are calculated at each year from first_allocation_year onwards. This accounts for changes in relative population shares over time:

\[ A(g, t) = \frac{P(g, t)}{\sum_{g'} P(g', t)} \]

Where:

  • \(A(g, t)\): Allocation share for country \(g\) at year \(t\)
  • \(P(g, t)\): Population of country \(g\) at year \(t\)
  • \(\sum_{g'} P(g', t)\): Total world population at year \(t\)

Mode 2: Preserved shares (preserve_first_allocation_year_shares=True)

Population shares calculated at the first_allocation_year are preserved across all periods. This means the relative allocation between groups remains constant:

\[ A(g, t) = \frac{P(g, t_a)}{\sum_{g'} P(g', t_a)} \quad \forall t \geq t_a \]

Where:

  • \(A(g, t)\): Allocation share for country \(g\) at year \(t\) (constant for all \(t \geq t_a\))
  • \(P(g, t_a)\): Population of country \(g\) at first allocation year \(t_a\)
  • \(\sum_{g'} P(g', t_a)\): Total world population at first allocation year

Parameters:

Name Type Description Default
population_ts TimeseriesDataFrame

Population time series for each group of interest.

 required
first_allocation_year int

First year that should be used for calculating the allocation. This must be a column in population_ts. See the allocation_year section in docs/science/parameter-effects.md for how this affects country shares

 required
emission_category str

Emission category to include in the output.

 required
preserve_first_allocation_year_shares bool

If False (default), shares are calculated at each year from first_allocation_year onwards. If True, shares calculated at the first_allocation_year are preserved across all periods.

 False
group_level str

Index level name for grouping (typically 'iso3c'). Default: 'iso3c'

 'iso3c'
unit_level str

Index level name for units. Default: 'unit'

 'unit'
ur PlainRegistry

Pint unit registry for unit conversions.

 get_default_unit_registry()

Returns:

Type Description
PathwayAllocationResult

Relative shares over time, summing to unity each year.
Notes

Theoretical grounding:

The equal per capita principle treats the atmosphere as a finite shared resource with equal claims per person. With a past first_allocation_year, it also accounts for historical responsibility: emissions since that year consume part of each country's pathway allocation, giving less to higher-emitting countries.

See docs/science/allocations.md for theoretical grounding and limitations.

See Also

per_capita_adjusted : With pre-allocation responsibility/capability adjustments per_capita_adjusted_gini : With Gini-adjusted GDP

per_capita_adjusted

fair_shares.library.allocations.pathways.per_capita.per_capita_adjusted

Python
per_capita_adjusted(
    population_ts: TimeseriesDataFrame,
    first_allocation_year: int,
    emission_category: str,
    country_actual_emissions_ts: (
        TimeseriesDataFrame | None
    ) = None,
    responsibility_emissions_ts: (
        TimeseriesDataFrame | None
    ) = None,
    gdp_ts: TimeseriesDataFrame | None = None,
    pre_allocation_responsibility_weight: float = 0.0,
    capability_weight: float = 0.0,
    pre_allocation_responsibility_year: int = 1990,
    pre_allocation_responsibility_per_capita: bool = False,
    pre_allocation_responsibility_exponent: float = 1.0,
    pre_allocation_responsibility_functional_form: str = "asinh",
    capability_per_capita: bool = True,
    capability_exponent: float = 1.0,
    capability_functional_form: str = "asinh",
    capability_reference_year: int | None = None,
    max_deviation_sigma: float | None = None,
    preserve_first_allocation_year_shares: bool = False,
    historical_discount_rate: float = 0.0,
    group_level: str = "iso3c",
    unit_level: str = "unit",
    ur: PlainRegistry = get_default_unit_registry(),
) -> PathwayAllocationResult

Per capita pathway allocation with pre-allocation responsibility and capability adjustments.

Extends equal per capita by incorporating:

  • Pre-allocation responsibility adjustment: Countries with higher historical emissions receive smaller allocations
  • Capability adjustment: Countries with higher GDP (per capita or absolute) receive smaller allocations
Mathematical Foundation

Mode 1: Dynamic adjusted shares (preserve_first_allocation_year_shares=False, default)

Shares are computed by adjusting population at each year:

\[ A(g, t) = \frac{P_{\text{adj}}(g, t)}{\sum_{g'} P_{\text{adj}}(g', t)} \]

Where the adjusted population is:

\[ P_{\text{adj}}(g, t) = P(g, t) \times R(g) \times C(g, t) \]

Where:

  • \(A(g, t)\): Allocation share for country \(g\) at year \(t\)
  • \(P_{\text{adj}}(g, t)\): Adjusted population of country \(g\) at year \(t\)
  • \(P(g, t)\): Actual population of country \(g\) at year \(t\)
  • \(R(g)\): Pre-allocation responsibility adjustment factor (constant over time, equals 1.0 if not used)
  • \(C(g, t)\): Capability adjustment factor (time-varying, equals 1.0 if not used)

Mode 2: Preserved adjusted shares (preserve_first_allocation_year_shares=True)

Shares calculated at first_allocation_year are broadcast across all years.

Pre-Allocation Responsibility Adjustment

The pre-allocation responsibility metric is based on cumulative historical emissions from pre_allocation_responsibility_year to first_allocation_year.

For per capita pre-allocation responsibility (:code:pre_allocation_responsibility_per_capita=True):

\[ R(g) = \left(\frac{\sum_{t=t_h}^{t_a} E(g, t)}{\sum_{t=t_h}^{t_a} P(g, t)}\right)^{-w_r \times e_r} \]

Where:

  • \(R(g)\): Pre-allocation responsibility adjustment factor (inverse - higher emissions = lower allocation)
  • \(E(g, t)\): Emissions of country \(g\) in year \(t\)
  • \(t_h\): Pre-allocation responsibility start year
  • \(t_a\): First allocation year
  • \(w_r\): Normalized pre-allocation responsibility weight
  • \(e_r\): Pre-allocation responsibility exponent

For absolute pre-allocation responsibility (:code:pre_allocation_responsibility_per_capita=False, default):

\[ R(g) = \left(\sum_{t=t_h}^{t_a} E(g, t)\right)^{-w_r \times e_r} \]

Capability Adjustment

The capability metric is based on cumulative GDP per capita from first_allocation_year up to year :math:t.

For per capita capability (:code:capability_per_capita=True, default):

\[ C(g, t) = \left(\frac{\sum_{t'=t_a}^{t} \text{GDP}(g, t')}{\sum_{t'=t_a}^{t} P(g, t')}\right)^{-w_c \times e_c} \]

Where:

  • \(C(g, t)\): Capability adjustment factor (inverse - higher cumulative GDP per capita = lower allocation)
  • \(\text{GDP}(g, t')\): Gross domestic product of country \(g\) in year \(t'\)
  • \(w_c\): Normalized capability weight
  • \(e_c\): Capability exponent

For absolute capability (:code:capability_per_capita=False):

\[ C(g, t) = \left(\sum_{t'=t_a}^{t} \text{GDP}(g, t')\right)^{-w_c \times e_c} \]

Deviation Constraint

When :code:max_deviation_sigma is provided, shares are constrained to prevent extreme deviations from equal per capita. The constraint limits allocations to within :math:\sigma standard deviations of the equal per capita baseline.

Parameters:

Name Type Description Default
population_ts TimeseriesDataFrame

Population time series for per capita calculations.

 required
first_allocation_year int

Starting year for the allocation pathway. Shares are computed from this year onwards. See docs/science/parameter-effects.md §allocation_year for how the choice of year affects country shares.

 required
emission_category str

Emission category (e.g., 'co2-ffi', 'all-ghg').

 required
country_actual_emissions_ts TimeseriesDataFrame | None

Pre-allocation responsibility. Country emissions used to compute cumulative emissions in the window [pre_allocation_responsibility_year, first_allocation_year). Required when pre_allocation_responsibility_weight > 0.

 None
gdp_ts TimeseriesDataFrame | None

Capability. GDP time series used from first_allocation_year onwards. Required when capability_weight > 0.

 None
pre_allocation_responsibility_weight float

Pre-allocation responsibility. Relative weight (0–1). Only the ratio to capability_weight matters — (0.5, 0.5) is identical to (1.0, 1.0). When 0, pre-allocation responsibility is disabled. See docs/science/parameter-effects.md §weights.

 0.0
capability_weight float

Capability. Relative weight (0–1). Applies from first_allocation_year onwards (contrast with pre-allocation responsibility, which covers the window before it). When 0, capability is disabled. See docs/science/parameter-effects.md §weights.

 0.0
pre_allocation_responsibility_year int

Pre-allocation responsibility. Start year of the historical window [pre_allocation_responsibility_year, first_allocation_year). Default: 1990.

 1990
pre_allocation_responsibility_per_capita bool

Pre-allocation responsibility. If True, cumulative emissions are divided by cumulative population before computing the adjustment factor. If False (default), absolute cumulative emissions are used.

 False
pre_allocation_responsibility_exponent float

Pre-allocation responsibility. Exponent applied to the emissions metric. Higher values amplify differences between countries. Default: 1.0.

 1.0
pre_allocation_responsibility_functional_form str

Pre-allocation responsibility. Transformation applied to the raw metric: 'asinh' (default), 'power', or 'linear'. 'asinh' compresses extreme values.

 'asinh'
capability_per_capita bool

Capability. If True (default), GDP is divided by population before computing the capability factor. If False, absolute GDP is used.

 True
capability_exponent float

Capability. Exponent applied to the GDP metric. Higher values amplify differences between countries. Default: 1.0.

 1.0
capability_functional_form str

Capability. Transformation applied to the raw GDP metric: 'asinh' (default), 'power', or 'linear'.

 'asinh'
capability_reference_year int | None

Capability. When None (default), capability is computed year-by-year. When set, the GDP (per capita) metric from that single year is broadcast across the pathway window — the same snapshot semantics as the budget approaches. A year before the first allocation year is sourced from the unfiltered inputs (without Gini adjustment); a year beyond the last observed GDP year falls back to the last observed column with a warning.

 None
max_deviation_sigma float | None

Constraint. Maximum allowed deviation from equal per capita baseline, in population-weighted standard deviations. Prevents extreme adjustments. None (default) means no constraint.

 None
preserve_first_allocation_year_shares bool

Mode. If False (default), shares are recalculated at each year. If True, shares from first_allocation_year are held constant for all subsequent years.

 False
historical_discount_rate float

Pre-allocation responsibility. Discount rate for historical emissions (0.0 to <1.0). Weights earlier emissions less via (1 - rate)^(reference_year - t). Default: 0.0 (no discounting). Only affects the pre-allocation responsibility calculation.

 0.0
group_level str

Index level name for grouping. Default: 'iso3c'.

 'iso3c'
unit_level str

Index level name for units. Default: 'unit'.

 'unit'
ur PlainRegistry

Pint unit registry for unit conversions.

 get_default_unit_registry()

Returns:

Type Description
PathwayAllocationResult

Relative shares over time, summing to unity each year.
Notes

Theoretical grounding:

This approach provides explicit mechanisms for differentiating allocations:

  • Pre-allocation Responsibility Rescaling: Multiplicative rescaling of shares based on cumulative per-capita emissions in a historical window — an alternative to the responsibility accounting that comes from setting first_allocation_year in the past (where past emissions consume allocation)
  • Capability (Ability to Pay): Adjusts based on economic resources from the first allocation year onwards — countries with greater capacity bear greater obligations

CBDR-RC can be operationalized either through a past first_allocation_year (responsibility via consumed budget) combined with capability adjustments, or through pre-allocation responsibility rescaling, or both.

Parameter choices involve normative judgments that should be made transparently:

  • Choice of start year for pre-allocation responsibility
  • Whether to use per capita or absolute metrics
  • Choice of GDP indicator (PPP vs. MER)
  • Transformation of indicators onto allocation scales

See docs/science/allocations.md for theoretical grounding.

GDP window: When the allocation pathway extends past the last year of the input gdp_ts, the cumulative GDP per capita values from the last observed year are forward-filled to cover the full pathway. This preserves the cross-country capability ratios of the last observed year, but those ratios then get weighted against the full post-observation population trajectory. Users who want different post-observation capability dynamics (SSP2 projections, custom growth assumptions, or a future-extended WDI release) should extend the input gdp_ts time series before calling this function. The forward-fill is the minimum-disruption default when no projected GDP data is supplied.

See Also

equal_per_capita : Without adjustments per_capita_adjusted_gini : With Gini-adjusted GDP

per_capita_adjusted_gini

fair_shares.library.allocations.pathways.per_capita.per_capita_adjusted_gini

Python
per_capita_adjusted_gini(
    population_ts: TimeseriesDataFrame,
    first_allocation_year: int,
    emission_category: str,
    country_actual_emissions_ts: (
        TimeseriesDataFrame | None
    ) = None,
    responsibility_emissions_ts: (
        TimeseriesDataFrame | None
    ) = None,
    gdp_ts: TimeseriesDataFrame | None = None,
    gini_s: DataFrame | None = None,
    pre_allocation_responsibility_weight: float = 0.0,
    capability_weight: float = 0.0,
    pre_allocation_responsibility_year: int = 1990,
    pre_allocation_responsibility_per_capita: bool = False,
    pre_allocation_responsibility_exponent: float = 1.0,
    pre_allocation_responsibility_functional_form: str = "asinh",
    capability_per_capita: bool = True,
    capability_exponent: float = 1.0,
    capability_functional_form: str = "asinh",
    capability_reference_year: int | None = None,
    income_floor: float = 0.0,
    max_gini_adjustment: float = 0.8,
    max_deviation_sigma: float | None = None,
    preserve_first_allocation_year_shares: bool = False,
    historical_discount_rate: float = 0.0,
    group_level: str = "iso3c",
    unit_level: str = "unit",
    ur: PlainRegistry = get_default_unit_registry(),
) -> PathwayAllocationResult

Per capita pathway allocation with pre-allocation responsibility, capability, and Gini adjustments.

The most comprehensive variant, incorporating:

  • Pre-allocation responsibility adjustment: Countries with higher historical emissions receive smaller allocations
  • Capability adjustment: Countries with higher Gini-adjusted GDP (per capita or absolute) receive smaller allocations
  • Gini adjustment: GDP is adjusted for income inequality within countries
Mathematical Foundation

Similar to :func:per_capita_adjusted, but capability uses Gini-adjusted GDP to account for income inequality within countries.

Gini Adjustment Process

GDP is adjusted using an interpretation of the Greenhouse Development Rights (GDR) framework's capability metric (note: GDR was designed for burden-sharing; fair-shares adapts its capability calculation for entitlement allocation). Only income above a development threshold counts as capability. When combined with the income floor, higher inequality means more national income sits above the threshold — increasing measured capability. See :func:~fair_shares.library.utils.math.allocation.calculate_gini_adjusted_gdp for the full mathematical derivation.

Capability Adjustment with Gini-Adjusted GDP

For per capita capability (:code:capability_per_capita=True, default):

\[ C(g, t) = \left(\frac{\sum_{t'=t_a}^{t} \text{GDP}^{\text{adj}}(g, t')}{\sum_{t'=t_a}^{t} P(g, t')}\right)^{-w_c \times e_c} \]

Where:

  • \(C(g, t)\): Capability adjustment factor using Gini-adjusted GDP
  • \(\text{GDP}^{\text{adj}}(g, t')\): Gini-adjusted GDP in year \(t'\)
  • \(P(g, t')\): Population in year \(t'\)
  • \(t_a\): First allocation year
  • \(w_c\): Normalized capability weight
  • \(e_c\): Capability exponent

For absolute capability (:code:capability_per_capita=False):

\[ C(g, t) = \left(\sum_{t'=t_a}^{t} \text{GDP}^{\text{adj}}(g, t')\right)^{-w_c \times e_c} \]

Gini Adjustment Effect

When combined with the income floor, higher inequality means more national income sits above the development threshold, creating larger per-person excesses. Countries with high inequality and high GDP thus receive smaller emission allocations (higher measured capability = more ability to pay). See :func:~fair_shares.library.utils.math.allocation.calculate_gini_adjusted_gdp for worked examples.

Parameters:

Name Type Description Default
population_ts TimeseriesDataFrame

Population time series for per capita calculations.

 required
first_allocation_year int

Year from which to begin the allocation pathway. See docs/science/parameter-effects.md §allocation_year.

 required
emission_category str

Emission category (e.g., 'co2-ffi', 'all-ghg').

 required
country_actual_emissions_ts TimeseriesDataFrame | None

Pre-allocation responsibility. Country emissions used to compute cumulative emissions in the window [pre_allocation_responsibility_year, first_allocation_year). Required when pre_allocation_responsibility_weight > 0.

 None
gdp_ts TimeseriesDataFrame | None

Capability. GDP time series used from first_allocation_year onwards. Required when capability_weight > 0 or gini_s is provided.

 None
gini_s DataFrame | None

Gini. Gini coefficients for within-country income inequality. Used to adjust GDP before computing the capability factor.

 None
pre_allocation_responsibility_weight float

Pre-allocation responsibility. Relative weight (0–1). Only the ratio to capability_weight matters. When 0, pre-allocation responsibility is disabled.

 0.0
capability_weight float

Capability. Relative weight (0–1). Applies from first_allocation_year onwards. When 0, capability is disabled.

 0.0
pre_allocation_responsibility_year int

Pre-allocation responsibility. Start year of the historical window [pre_allocation_responsibility_year, first_allocation_year). Default: 1990.

 1990
pre_allocation_responsibility_per_capita bool

Pre-allocation responsibility. If True, uses per-capita cumulative emissions. If False (default), uses absolute cumulative emissions.

 False
pre_allocation_responsibility_exponent float

Pre-allocation responsibility. Exponent applied to the emissions metric. Default: 1.0.

 1.0
pre_allocation_responsibility_functional_form str

Pre-allocation responsibility. Transformation: 'asinh' (default), 'power', or 'linear'.

 'asinh'
capability_per_capita bool

Capability. If True (default), Gini-adjusted GDP is divided by population. If False, absolute Gini-adjusted GDP is used.

 True
capability_exponent float

Capability. Exponent applied to the Gini-adjusted GDP metric. Default: 1.0.

 1.0
capability_functional_form str

Capability. Transformation: 'asinh' (default), 'power', or 'linear'.

 'asinh'
capability_reference_year int | None

Capability. When None (default), capability is computed year-by-year. When set, the GDP (per capita) metric from that single year is broadcast across the pathway window — the same snapshot semantics as the budget approaches. A year before the first allocation year is sourced from the unfiltered inputs (without Gini adjustment); a year beyond the last observed GDP year falls back to the last observed column with a warning.

 None
income_floor float

Gini. Development threshold in USD PPP per capita. Income below this is excluded from capability calculations, adapted from GDR. Default: 0.0 (all income counts); pass 7500.0 for the GDR threshold. See docs/science/parameter-effects.md §income_floor.

 0.0
max_gini_adjustment float

Gini. Maximum reduction factor from threshold deduction (0–1). Limits how much the deduction can reduce effective GDP. Default: 0.8.

 0.8
max_deviation_sigma float | None

Constraint. Maximum allowed deviation from equal per capita baseline, in population-weighted standard deviations. None (default) means no constraint.

 None
preserve_first_allocation_year_shares bool

Mode. If False (default), shares are recalculated at each year. If True, shares from first_allocation_year are held constant.

 False
historical_discount_rate float

Pre-allocation responsibility. Discount rate for historical emissions (0.0 to <1.0), via (1 - rate)^(reference_year - t) Default: 0.0. Only affects the pre-allocation responsibility calculation.

 0.0
group_level str

Index level name for grouping. Default: 'iso3c'.

 'iso3c'
unit_level str

Index level name for units. Default: 'unit'.

 'unit'
ur PlainRegistry

Pint unit registry for unit conversions.

 get_default_unit_registry()

Returns:

Type Description
PathwayAllocationResult

Relative shares over time, summing to unity each year.
Notes

Theoretical grounding:

This approach extends capability-based allocation by incorporating intra-national inequality via the GDR development threshold (adapted for entitlement allocation from GDR's burden-sharing context). Only income above the development threshold counts toward capability. When combined with the income floor, higher inequality means more national income sits above the threshold. See :func:~fair_shares.library.utils.math.allocation.calculate_gini_adjusted_gdp for the mathematical formulation.

See docs/science/allocations.md for theoretical grounding.

GDP window: When the allocation pathway extends past the last year of the input gdp_ts, the cumulative (Gini-adjusted) GDP per capita values from the last observed year are forward-filled to cover the full pathway. This preserves the cross-country capability ratios of the last observed year, but those ratios then get weighted against the full post-observation population trajectory. Users who want different post-observation capability dynamics (SSP2 projections, custom growth assumptions, or a future-extended WDI release) should extend the input gdp_ts time series before calling this function. Gini coefficients are looked up per-country and are not part of this forward-fill — only the GDP series is extended in time.

See Also

equal_per_capita : Without adjustments per_capita_adjusted : Without Gini adjustment

Convergence Pathways

per_capita_convergence

fair_shares.library.allocations.pathways.per_capita_convergence.per_capita_convergence

Python
per_capita_convergence(
    population_ts: TimeseriesDataFrame,
    country_actual_emissions_ts: TimeseriesDataFrame,
    first_allocation_year: int,
    convergence_year: int,
    emission_category: str,
    group_level: str = "iso3c",
    unit_level: str = "unit",
    ur: PlainRegistry = get_default_unit_registry(),
) -> PathwayAllocationResult

Per capita convergence pathway blending grandfathering and equal per capita.

This approach transitions from grandfathering (GF) to equal per capita (EPC) from allocation time, \(t_{a}\), to convergence time, \(t_{conv}\), using a linear weight \(M(t)\). It implements a variant of Contraction and Convergence, where global emissions contract while per capita emissions converge to equality by a target date.

Mathematical Foundation

Baseline Shares at Allocation Time

Grandfathering and equal per capita shares at allocation time are calculated as:

\[ \mathrm{GF}(g) = \frac{E(g, t_{a})}{\sum_{g'} E(g', t_{a})} \]
\[ \mathrm{EPC}(g) = \frac{P(g, t_{a})}{\sum_{g'} P(g', t_{a})} \]

Where:

  • \(E(g, t_{a})\): Emissions of country \(g\) at first allocation year \(t_a\)
  • \(P(g, t_{a})\): Population of country \(g\) at first allocation year \(t_a\)

Time-Dependent Blending Weight

The transition weight \(M(t)\) controls the blend between grandfathering and equal per capita:

  • \(M(t) = 1\) for \(t \le t_{a}\) (full grandfathering at start)
  • \(M(t) = \frac{t_{conv} - t}{t_{conv} - t_{a}}\) for \(t_{a} < t < t_{conv}\)
  • \(M(t) = 0\) for \(t \ge t_{conv}\) (full equal per capita at convergence)

Blended Allocation

The final allocation blends the two principles:

\[ A(g, t) = M(t) \cdot \mathrm{GF}(g) + (1 - M(t)) \cdot \mathrm{EPC}(g) \]

Parameters:

Name Type Description Default
population_ts TimeseriesDataFrame

Timeseries of population for each group of interest.

 required
country_actual_emissions_ts TimeseriesDataFrame

Timeseries of emissions for each group of interest.

 required
first_allocation_year int

First year that should be used for calculating the allocation. This must be a column in both population and emissions.

 required
convergence_year int

Year by which allocations fully converge to equal per capita.

 required
emission_category str

Emission category to include in the output.

 required
group_level str

Level in index specifying group information. Default: 'iso3c'

 'iso3c'
unit_level str

Level in index specifying units. Default: 'unit'

 'unit'
ur PlainRegistry

The unit registry to use for calculations.

 get_default_unit_registry()

Returns:

Type Description
PathwayAllocationResult

Container with relative shares for pathway emissions allocation. The TimeseriesDataFrame contains all years from first_allocation_year onwards with shares that sum to 1 across groups for the specified emission category.
Notes
See Also

per_capita_adjusted : Equal per capita with pre-allocation responsibility/capability adjustments cumulative_per_capita_convergence : Convergence accounting for cumulative emissions

cumulative_per_capita_convergence

fair_shares.library.allocations.pathways.cumulative_per_capita_convergence.cumulative_per_capita_convergence

Python
cumulative_per_capita_convergence(
    population_ts: TimeseriesDataFrame,
    country_actual_emissions_ts: TimeseriesDataFrame,
    first_allocation_year: int,
    emission_category: str,
    world_scenario_emissions_ts: TimeseriesDataFrame,
    max_deviation_sigma: float | None = None,
    max_convergence_speed: float = 0.9,
    strict: bool = True,
    convergence_method: str = "minimum-speed",
    convergence_year: int | None = None,
    group_level: str = "iso3c",
    unit_level: str = "unit",
    ur: PlainRegistry = get_default_unit_registry(),
) -> PathwayAllocationResult

Pure cumulative per capita convergence allocation without adjustments.

Allocates emissions based on cumulative population shares, converging from initial emission shares to cumulative per capita targets over time.

Mathematical Foundation

Convergence Dynamics

The allocation shares evolve through exponential convergence:

\[ A(g, t+1) = A(g, t) + \lambda \big(A^{\infty}(g) - A(g, t)\big) \]

Where:

  • \(A(g, t)\): Allocation share for country \(g\) at year \(t\)
  • \(A^{\infty}(g)\): Long-run target share that each year converges toward
  • \(\lambda\): Convergence speed (automatically determined to be minimum feasible)

Initial Shares

Initial shares at first_allocation_year are based on actual emissions:

\[ A(g, t_a) = \frac{E(g, t_a)}{\sum_{g'} E(g', t_a)} \]

Where:

  • \(A(g, t_a)\): Initial allocation share for country \(g\) at first allocation year
  • \(E(g, t_a)\): Actual emissions of country \(g\) at year \(t_a\)
  • \(t_a\): First allocation year
  • \(\sum_{g'} E(g', t_a)\): Total world emissions at first allocation year

Cumulative Target Shares

The cumulative target shares are based on cumulative population:

\[ T_{\text{cum}}(g) = \frac{\sum_{t \geq t_a} P(g, t)}{\sum_{g'} \sum_{t \geq t_a} P(g', t)} \]

Where:

  • \(T_{\text{cum}}(g)\): Cumulative target share for country \(g\)
  • \(P(g, t)\): Population of country \(g\) at year \(t\)
  • \(\sum_{t \geq t_a} P(g, t)\): Cumulative population of country \(g\) from allocation year onwards
  • \(\sum_{g'} \sum_{t \geq t_a} P(g', t)\): Total cumulative world population from allocation year onwards

Convergence Speed Determination

The convergence speed \(\lambda\) is automatically determined to be the minimum speed that ensures cumulative allocations match targets:

\[ \sum_{t \geq t_a} w(t) \, A(g, t) = T_{\text{cum}}(g) \]

Where:

  • \(w(t)\): Year weight for year \(t\), defined as \(w(t) = \frac{W(t)}{\sum_{t' \geq t_a} W(t')}\)
  • \(W(t)\): World emissions in year \(t\) from the scenario pathway

Deviation Constraint

When :code:max_deviation_sigma is provided, cumulative target shares are constrained to prevent extreme deviations from equal cumulative per capita:

\[ T_{\text{equal}}(g) - \sigma \, s \leq T_{\text{cum}}(g) \leq T_{\text{equal}}(g) + \sigma \, s \]

Where:

  • \(T_{\text{equal}}(g)\): Equal cumulative per capita baseline share
  • \(\sigma\): Maximum deviation parameter (e.g., 2.0 standard deviations)
  • \(s\): Population-weighted standard deviation of unconstrained cumulative targets

Parameters:

Name Type Description Default
population_ts TimeseriesDataFrame

Population time series for calculating cumulative per capita shares.

 required
country_actual_emissions_ts TimeseriesDataFrame

Country emissions for calculating initial shares at first_allocation_year.

 required
world_scenario_emissions_ts TimeseriesDataFrame

World emissions pathway defining the time horizon and year weights.

 required
first_allocation_year int

Starting year for the allocation.

 required
emission_category str

The emission category (e.g., 'co2-ffi', 'all-ghg').

 required
max_deviation_sigma float | None

Maximum allowed deviation from equal per capita baseline in terms of population-weighted standard deviations. If provided, constrains each group's share to be within ±max_deviation_sigma standard deviations from the baseline equal per capita share. If None, no constraint is applied.

 None
max_convergence_speed float

Maximum allowed convergence speed (0 to 1.0). Lower values create smoother pathways but may become infeasible. Default: 0.9.

 0.9
strict bool

If True (default), raise error for infeasible convergence. If False, use nearest feasible solution with warnings.

 True
convergence_method str

Convergence algorithm to use. "minimum-speed" (default): exponential convergence with binary-search for minimum feasible speed. "sine-deviation": iterative sine-shaped correction from a PCC baseline; requires convergence_year.

 'minimum-speed'
convergence_year int | None

Year by which allocations converge to equal per capita. Required when convergence_method='sine-deviation'. Must be > first_allocation_year. Default: None.

 None
group_level str

Index level name for grouping (typically 'iso3c'). Default: 'iso3c'

 'iso3c'
unit_level str

Index level name for units. Default: 'unit'

 'unit'
ur PlainRegistry

Pint unit registry for unit conversions.

 get_default_unit_registry()

Returns:

Type Description
PathwayAllocationResult

Relative shares over time, summing to unity each year.
Notes

Theoretical grounding:

For convergence mechanism foundations, use cases, and limitations, see: docs/science/allocations.md#convergence-mechanism-pathways-only

The base convergence approach drives toward equal cumulative per capita targets. The first_allocation_year choice affects normative positioning: a past year means historical emissions since then consume part of each country's cumulative target, directly incorporating responsibility. Combined with capability adjustments (available in the _adjusted variants), this already operationalizes CBDR-RC without needing explicit pre-allocation responsibility rescaling. See docs/science/principle-to-code.md for implementation examples.

For capability adjustments or explicit pre-allocation responsibility rescaling, use cumulative_per_capita_convergence_adjusted or cumulative_per_capita_convergence_adjusted_gini.

Convergence Speed

The convergence speed is automatically determined to be the minimum speed that ensures cumulative targets are met, creating the smoothest possible transition path while still achieving equity goals. The strict parameter controls whether an error is raised if exact targets cannot be achieved.

See Also

cumulative_per_capita_convergence_adjusted : With pre-allocation responsibility/capability adjustments cumulative_per_capita_convergence_adjusted_gini : With Gini-adjusted GDP

cumulative_per_capita_convergence_adjusted

fair_shares.library.allocations.pathways.cumulative_per_capita_convergence.cumulative_per_capita_convergence_adjusted

Python
cumulative_per_capita_convergence_adjusted(
    population_ts: TimeseriesDataFrame,
    country_actual_emissions_ts: TimeseriesDataFrame,
    first_allocation_year: int,
    emission_category: str,
    world_scenario_emissions_ts: TimeseriesDataFrame,
    responsibility_emissions_ts: (
        TimeseriesDataFrame | None
    ) = None,
    gdp_ts: TimeseriesDataFrame | None = None,
    pre_allocation_responsibility_weight: float = 0.0,
    capability_weight: float = 0.0,
    pre_allocation_responsibility_year: int = 1990,
    pre_allocation_responsibility_per_capita: bool = False,
    pre_allocation_responsibility_exponent: float = 1.0,
    pre_allocation_responsibility_functional_form: str = "asinh",
    capability_per_capita: bool = True,
    capability_exponent: float = 1.0,
    capability_functional_form: str = "asinh",
    max_deviation_sigma: float | None = None,
    max_convergence_speed: float = 0.9,
    strict: bool = True,
    historical_discount_rate: float = 0.0,
    convergence_method: str = "minimum-speed",
    convergence_year: int | None = None,
    group_level: str = "iso3c",
    unit_level: str = "unit",
    ur: PlainRegistry = get_default_unit_registry(),
) -> PathwayAllocationResult

Cumulative per capita convergence with pre-allocation responsibility and capability adjustments.

Extends cumulative per capita convergence by incorporating:

  • Pre-allocation responsibility adjustment: Countries with higher historical emissions receive smaller allocations
  • Capability adjustment: Countries with higher GDP receive smaller allocations
Mathematical Foundation

Convergence Dynamics

The allocation shares evolve through exponential convergence (same as base approach):

\[ A(g, t+1) = A(g, t) + \lambda \big(A^{\infty}(g) - A(g, t)\big) \]

Where:

  • \(A(g, t)\): Allocation share for country \(g\) at year \(t\)
  • \(A^{\infty}(g)\): Long-run target share
  • \(\lambda\): Convergence speed (automatically determined)

Initial shares at first_allocation_year are based on actual emissions.

Cumulative Target Shares with Adjustments

Target shares are computed by adjusting cumulative population for pre-allocation responsibility and economic capability:

\[ T_{\text{cum}}(g) = \frac{P_{\text{adj}}(g)}{\sum_{g'} P_{\text{adj}}(g')} \]

Where the adjusted population is:

\[ P_{\text{adj}}(g) = P_{\text{cum}}(g) \times R(g) \times C(g) \]

Where:

  • \(T_{\text{cum}}(g)\): Cumulative target share for country \(g\)
  • \(P_{\text{adj}}(g)\): Adjusted cumulative population
  • \(P_{\text{cum}}(g) = \sum_{t \geq t_a} P(g, t)\): Cumulative population from allocation year onwards
  • \(R(g)\): Pre-allocation responsibility adjustment factor (equals 1.0 if not used)
  • \(C(g)\): Capability adjustment factor (equals 1.0 if not used)

Pre-Allocation Responsibility Adjustment

The pre-allocation responsibility metric is based on cumulative emissions from pre_allocation_responsibility_year to first_allocation_year.

For per capita pre-allocation responsibility (:code:pre_allocation_responsibility_per_capita=True):

\[ R(g) = \left(\frac{\sum_{t=t_h}^{t_a} E(g, t)}{\sum_{t=t_h}^{t_a} P(g, t)}\right)^{-w_r \times e_r} \]

Where:

  • \(R(g)\): Pre-allocation responsibility adjustment factor (inverse - higher emissions = lower allocation)
  • \(E(g, t)\): Emissions of country \(g\) in year \(t\)
  • \(t_h\): Pre-allocation responsibility start year
  • \(t_a\): First allocation year
  • \(w_r\): Normalized pre-allocation responsibility weight
  • \(e_r\): Pre-allocation responsibility exponent

For absolute pre-allocation responsibility (:code:pre_allocation_responsibility_per_capita=False, default):

\[ R(g) = \left(\sum_{t=t_h}^{t_a} E(g, t)\right)^{-w_r \times e_r} \]

Capability Adjustment

The capability metric is based on cumulative GDP from first_allocation_year onwards.

For per capita capability (:code:capability_per_capita=True, default):

\[ C(g) = \left(\frac{\sum_{t \geq t_a} \text{GDP}(g, t)}{\sum_{t \geq t_a} P(g, t)}\right)^{-w_c \times e_c} \]

Where:

  • \(C(g)\): Capability adjustment factor (inverse - higher cumulative GDP per capita = lower allocation)
  • \(\text{GDP}(g, t)\): Gross domestic product of country \(g\) in year \(t\)
  • \(w_c\): Normalized capability weight
  • \(e_c\): Capability exponent

For absolute capability (:code:capability_per_capita=False):

\[ C(g) = \left(\sum_{t \geq t_a} \text{GDP}(g, t)\right)^{-w_c \times e_c} \]

Deviation Constraint

When :code:max_deviation_sigma is provided, adjusted cumulative target shares are constrained to prevent extreme deviations from equal cumulative per capita.

Parameters:

Name Type Description Default
population_ts TimeseriesDataFrame

Population time series for per capita calculations.

 required
country_actual_emissions_ts TimeseriesDataFrame

Country emissions for initial shares at first_allocation_year and for the pre-allocation responsibility calculation.

 required
world_scenario_emissions_ts TimeseriesDataFrame

Convergence. World emissions pathway defining time horizon and year weights for convergence dynamics.

 required
first_allocation_year int

Starting year for the allocation. Shares are computed from this year onwards.

 required
emission_category str

Emission category (e.g., 'co2-ffi', 'all-ghg').

 required
gdp_ts TimeseriesDataFrame | None

Capability. GDP time series used from first_allocation_year onwards. Required when capability_weight > 0.

 None
pre_allocation_responsibility_weight float

Pre-allocation responsibility. Relative weight (0–1). Only the ratio to capability_weight matters. When 0, pre-allocation responsibility is disabled.

 0.0
capability_weight float

Capability. Relative weight (0–1). Applies from first_allocation_year onwards (contrast with pre-allocation responsibility, which covers the window before it). When 0, capability is disabled.

 0.0
pre_allocation_responsibility_year int

Pre-allocation responsibility. Start year of the historical window [pre_allocation_responsibility_year, first_allocation_year). Default: 1990.

 1990
pre_allocation_responsibility_per_capita bool

Pre-allocation responsibility. If True, uses per-capita cumulative emissions. If False (default), uses absolute cumulative emissions.

 False
pre_allocation_responsibility_exponent float

Pre-allocation responsibility. Exponent applied to the emissions metric. Default: 1.0.

 1.0
pre_allocation_responsibility_functional_form str

Pre-allocation responsibility. Transformation: 'asinh' (default), 'power', or 'linear'.

 'asinh'
capability_per_capita bool

Capability. If True (default), GDP is divided by population. If False, absolute GDP is used.

 True
capability_exponent float

Capability. Exponent applied to the GDP metric. Default: 1.0.

 1.0
capability_functional_form str

Capability. Transformation: 'asinh' (default), 'power', or 'linear'.

 'asinh'
max_deviation_sigma float | None

Constraint. Maximum allowed deviation from equal per capita baseline, in population-weighted standard deviations. None (default) means no constraint.

 None
max_convergence_speed float

Convergence. Maximum allowed convergence speed (0–1.0). Lower values create smoother pathways but may become infeasible. Default: 0.9.

 0.9
strict bool

Convergence. If True (default), raise error for infeasible convergence. If False, use nearest feasible solution with warnings.

 True
historical_discount_rate float

Pre-allocation responsibility. Discount rate for historical emissions (0.0 to <1.0), via (1 - rate)^(reference_year - t) Default: 0.0. Only affects the pre-allocation responsibility calculation.

 0.0
convergence_method str

Convergence. Algorithm to use. 'minimum-speed' (default): exponential convergence with binary-search for minimum feasible speed. 'sine-deviation': iterative sine-shaped correction from a PCC baseline; requires convergence_year.

 'minimum-speed'
convergence_year int | None

Convergence. Year by which allocations converge to equal per capita. Required when convergence_method='sine-deviation'. Must be > first_allocation_year. Default: None.

 None
group_level str

Index level name for grouping. Default: 'iso3c'.

 'iso3c'
unit_level str

Index level name for units. Default: 'unit'.

 'unit'
ur PlainRegistry

Pint unit registry for unit conversions.

 get_default_unit_registry()

Returns:

Type Description
PathwayAllocationResult

Relative shares over time, summing to unity each year.
Notes

Theoretical grounding:

For convergence mechanism foundations, see: docs/science/allocations.md#convergence-mechanism-pathways-only

For how historical responsibility and capability enter allocations, see: docs/science/allocations.md#historical-responsibility

For implementation examples, see docs/science/principle-to-code.md.

This approach provides explicit pre-allocation responsibility rescaling and capability adjustments. These are one way to operationalize CBDR-RC; another is setting first_allocation_year in the past (responsibility via consumed budget) combined with capability adjustments. Higher past emissions and/or higher GDP -> smaller allocation.

GDP window: The capability metric for this approach is a per-country scalar computed by summing GDP and population only over the intersection of years where both data are available -- there is no forward-fill into post-observation years. With gdp_ts typically ending at the last observed year (e.g. 2023 for wdi-2025), only the observed-GDP years contribute to the capability metric, regardless of how far the population series extends. Users who want post-observation GDP dynamics to enter the capability calculation should extend the input gdp_ts time series with projected data (SSP2 GDP projections, custom growth assumptions, or a future-extended WDI release) before calling this function.

Convergence Speed

The convergence speed is automatically determined to be the minimum speed that ensures cumulative targets are met, creating the smoothest possible transition path while still achieving equity goals. The strict parameter controls whether an error is raised if exact targets cannot be achieved.

See Also

cumulative_per_capita_convergence : Without adjustments cumulative_per_capita_convergence_adjusted_gini : With Gini-adjusted GDP

cumulative_per_capita_convergence_adjusted_gini

fair_shares.library.allocations.pathways.cumulative_per_capita_convergence.cumulative_per_capita_convergence_adjusted_gini

Python
cumulative_per_capita_convergence_adjusted_gini(
    population_ts: TimeseriesDataFrame,
    country_actual_emissions_ts: TimeseriesDataFrame,
    first_allocation_year: int,
    emission_category: str,
    world_scenario_emissions_ts: TimeseriesDataFrame,
    responsibility_emissions_ts: (
        TimeseriesDataFrame | None
    ) = None,
    gdp_ts: TimeseriesDataFrame | None = None,
    gini_s: DataFrame | None = None,
    pre_allocation_responsibility_weight: float = 0.0,
    capability_weight: float = 0.0,
    pre_allocation_responsibility_year: int = 1990,
    pre_allocation_responsibility_per_capita: bool = False,
    pre_allocation_responsibility_exponent: float = 1.0,
    pre_allocation_responsibility_functional_form: str = "asinh",
    capability_per_capita: bool = True,
    capability_exponent: float = 1.0,
    capability_functional_form: str = "asinh",
    income_floor: float = 0.0,
    max_gini_adjustment: float = 0.8,
    max_deviation_sigma: float | None = None,
    max_convergence_speed: float = 0.9,
    strict: bool = True,
    historical_discount_rate: float = 0.0,
    convergence_method: str = "minimum-speed",
    convergence_year: int | None = None,
    group_level: str = "iso3c",
    unit_level: str = "unit",
    ur: PlainRegistry = get_default_unit_registry(),
) -> PathwayAllocationResult

Cumulative per capita convergence with Gini-adjusted GDP and full adjustments.

The most comprehensive variant, incorporating:

  • Pre-allocation responsibility adjustment: Countries with higher historical emissions receive smaller allocations
  • Capability adjustment: Countries with higher GDP receive smaller allocations
  • Gini adjustment: GDP is adjusted for income inequality within countries
Mathematical Foundation

Convergence Dynamics

The allocation shares evolve through exponential convergence (same as base approach):

\[ A(g, t+1) = A(g, t) + \lambda \big(A^{\infty}(g) - A(g, t)\big) \]

Where:

  • \(A(g, t)\): Allocation share for country \(g\) at year \(t\)
  • \(A^{\infty}(g)\): Long-run target share
  • \(\lambda\): Convergence speed (automatically determined)

Initial shares at first_allocation_year are based on actual emissions.

Cumulative Target Shares with Adjustments

Target shares are computed by adjusting cumulative population for pre-allocation responsibility and Gini-adjusted economic capability:

\[ T_{\text{cum}}(g) = \frac{P_{\text{adj}}(g)}{\sum_{g'} P_{\text{adj}}(g')} \]

Where the adjusted population is:

\[ P_{\text{adj}}(g) = P_{\text{cum}}(g) \times R(g) \times C_{\text{Gini}}(g) \]

Where:

  • \(T_{\text{cum}}(g)\): Cumulative target share for country \(g\)
  • \(P_{\text{adj}}(g)\): Adjusted cumulative population
  • \(P_{\text{cum}}(g) = \sum_{t \geq t_a} P(g, t)\): Cumulative population from allocation year onwards
  • \(R(g)\): Pre-allocation responsibility adjustment factor (equals 1.0 if not used)
  • \(C_{\text{Gini}}(g)\): Gini-adjusted capability factor (equals 1.0 if not used)

Gini Adjustment Process

GDP is adjusted using an interpretation of the Greenhouse Development Rights (GDR) framework's capability metric (note: GDR was designed for burden-sharing; fair-shares adapts its capability calculation for entitlement allocation). Only income above a development threshold counts as capability. When combined with the income floor, higher inequality means more national income sits above the threshold — increasing measured capability. See :func:~fair_shares.library.utils.math.allocation.calculate_gini_adjusted_gdp for the full mathematical derivation.

Pre-Allocation Responsibility Adjustment

Identical to adjusted convergence (see that function for details).

For per capita pre-allocation responsibility (:code:pre_allocation_responsibility_per_capita=True):

\[ R(g) = \left(\frac{\sum_{t=t_h}^{t_a} E(g, t)}{\sum_{t=t_h}^{t_a} P(g, t)}\right)^{-w_r \times e_r} \]

Where:

  • \(E(g, t)\): Emissions of country \(g\) in year \(t\)
  • \(t_h\): Pre-allocation responsibility start year
  • \(t_a\): First allocation year
  • \(w_r\): Normalized pre-allocation responsibility weight
  • \(e_r\): Pre-allocation responsibility exponent

Capability Adjustment with Gini-Adjusted GDP

The capability metric uses Gini-adjusted GDP to account for income inequality.

For per capita capability (:code:capability_per_capita=True, default):

\[ C_{\text{Gini}}(g) = \left(\frac{\sum_{t \geq t_a} \text{GDP}^{\text{adj}}(g, t)}{\sum_{t \geq t_a} P(g, t)}\right)^{-w_c \times e_c} \]

Where:

  • \(C_{\text{Gini}}(g)\): Gini-adjusted capability factor (inverse - higher adjusted GDP = lower allocation)
  • \(\text{GDP}^{\text{adj}}(g, t)\): Gini-adjusted GDP in year \(t\)
  • \(w_c\): Normalized capability weight
  • \(e_c\): Capability exponent

For absolute capability (:code:capability_per_capita=False):

\[ C_{\text{Gini}}(g) = \left(\sum_{t \geq t_a} \text{GDP}^{\text{adj}}(g, t)\right)^{-w_c \times e_c} \]

Gini Adjustment Effect

When combined with the income floor, higher inequality means more national income sits above the development threshold, creating larger per-person excesses. Countries with high inequality and high GDP thus receive smaller emission allocations (higher measured capability = more ability to pay). See :func:~fair_shares.library.utils.math.allocation.calculate_gini_adjusted_gdp for worked examples.

Deviation Constraint

When :code:max_deviation_sigma is provided, adjusted cumulative target shares are constrained to prevent extreme deviations from equal cumulative per capita.

Parameters:

Name Type Description Default
population_ts TimeseriesDataFrame

Population time series for per capita calculations.

 required
country_actual_emissions_ts TimeseriesDataFrame

Country emissions for initial shares at first_allocation_year and for the pre-allocation responsibility calculation.

 required
world_scenario_emissions_ts TimeseriesDataFrame

Convergence. World emissions pathway defining time horizon and year weights for convergence dynamics.

 required
first_allocation_year int

Starting year for the allocation. Shares are computed from this year onwards.

 required
emission_category str

Emission category (e.g., 'co2-ffi', 'all-ghg').

 required
gdp_ts TimeseriesDataFrame | None

Capability. GDP time series used from first_allocation_year onwards. Required when capability_weight > 0 or gini_s is provided.

 None
gini_s DataFrame | None

Gini. Gini coefficients for within-country income inequality. Used to adjust GDP before computing the capability factor.

 None
pre_allocation_responsibility_weight float

Pre-allocation responsibility. Relative weight (0–1). Only the ratio to capability_weight matters. When 0, pre-allocation responsibility is disabled.

 0.0
capability_weight float

Capability. Relative weight (0–1). Applies from first_allocation_year onwards. When 0, capability is disabled.

 0.0
pre_allocation_responsibility_year int

Pre-allocation responsibility. Start year of the historical window [pre_allocation_responsibility_year, first_allocation_year). Default: 1990.

 1990
pre_allocation_responsibility_per_capita bool

Pre-allocation responsibility. If True, uses per-capita cumulative emissions. If False (default), uses absolute cumulative emissions.

 False
pre_allocation_responsibility_exponent float

Pre-allocation responsibility. Exponent applied to the emissions metric. Default: 1.0.

 1.0
pre_allocation_responsibility_functional_form str

Pre-allocation responsibility. Transformation: 'asinh' (default), 'power', or 'linear'.

 'asinh'
capability_per_capita bool

Capability. If True (default), Gini-adjusted GDP is divided by population. If False, absolute Gini-adjusted GDP is used.

 True
capability_exponent float

Capability. Exponent applied to the Gini-adjusted GDP metric. Default: 1.0.

 1.0
capability_functional_form str

Capability. Transformation: 'asinh' (default), 'power', or 'linear'.

 'asinh'
income_floor float

Gini. Development threshold in USD PPP per capita. Income below this is excluded from capability calculations. Default: 0.0 (all income counts); pass 7500.0 for the GDR threshold.

 0.0
max_gini_adjustment float

Gini. Maximum reduction factor from threshold deduction (0–1). Default: 0.8.

 0.8
max_deviation_sigma float | None

Constraint. Maximum allowed deviation from equal per capita baseline, in population-weighted standard deviations. None (default) means no constraint.

 None
max_convergence_speed float

Convergence. Maximum allowed convergence speed (0–1.0). Default: 0.9.

 0.9
strict bool

Convergence. If True (default), raise error for infeasible convergence. If False, use nearest feasible solution.

 True
historical_discount_rate float

Pre-allocation responsibility. Discount rate for historical emissions (0.0 to <1.0), via (1 - rate)^(reference_year - t) Default: 0.0. Only affects the pre-allocation responsibility calculation.

 0.0
convergence_method str

Convergence. Algorithm: 'minimum-speed' (default) or 'sine-deviation' (requires convergence_year).

 'minimum-speed'
convergence_year int | None

Convergence. Year by which allocations converge to equal per capita. Required when convergence_method='sine-deviation'. Default: None.

 None
group_level str

Index level name for grouping. Default: 'iso3c'.

 'iso3c'
unit_level str

Index level name for units. Default: 'unit'.

 'unit'
ur PlainRegistry

Pint unit registry for unit conversions.

 get_default_unit_registry()

Returns:

Type Description
PathwayAllocationResult

Relative shares over time, summing to unity each year.
Notes

Theoretical grounding:

For convergence mechanism foundations and Gini adjustment rationale, see: docs/science/allocations.md#convergence-mechanism-pathways-only docs/science/allocations.md#gini-adjustment

For implementation examples combining convergence with subsistence protection, see docs/science/principle-to-code.md.

This approach extends the adjusted convergence method by incorporating Gini-adjusted GDP to account for income inequality within countries. The income_floor parameter implements the subsistence vs. luxury emissions distinction. When combined with the income floor, higher inequality means more national income sits above the threshold — increasing measured capability.

GDP window: The capability metric for this approach is a per-country scalar computed by summing (Gini-adjusted) GDP and population only over the intersection of years where both data are available -- there is no forward-fill into post-observation years. With gdp_ts typically ending at the last observed year (e.g. 2023 for wdi-2025), only the observed-GDP years contribute to the capability metric. Users who want post-observation GDP dynamics to enter the capability calculation should extend the input gdp_ts time series with projected data (SSP2 GDP projections, custom growth assumptions, or a future-extended WDI release) before calling this function. Gini coefficients are looked up per-country and are not part of this windowing -- only the GDP series is constrained to the observation window.

Convergence Speed

The convergence speed is automatically determined to be the minimum speed that ensures cumulative targets are met, creating the smoothest possible transition path while still achieving equity goals. The strict parameter controls whether an error is raised if exact targets cannot be achieved.

See Also

cumulative_per_capita_convergence : Without adjustments cumulative_per_capita_convergence_adjusted : Without Gini adjustment

See Also