gcubed.tuning

Reusable model-database tuning operations for G-Cubed model builds.

AdjustmentMethod = typing.Literal['floor', 'ceiling', 'exact', 'range']
@dataclass(frozen=True)
class BaselineTuningConfiguration:

The two independently executable baseline-tuning configurations.

BaselineTuningConfiguration( real_interest_rates_in_base_year: RealInterestRateTuningConfiguration | None, monetary_policy_adjustments: MonetaryPolicyAdjustmentConfiguration | None)
real_interest_rates_in_base_year: RealInterestRateTuningConfiguration | None
monetary_policy_adjustments: MonetaryPolicyAdjustmentConfiguration | None
@dataclass(frozen=True)
class CellChange:

One proposed or applied database-cell change.

CellChange( region: str, variable_name: str, year: int, category: str, original_value: float, selected_value: float)
region: str
variable_name: str
year: int
category: str
original_value: float
selected_value: float
class IntxConfigurationError(gcubed.tuning.IntxUpdateError):

Raised when monetary-policy tuning settings are invalid for a model.

@dataclass(frozen=True)
class IntxTuningSummary:

Observable result of one monetary-policy tuning invocation.

IntxTuningSummary( mode: str, decisions: tuple[StartingIntxDecision, ...] = (), diagnostics_file: pathlib.Path | None = None, planned_model_input_files: tuple[pathlib.Path, ...] = (), status: str = 'disabled')
mode: str
decisions: tuple[StartingIntxDecision, ...] = ()
diagnostics_file: pathlib.Path | None = None
planned_model_input_files: tuple[pathlib.Path, ...] = ()
status: str = 'disabled'
applied: bool

Whether the proposed model-input changes were committed.

class IntxUpdateError(builtins.RuntimeError):

Raised for a safe, user-correctable monetary-policy tuning failure.

@dataclass(frozen=True)
class MonetaryPolicyAdjustmentConfiguration:

Validated durable configuration for INTX transition tuning.

MonetaryPolicyAdjustmentConfiguration( projections_file_name: str, defaults: MonetaryPolicyAdjustmentSettings | None, region_overrides: dict[str, MonetaryPolicyAdjustmentSettings])
projections_file_name: str
region_overrides: dict[str, MonetaryPolicyAdjustmentSettings]
@dataclass(frozen=True)
class MonetaryPolicyAdjustmentSettings:

One complete default or regional INTX transition.

MonetaryPolicyAdjustmentSettings( start_year: int, end_year: int, annual_decay_percent: float, starting_intx_value: float | None = None)
start_year: int
end_year: int
annual_decay_percent: float
starting_intx_value: float | None = None
class PriceConditioningConfigurationError(gcubed.tuning.PriceConditioningError):

Raised when tuning settings do not match the model's regions.

class PriceConditioningError(builtins.RuntimeError):

Raised for a safe, user-correctable real-interest-rate tuning failure.

@dataclass(frozen=True)
class RealInterestRateTuningSummary:

Observable result of one disabled, summary, or apply invocation.

RealInterestRateTuningSummary( mode: str, decisions: tuple[RegionDecision, ...] = (), changes: tuple[CellChange, ...] = (), diagnostics_files: tuple[pathlib.Path, ...] = (), status: str = 'disabled')
mode: str
decisions: tuple[RegionDecision, ...] = ()
changes: tuple[CellChange, ...] = ()
diagnostics_files: tuple[pathlib.Path, ...] = ()
status: str = 'disabled'
applied: bool

Whether the proposed model-input changes were committed.

@dataclass(frozen=True)
class RealInterestRateConstraint:

One complete method-specific constraint on an implied INTR value.

RealInterestRateConstraint( adjustment_method: Literal['floor', 'ceiling', 'exact', 'range'], exact_real_interest_rate: float | None = None, floor_real_interest_rate: float | None = None, ceiling_real_interest_rate: float | None = None)
adjustment_method: Literal['floor', 'ceiling', 'exact', 'range']
exact_real_interest_rate: float | None = None
floor_real_interest_rate: float | None = None
ceiling_real_interest_rate: float | None = None
@dataclass(frozen=True)
class RealInterestRatePropagation:

Downstream price and wage groups controlled by INTR tuning.

RealInterestRatePropagation(other_domestic_nominal_price_indices: bool, wages: bool)
other_domestic_nominal_price_indices: bool
wages: bool
@dataclass(frozen=True)
class RealInterestRateTuningConfiguration:

Validated durable configuration for INTR-driven database tuning.

RealInterestRateTuningConfiguration( propagation: RealInterestRatePropagation, defaults: RealInterestRateConstraint | None, region_overrides: dict[str, RealInterestRateConstraint])
defaults: RealInterestRateConstraint | None
region_overrides: dict[str, RealInterestRateConstraint]
@dataclass(frozen=True)
class RegionDecision:

