Parameter Effects Reference¶
This guide shows how key parameters affect allocation outcomes using real data for representative countries:
- USA: High historical emissions, high GDP per capita
- India: Large population, lower historical emissions per capita
- Germany: Medium population, high historical emissions and GDP per capita
All examples use real data from PRIMAP (emissions), UN/OWID (population), World Bank (GDP), and UNU-WIDER (Gini).
Reproducing examples: Examples are generated by notebooks/docs/parameter_effects_examples.py. Run uv run python notebooks/docs/parameter_effects_examples.py to regenerate with updated data.
allocation_year (Budget) / first_allocation_year (Pathway)¶
Effect: Earlier allocation years account for more historical emissions in the cumulative budget calculation, dramatically reducing the remaining allocation for high historical emitters.
Direction:
- Earlier years → More cumulative emissions accounted for → High emitters may go negative
- Later years → Less history considered → Allocations closer to current population shares
Example: equal-per-capita-budget with varying allocation_year, showing remaining budget from 2020
| Country | allocation_year=2020 | allocation_year=1990 | allocation_year=1900 |
|---|---|---|---|
| USA | +12.3 GtCO2 | -119.9 GtCO2 | -329.2 GtCO2 |
| India | +51.2 GtCO2 | +155.3 GtCO2 | +271.2 GtCO2 |
| Germany | +2.4 GtCO2 | -15.9 GtCO2 | -66.2 GtCO2 |
Example uses 1.5°C carbon budget (50% probability). Remaining budget = (cumulative population share × global budget from allocation_year) minus actual emissions from allocation_year to 2020.
Key insight: The allocation_year is a highly consequential normative choice. With allocation_year=2020, no historical emissions are considered and all countries have positive remaining budgets. With allocation_year=1990, the USA and Germany have already exceeded their equal per capita share and show negative remaining budgets.
Mathematical detail: See equal_per_capita_budget API
Theoretical basis: See Allocation Approaches · Historical Responsibility
pre_allocation_responsibility_weight and capability_weight¶
Effect: These two weights jointly control CBDR-RC adjustments. They are relative — only their ratio matters, not their individual values. (0.5, 0.5) is identical to (1.0, 1.0) or (0.3, 0.3). When one weight is 0, the other becomes the sole adjustment regardless of its value — (0.0, 0.3) is identical to (0.0, 1.0). When both are 0, no adjustment is applied (pure equal per capita). See Weight Normalization.
pre_allocation_responsibility_weight activates per-capita rescaling based on cumulative per-capita emissions in [pre_allocation_responsibility_year, allocation_year). This is a separate mechanism from setting an early allocation_year — rescaling is multiplicative and always produces positive allocations if allocation_year is the present, whereas cumulative accounting can produce negative allocations (see comparison table below).
capability_weight activates capability (ability to pay) adjustments based on GDP per capita from the allocation year onwards. Capability data before the allocation year is not used.
Direction:
- Both weights
0.0→ No adjustment (equal per capita) - One weight
> 0, other= 0→ That adjustment is the sole factor (the specific non-zero value is irrelevant) - Both non-zero → Balanced by their ratio (e.g., 0.7:0.3 = 70% pre-allocation responsibility, 30% capability)
Each adjustment in isolation¶
Pre-allocation responsibility only (per-capita-adjusted-budget, capability_weight=0.0):
| Country | No adjustment (both=0) | Pre-allocation responsibility only |
|---|---|---|
| USA | 4.0% | 0.5% |
| India | 16.7% | 8.2% |
| Germany | 0.8% | 0.1% |
Uses allocation_year=2020, pre_allocation_responsibility_year=1990.
Pre-allocation responsibility rescaling substantially reduces shares for high-emitting developed countries (USA: 4.0% → 0.5%, Germany: 0.8% → 0.1%). India's share also decreases (16.7% → 8.2%) because the adjustment redistributes toward countries with the lowest per capita historical emissions, which are not shown in this three-country excerpt.
Capability only (per-capita-adjusted-budget, pre_allocation_responsibility_weight=0.0):
| Country | No adjustment (both=0) | Capability only |
|---|---|---|
| USA | 4.0% | 3.4% |
| India | 16.7% | 16.9% |
| Germany | 0.8% | 0.7% |
Uses allocation_year=2020.
Capability adjustments have a smaller magnitude effect. Wealthy countries see modest reductions (USA: 4.0% → 3.4%) while lower-GDP countries see small increases (India: 16.7% → 16.9%).
Varying the ratio (both weights non-zero)¶
The ratio only matters when both weights are non-zero. Here the specific values matter because they determine how much each adjustment contributes:
| Country | 100% pre-alloc resp. (1.0:0.0) | 70:30 | 50:50 | 30:70 | 100% capability (0.0:1.0) |
|---|---|---|---|---|---|
| USA | 0.5% | ← | ← | → | 3.4% |
| India | 8.2% | → | → | → | 16.9% |
| Germany | 0.1% | ← | ← | → | 0.7% |
Arrows indicate direction of interpolation between the two extremes. The exact intermediate values depend on data; the key point is that the ratio smoothly blends between pure pre-allocation responsibility and pure capability.
Mathematical detail: See per_capita_adjusted_budget API
Theoretical basis: See Historical Responsibility · Weight Normalization
income_floor¶
Effect: Sets a development threshold for capability calculations, adapted from the Greenhouse Development Rights framework (Baer et al. 2009). Note that GDR was designed for burden-sharing; fair-shares uses its capability metric in an entitlement allocation context. For every person, only their income above this threshold counts towards "capability" or "ability to pay". Income up to the threshold is considered necessary for basic human development.
Direction:
floor=0→ All income counts toward capability (no development protection)floor=7500→ $7,500/year (2010 PPP) — GDR framework default, the level at which basic development indicators (nutrition, infant mortality, education) are broadly metfloor=15000→ $15,000/year (2010 PPP) subsistence threshold
Higher floors increase the exempt portion, reducing measured capability for all countries and increasing their allocated share of emissions. The effect is largest for middle-income countries where a significant fraction of the population clusters around the threshold.
Example: per-capita-adjusted-gini-budget varying income_floor (with capability_weight=0.5)
| Country | floor=0 | floor=7500 | floor=15000 |
|---|---|---|---|
| USA | 3.4% | 3.2% | 3.1% |
| India | 16.9% | 16.5% | 16.6% |
| Germany | 0.7% | 0.6% | 0.6% |
Example uses allocation_year=2020, Gini-adjusted capability calculation.
Key insight: Income floor effects are modest but principled. Higher floors slightly reduce measured capability for wealthy countries (USA: 3.4% → 3.2%) by excluding subsistence income from "ability to pay." The effect is nonlinear and depends on income distribution (captured by Gini coefficients).
Mathematical detail: See per_capita_adjusted_gini_budget API
Theoretical basis: See Gini Adjustment
historical_discount_rate¶
Effect: Weights earlier historical emissions less than recent ones when computing pre-allocation responsibility adjustments. Available on per-capita-adjusted functions only — not part of equal-per-capita accounting.
Direction:
rate=0.0(default) → All historical emissions weighted equally (standard approach)rate=0.005→ 1850 emissions at ~43% weight relative to 2020rate=0.01→ Stronger discounting; 1850 emissions at ~18% weight
Higher rates reduce the influence of early-industrialisation emissions. Countries that industrialised early (UK, Germany, USA) benefit most from discounting. Countries whose emissions grew recently (China, India) see relatively smaller changes because their emission mass is concentrated in recent decades where discount weights are near 1.0.
Key insight: This parameter is contested in the literature. The physical argument: natural carbon sinks remove CO2 over time, so older emissions contribute less to current concentrations [Dekker 2025; Van Den Berg 2020]. The moral counterargument: responsibility for harm does not decay with time, and discounting systematically benefits the countries most responsible for cumulative warming [Meyer 2013; Shue 2015; Caney 2009]. The choice of any rate above 0.0 is a normative decision, not a technical one.
Mathematical detail: See Historical Emissions Discounting
Theoretical basis: See Allocation Approaches · Historical Responsibility
historical_start_year (Convergence Only)¶
Effect: Extends the cumulative population window backward when computing convergence target shares. Countries with large historical populations receive larger cumulative entitlements; countries whose populations grew recently receive relatively less. This is a population entitlement parameter — it does not affect responsibility adjustments or historical emissions accounting.
Direction:
- Default (None) → Cumulative population starts at
first_allocation_year - Earlier
historical_start_year→ More weight to historically populous countries (China, India) historical_start_year=first_allocation_year→ No-op (identical to default)
Example: cumulative-per-capita-convergence with first_allocation_year=2020, varying historical_start_year
| Country | Default (no hist) | hist=1990 | hist=1950 | hist=1850 |
|---|---|---|---|---|
| USA | ↔ baseline | ↓ slight | ↓ moderate | ↓ large |
| India | ↔ baseline | ↑ slight | ↑ moderate | ↑ large |
| Germany | ↔ baseline | ↓ slight | ↓ moderate | ↓ large |
Directional effects shown. India and China gain cumulative entitlement because they held a larger share of global population in 1850–1950 than they do from 2020 onward. USA and Germany lose entitlement because their population share was smaller historically.
Key insight: This parameter addresses a specific question: over what period should cumulative population count toward per-capita atmospheric entitlements? The default (forward-looking only) implicitly treats past use of the atmospheric commons as irrelevant to future entitlement. Setting historical_start_year to 1850 takes the position that entitlements should reflect the entire period of industrialisation. The choice is normative — there is no technically neutral default.
Mathematical detail: See Historical Start Year
Theoretical basis: See [Dekker 2025; Van Den Berg 2020] in References
strict (Convergence Only)¶
Effect: Controls whether infeasible convergence targets raise an error or produce approximate results with warnings. Infeasibility occurs when a country's current emissions are so far from its target share that no valid convergence path exists within the allowed speed range — the solver would need negative or >100% long-run shares, which are physically meaningless.
Direction:
strict=True(default) → Error on infeasibility. Use during research to catch impossible configurations early.strict=False→ Clips infeasible long-run shares to [0, 1], redistributes proportionally, reports per-country deviation ratios. Use during exploration to get results even when some targets are unreachable.
When infeasibility happens:
Aggressive equity configurations are the usual trigger. The more you push high-emitting countries toward small targets — via strong responsibility weighting, early allocation years, tight budgets, or combinations — the more likely the solver hits a mathematical wall. Short time horizons (few years between first_allocation_year and end of pathway) and low max_convergence_speed values also increase the chance.
Example: cumulative-per-capita-convergence-adjusted with strong responsibility weighting
| Configuration | USA | India | Germany |
|---|---|---|---|
strict=True, moderate weights |
✓ feasible | ✓ feasible | ✓ feasible |
strict=True, aggressive weights + early start |
✗ raises error | — | — |
strict=False, same aggressive config |
0.72 (achieved 72% of target) |
✓ feasible | 0.85 (achieved 85%) |
Warning values show achieved/target cumulative share ratio. Feasible countries are unaffected by the fallback.
Key insight: strict=False is a diagnostic tool, not a way to paper over bad configurations. If many countries show low ratios (<0.8), the configuration is asking for something the convergence mechanism can't deliver — consider relaxing weights, using a later allocation year, or extending the time horizon. If only 1-2 countries are slightly infeasible (ratios >0.95), the approximate result may be acceptable for exploratory analysis.
Mathematical detail: See Strict Parameter
max_deviation_sigma¶
Effect: Limits how far any country's adjusted allocation can deviate from equal per capita, measured in standard deviations. Only relevant when applying scaling adjustments (pre-allocation responsibility, capability, or combinations). Without this constraint, extreme adjustment values can produce outlier allocations.
Direction:
None→ No constraint (adjustments applied without limit)2.0(default) → Allocations clipped to within ±2 standard deviations of equal per capita- Lower values → Tighter constraint, allocations closer to equal per capita
Key insight: This is a safety rail, not a tuning parameter. The default of 2.0 prevents extreme outliers while preserving meaningful differentiation. Set to None only when you want the raw adjustment values without any clipping — useful for sensitivity analysis but risky for production results. If you find yourself lowering this significantly, the adjustments themselves may be too aggressive.
Mathematical detail: See Maximum Deviation Constraint
preserve_allocation_year_shares / preserve_first_allocation_year_shares¶
Effect: Controls whether population (and adjustment) shares are recalculated dynamically over time or frozen at the allocation year. Budget approaches use preserve_allocation_year_shares; pathway approaches use preserve_first_allocation_year_shares.
Direction:
False(default) → Dynamic: shares update with changing population and GDP over timeTrue→ Preserved: shares fixed at allocation year values, constant across all periods
Key insight: The default (dynamic) accounts for demographic change — countries with growing populations receive increasing shares over time. Preserved mode treats the allocation year as a snapshot: useful when you want to isolate the effect of equity parameters from demographic projections, or when population projections are uncertain. For budget approaches, dynamic mode uses cumulative population from the allocation year; preserved mode uses the single-year population at the allocation year.
Mathematical detail: See Dynamic vs Preserved Shares
convergence_method (Convergence Only)¶
Effect: Selects the solver for computing convergence pathways. Two methods produce different transition dynamics while respecting the same cumulative budget constraints.
Direction:
"minimum-speed"(default) → Finds the minimum exponential convergence speed that satisfies cumulative constraints. Produces the smoothest feasible transition."sine-deviation"→ Iterative sine-shaped deviation from a per-capita-convergence baseline [Dekker 2025]. Front-loads the adjustment toward cumulative budget targets. Requiresconvergence_year.
Key insight: minimum-speed is the workhorse — it requires no additional parameters and finds the least disruptive transition path. sine-deviation is more aggressive near-term: it front-loads adjustments using a sine-shaped correction, producing steeper initial changes but converging by convergence_year. Use sine-deviation when the policy question is specifically about accelerated near-term transitions.
Mathematical detail: See Convergence Method
max_convergence_speed (Convergence Only)¶
Effect: Upper bound on the exponential convergence speed parameter. Controls how fast allocations can transition from current emission shares to target shares in a single year.
Direction:
0.9(default) → Allows up to 90% of the remaining gap to close per year- Lower values → Forces slower, more gradual transitions but increases the risk of infeasibility
- Higher values (approaching 1.0) → Allows near-instantaneous convergence
Key insight: This parameter is rarely tuned directly. The default of 0.9 permits fast transitions when needed while keeping the convergence mathematically stable. Lowering it constrains the solver — if the cumulative target requires rapid transition and max_convergence_speed is too low, the solver cannot find a feasible path. When strict=True, this manifests as an error; when strict=False, as deviation ratios below 1.0.
Mathematical detail: See Convergence Mechanism
Understanding Weights vs Exponents¶
Two distinct parameter types control adjustments. They are often confused:
| Parameter | Default | Meaning of default | What it controls |
|---|---|---|---|
pre_allocation_responsibility_weight |
0.0 | Both at 0.0 → no adjustments | Relative importance of responsibility vs capability |
capability_weight |
0.0 | Both at 0.0 → no adjustments | Relative importance of capability vs responsibility |
pre_allocation_responsibility_exponent |
1.0 | Standard proportional effect | Shape of the responsibility function (1=linear, 2=squared) |
capability_exponent |
1.0 | Standard proportional effect | Shape of the capability function (1=linear, 2=squared) |
Key distinction: Weights are relative — only the ratio between pre_allocation_responsibility_weight and capability_weight matters. Setting either to any non-zero value (with the other at zero) gives that adjustment 100% of the weighting. Exponents control the functional shape of each adjustment independently.
Why exponents matter: At 1.0 (default), the adjustment is proportional — doubling per-capita emissions doubles the rescaling effect. At values above 1.0, the adjustment becomes convex: high emitters or wealthy countries are penalised disproportionately more, operationalising the argument that marginal emissions or income matter more at higher levels. The default of 1.0 is the most transparent choice; deviations require explicit normative justification. See Adjustment Shape Parameters for details on exponents, functional forms, and per-capita vs absolute modes.
"If you want X, set Y" guide¶
Two independent mechanisms for historical responsibility exist. They can be used separately or together:
| Mechanism | Parameter | How it works |
|---|---|---|
| Cumulative accounting | Early allocation_year (e.g. 1990, 1850) |
Requires considering cumulative emissions since that year when determining the remaining budget; negative allocations are a mathematical consequence |
| Relative rescaling | pre_allocation_responsibility_weight + pre_allocation_responsibility_year |
Multiplicative rescaling of per-capita shares over [pre_allocation_responsibility_year, allocation_year); always produces positive allocations if allocation_year is the present |
The rescaling mechanism requires pre_allocation_responsibility_year < allocation_year — when they are equal, the window is empty and the weight has no effect.
| Goal | Parameters |
|---|---|
| Pure equal per capita (no adjustments) | pre_allocation_responsibility_weight=0.0, capability_weight=0.0 |
| Historical responsibility via cumulative accounting | Early allocation_year (e.g. 1990), no weight needed |
| Historical responsibility via rescaling | pre_allocation_responsibility_weight=1.0, pre_allocation_responsibility_year < allocation_year |
| Both mechanisms combined | Early allocation_year + pre_allocation_responsibility_weight > 0 + pre_allocation_responsibility_year < allocation_year |
| Balanced CBDR-RC (rescaling + capability) | pre_allocation_responsibility_weight=0.5, capability_weight=0.5 |
| CBDR-RC with 0.7:0.3 responsibility-to-capability ratio | pre_allocation_responsibility_weight=0.7, capability_weight=0.3 |
| Ability to pay only | pre_allocation_responsibility_weight=0.0, capability_weight=1.0 |
| Stronger-than-linear rescaling | pre_allocation_responsibility_weight=0.5, pre_allocation_responsibility_exponent=2.0 |
| Historical population entitlements (convergence) | historical_start_year=1950 (or 1850) on cumulative-per-capita-convergence* |
Combining Parameters¶
Real allocation approaches combine multiple principles. Common patterns:
Pre-Allocation Responsibility Scaling + Capability¶
per_capita_adjusted_budget(
allocation_year=2020,
pre_allocation_responsibility_weight=0.5,
capability_weight=0.5,
pre_allocation_responsibility_year=1990, # window: [1990, 2020)
)
Rescales per-capita shares using 1990-2019 per-capita emissions (50%) and GDP from 2020 onwards (50%). No cumulative accounting of past emissions in the budget (allocation starts at 2020). Note the temporal asymmetry: pre-allocation responsibility looks backward from the allocation year, capability looks forward from it.
Both Responsibility Mechanisms (Cumulative Accounting + Rescaling)¶
per_capita_adjusted_budget(
allocation_year=1990,
pre_allocation_responsibility_weight=1.0,
capability_weight=0.0,
pre_allocation_responsibility_year=1850, # window: [1850, 1990)
)
Cumulative emissions from 1990 onward are accounted for when determining the remaining budget (via allocation_year=1990). Per-capita emissions from 1850-1989 rescale the remaining allocation (via pre_allocation_responsibility_weight=1.0).
Capability with Development Threshold¶
per_capita_adjusted_gini_budget(
pre_allocation_responsibility_weight=0.0,
capability_weight=1.0,
income_floor=7500, # ~$20/day
)
Adjusts for wealth while protecting subsistence needs.
Understanding Parameter Interactions¶
Parameter Sensitivity Ranking¶
Based on the examples:
allocation_year(largest absolute effect) - Cumulative accounting swings allocations by hundreds of GtCO2 and can flip them negative (USA: +12.3 to -329.2 GtCO2)pre_allocation_responsibility_weight(largest percentage-point effect on shares) - Can change allocations by 3-4 percentage points via multiplicative rescalingcapability_weight(typically 0.5-1 percentage point changes)income_floor(smallest effect) - Typically <0.5 percentage point changes
Multi-Parameter Trade-offs¶
When combining adjustments:
- High pre-allocation responsibility weight + high capability weight → Very low allocations for developed countries
- Capability-dominant weighting (e.g., 0.2:0.8) → Allocations shift primarily by GDP per capita
- Pre-allocation responsibility alone → "Polluter pays" framing
- Capability alone → "Common but differentiated" without historical accountability
See Also¶
- Principle to Code - How equity principles map to parameters
- Approach Catalog - Pre-configured combinations for common scenarios
- API Documentation - Mathematical definitions and validation rules