The calculated first-transition treatment for one enabled region.

RegionDecision( region: str, base_year: int, lead_year: int, adjustment_method: str, configured_floor_real_interest_rate: float | None, configured_ceiling_real_interest_rate: float | None, configured_exact_real_interest_rate: float | None, nominal_interest_rate_percentage_points: float, risk_premium_percentage_points: float, original_prid_inflation_percentage_points: float, original_implied_intr_percentage_points: float, selected_intr_percentage_points: float, selected_inflation_percentage_points: float, selected_prid_index: float, adjustment_required: bool, status: str)
region: str
base_year: int
lead_year: int
adjustment_method: str
configured_floor_real_interest_rate: float | None
configured_ceiling_real_interest_rate: float | None
configured_exact_real_interest_rate: float | None
nominal_interest_rate_percentage_points: float
risk_premium_percentage_points: float
original_prid_inflation_percentage_points: float
original_implied_intr_percentage_points: float
selected_intr_percentage_points: float
selected_inflation_percentage_points: float
selected_prid_index: float
adjustment_required: bool
status: str
@dataclass(frozen=True)
class StartingIntxDecision:

Calculated residual, selected judgement, and transition settings.

StartingIntxDecision( region: str, year: int, observed_intn_percentage_points: float, observed_intl_percentage_points: float, exchange_rate_gap_percentage_points: float, inflation_target_percentage_points: float, inflation_gap_percentage_points: float, output_growth_gap_percentage_points: float, no_shock_rule_value_percentage_points: float, calculated_intx_percentage_points: float, configured_starting_intx_percentage_points: float | None, selected_intx_percentage_points: float, selection_source: str, judgement_adjustment_percentage_points: float, reconstructed_intn_percentage_points: float, reconstructed_minus_observed_intn_percentage_points: float, start_year: int, end_year: int, annual_decay_percent: float)
region: str
year: int
observed_intn_percentage_points: float
observed_intl_percentage_points: float
exchange_rate_gap_percentage_points: float
inflation_target_percentage_points: float
inflation_gap_percentage_points: float
output_growth_gap_percentage_points: float
no_shock_rule_value_percentage_points: float
calculated_intx_percentage_points: float
configured_starting_intx_percentage_points: float | None
selected_intx_percentage_points: float
selection_source: str
judgement_adjustment_percentage_points: float
reconstructed_intn_percentage_points: float
reconstructed_minus_observed_intn_percentage_points: float
start_year: int
end_year: int
annual_decay_percent: float
@dataclass(frozen=True)
class StartingRuleResidual:

Observed inputs and calculated base-year monetary-rule residual.

StartingRuleResidual( region: str, year: int, observed_intn_percentage_points: float, observed_intl_percentage_points: float, exchange_rate_gap_percentage_points: float, inflation_target_percentage_points: float, inflation_gap_percentage_points: float, output_growth_gap_percentage_points: float, no_shock_rule_value_percentage_points: float, calculated_intx_percentage_points: float)
region: str
year: int
observed_intn_percentage_points: float
observed_intl_percentage_points: float
exchange_rate_gap_percentage_points: float
inflation_target_percentage_points: float
inflation_gap_percentage_points: float
output_growth_gap_percentage_points: float
no_shock_rule_value_percentage_points: float
calculated_intx_percentage_points: float
intx_residual_percentage_points: float

Return the calculated residual under its legacy descriptive name.

class TuningMode(builtins.str, enum.Enum):

Execution modes shared by the independent tuning mechanisms.

DISABLED = <TuningMode.DISABLED: 'disabled'>
SUMMARY = <TuningMode.SUMMARY: 'summary'>
APPLY = <TuningMode.APPLY: 'apply'>
@classmethod
def parse(cls, value: TuningMode | str) -> TuningMode:

Return a validated mode with a concise user-facing error.

def cleanup_monetary_policy_adjustments( model_configuration: gcubed.model_configuration.ModelConfiguration) -> None:

Remove managed INTX model inputs and zero database INTX values.

def cleanup_real_interest_rate_tuning( model_configuration: gcubed.model_configuration.ModelConfiguration) -> int:

Restore the database cells saved by the latest applied INTR tuning.

def tune_monetary_policy_adjustments( model_configuration: gcubed.model_configuration.ModelConfiguration, mode: TuningMode | str = 'disabled') -> IntxTuningSummary:

Summarize or apply configured monetary-policy tuning.

def tune_real_interest_rates( model_configuration: gcubed.model_configuration.ModelConfiguration, mode: TuningMode | str = 'disabled') -> RealInterestRateTuningSummary:

Summarize or apply configured INTR-driven database tuning.