IFPRI API

IFPRI API#

The cge_core.models.ifpri package exposes the public interface for loading, calibrating, solving, validating and reporting the IFPRI Standard CGE benchmark and policy scenarios.

IFPRI Standard CGE model family.

The package root exposes the practitioner façade and the advanced implementation APIs used for replication, custom closures, validation, and research workflows.

class cge_core.models.ifpri.IFPRICGE(dataset, *, source_kind, solver=None)#

Bases: object

IFPRI Standard CGE adapter with an explicit synthetic/official boundary.

Parameters:

  • source_kind (str)

  • solver (Optional[str])

class cge_core.models.ifpri.IFPRIEquilibrium(_dataset: 'Any', _calibration: 'Any', _model: 'Any', _report: 'Any', _solver: 'Optional[str]' = None)#

Bases: object

Parameters:

  • _dataset (Any)

  • _calibration (Any)

  • _model (Any)

  • _report (Any)

  • _solver (str | None)

class cge_core.models.ifpri.IFPRIResult(name: 'str', _model: 'Any', _report: 'Any')#

Bases: object

Parameters:

  • name (str)

  • _model (Any)

  • _report (Any)

class cge_core.models.ifpri.IFPRIScenario(name: 'str', base: 'IFPRIEquilibrium', model: 'Any', solver: 'Optional[str]' = None)#

Bases: object

Parameters:
class cge_core.models.ifpri.IfpriBenchmarkCalibration(prices, quantities, production, taxes, institutions, les, system)#

Bases: object

Complete algebraic calibration of the supplied benchmark, without solve.

Parameters:
class cge_core.models.ifpri.IfpriBenchmarkPrices(exchange_rate, activity, activity_commodity, value_added, intermediate_aggregate, marketed_output, domestic_supply, domestic_demand, export, import_, composite, world_export, world_import, factor, factor_activity)#

Bases: object

Benchmark prices implied by the SAM normalization.

Parameters:

  • exchange_rate (float)

  • activity (Mapping[str, float])

  • activity_commodity (Mapping[Tuple[str, str], float])

  • value_added (Mapping[str, float])

  • intermediate_aggregate (Mapping[str, float])

  • marketed_output (Mapping[str, float])

  • domestic_supply (Mapping[str, float])

  • domestic_demand (Mapping[str, float])

  • export (Mapping[str, float])

  • import_ (Mapping[str, float])

  • composite (Mapping[str, float])

  • world_export (Mapping[str, float])

  • world_import (Mapping[str, float])

  • factor (Mapping[str, float])

  • factor_activity (Mapping[Tuple[str, str], float])

class cge_core.models.ifpri.IfpriBenchmarkQuantities(activity, value_added, activity_commodity, home_consumption, marketed_output, domestic_sales, exports, imports, composite_supply, factor_demand, factor_supply, intermediate, intermediate_aggregate, transaction_demand, household_market, government, investment, stock_change)#

Bases: object

Benchmark quantities reconstructed from values and normalized prices.

Parameters:

  • activity (Mapping[str, float])

  • value_added (Mapping[str, float])

  • activity_commodity (Mapping[Tuple[str, str], float])

  • home_consumption (Mapping[Tuple[str, str, str], float])

  • marketed_output (Mapping[str, float])

  • domestic_sales (Mapping[str, float])

  • exports (Mapping[str, float])

  • imports (Mapping[str, float])

  • composite_supply (Mapping[str, float])

  • factor_demand (Mapping[Tuple[str, str], float])

  • factor_supply (Mapping[str, float])

  • intermediate (Mapping[Tuple[str, str], float])

  • intermediate_aggregate (Mapping[str, float])

  • transaction_demand (Mapping[str, float])

  • household_market (Mapping[Tuple[str, str], float])

  • government (Mapping[str, float])

  • investment (Mapping[str, float])

  • stock_change (Mapping[str, float])

class cge_core.models.ifpri.IfpriCalibrationInputs(elasticities, factor_quantities, home_consumption, taxes)#

Bases: object

All non-SAM inputs needed by the benchmark calibration stage.

Parameters:
exception cge_core.models.ifpri.IfpriDataError#

Bases: ValueError

Raised when an IFPRI source file is missing or structurally invalid.

class cge_core.models.ifpri.IfpriDataset(source_path, sets, sam, inputs)#

Bases: object

Parsed IFPRI benchmark data and calibration inputs.

Parameters:
class cge_core.models.ifpri.IfpriElasticities(armington, transformation, factor_substitution, top_level_substitution, output_aggregation, market_expenditure, home_expenditure, frisch)#

Bases: object

Trade, production, and household-demand elasticities.

Parameters:

  • armington (Mapping[str, float])

  • transformation (Mapping[str, float])

  • factor_substitution (Mapping[str, float])

  • top_level_substitution (Mapping[str, float])

  • output_aggregation (Mapping[str, float])

  • market_expenditure (Mapping[Tuple[str, str], float])

  • home_expenditure (Mapping[Tuple[str, str, str], float])

  • frisch (Mapping[str, float])

class cge_core.models.ifpri.IfpriFactorQuantities(supply, demand)#

Bases: object

Optional physical factor supply and activity-demand quantities.

Parameters:

  • supply (Mapping[str, float])

  • demand (Mapping[Tuple[str, str], float])

class cge_core.models.ifpri.IfpriHomeConsumption(value_shares)#

Bases: object

Commodity value shares for household home consumption.

Parameters:

value_shares (Mapping[Tuple[str, str, str], float])

class cge_core.models.ifpri.IfpriInstitutionCalibration(institution_income, factor_income, institution_factor_income, factor_income_share, interinstitution_share, savings_rate, household_expenditure, government_income, government_expenditure, government_saving)#

Bases: object

Institutional benchmark incomes, shares, transfers, and savings.

Parameters:

  • institution_income (Mapping[str, float])

  • factor_income (Mapping[str, float])

  • institution_factor_income (Mapping[Tuple[str, str], float])

  • factor_income_share (Mapping[Tuple[str, str], float])

  • interinstitution_share (Mapping[Tuple[str, str], float])

  • savings_rate (Mapping[str, float])

  • household_expenditure (Mapping[str, float])

  • government_income (float)

  • government_expenditure (float)

  • government_saving (float)

class cge_core.models.ifpri.IfpriLesCalibration(market_budget_share, home_budget_share, normalized_market_elasticity, normalized_home_elasticity, market_marginal_share, home_marginal_share, market_subsistence, home_subsistence, supernumerary_income, implied_frisch)#

Bases: object

Linear-expenditure-system benchmark parameters and checks.

Parameters:

  • market_budget_share (Mapping[Tuple[str, str], float])

  • home_budget_share (Mapping[Tuple[str, str, str], float])

  • normalized_market_elasticity (Mapping[Tuple[str, str], float])

  • normalized_home_elasticity (Mapping[Tuple[str, str, str], float])

  • market_marginal_share (Mapping[Tuple[str, str], float])

  • home_marginal_share (Mapping[Tuple[str, str, str], float])

  • market_subsistence (Mapping[Tuple[str, str], float])

  • home_subsistence (Mapping[Tuple[str, str, str], float])

  • supernumerary_income (Mapping[str, float])

  • implied_frisch (Mapping[str, float])

class cge_core.models.ifpri.IfpriProductionCalibration(value_added_coefficient, intermediate_coefficient, intermediate_shares, yield_coefficient, factor_exponent, factor_shares, factor_scale, output_exponent, output_shares, output_scale, armington_exponent, armington_share, armington_scale, cet_exponent, cet_share, cet_scale, transaction_domestic, transaction_import, transaction_export)#

Bases: object

Calibrated production, output-aggregation, and trade parameters.

Parameters:

  • value_added_coefficient (Mapping[str, float])

  • intermediate_coefficient (Mapping[str, float])

  • intermediate_shares (Mapping[Tuple[str, str], float])

  • yield_coefficient (Mapping[Tuple[str, str], float])

  • factor_exponent (Mapping[str, float])

  • factor_shares (Mapping[Tuple[str, str], float])

  • factor_scale (Mapping[str, float])

  • output_exponent (Mapping[str, float])

  • output_shares (Mapping[Tuple[str, str], float])

  • output_scale (Mapping[str, float])

  • armington_exponent (Mapping[str, float])

  • armington_share (Mapping[str, float])

  • armington_scale (Mapping[str, float])

  • cet_exponent (Mapping[str, float])

  • cet_share (Mapping[str, float])

  • cet_scale (Mapping[str, float])

  • transaction_domestic (Mapping[Tuple[str, str], float])

  • transaction_import (Mapping[Tuple[str, str], float])

  • transaction_export (Mapping[Tuple[str, str], float])

class cge_core.models.ifpri.IfpriReferenceComparison(compared_values: 'int', max_abs_difference: 'float', max_relative_difference: 'float', worst_absolute: 'str', worst_relative: 'str', differences: 'Mapping[str, float]')#

Bases: object

Parameters:

  • compared_values (int)

  • max_abs_difference (float)

  • max_relative_difference (float)

  • worst_absolute (str)

  • worst_relative (str)

  • differences (Mapping[str, float])

class cge_core.models.ifpri.IfpriResidualReport(equation_count, max_abs_residual, worst_equation, group_max_abs_residual)#

Bases: object

Summary of equation residuals at the current Pyomo variable values.

Parameters:

  • equation_count (int)

  • max_abs_residual (float)

  • worst_equation (str)

  • group_max_abs_residual (Mapping[str, float])

class cge_core.models.ifpri.IfpriSam(table_name, accounts, values, scale)#

Bases: object

Parsed and scaled social accounting matrix.

Parameters:

  • table_name (str)

  • accounts (Tuple[str, ...])

  • values (Mapping[Tuple[str, str], float])

  • scale (float)

column_total(column)#

Return the sum of column over active SAM accounts.

Parameters:

column (str)

Return type:

float

imbalance(account)#

Return row total minus column total for one account.

Parameters:

account (str)

Return type:

float

max_abs_imbalance()#

Return the largest absolute account imbalance.

Return type:

float

row_total(row)#

Return the sum of row over active SAM accounts.

Parameters:

row (str)

Return type:

float

value(row, column)#

Return a SAM cell, treating an omitted GAMS table cell as zero.

Parameters:

  • row (str)

  • column (str)

Return type:

float

class cge_core.models.ifpri.IfpriScenario(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: str, Enum

Named counterfactuals in the official IFPRI test simulation file.

class cge_core.models.ifpri.IfpriSets(accounts, activities, agricultural_activities, commodities, agricultural_commodities, domestic_transaction_accounts, export_transaction_accounts, import_transaction_accounts, factors, labor_factors, land_factors, capital_factors, institutions, domestic_institutions, domestic_nongovernment_institutions, enterprises, households)#

Bases: object

Account classifications declared in an IFPRI .dat file.

Parameters:

  • accounts (Tuple[str, ...])

  • activities (Tuple[str, ...])

  • agricultural_activities (Tuple[str, ...])

  • commodities (Tuple[str, ...])

  • agricultural_commodities (Tuple[str, ...])

  • domestic_transaction_accounts (Tuple[str, ...])

  • export_transaction_accounts (Tuple[str, ...])

  • import_transaction_accounts (Tuple[str, ...])

  • factors (Tuple[str, ...])

  • labor_factors (Tuple[str, ...])

  • land_factors (Tuple[str, ...])

  • capital_factors (Tuple[str, ...])

  • institutions (Tuple[str, ...])

  • domestic_institutions (Tuple[str, ...])

  • domestic_nongovernment_institutions (Tuple[str, ...])

  • enterprises (Tuple[str, ...])

  • households (Tuple[str, ...])

class cge_core.models.ifpri.IfpriSolveReport(solver: 'str', status: 'str', termination_condition: 'str', degrees_of_freedom: 'int', max_abs_equation_residual: 'float')#

Bases: object

Parameters:

  • solver (str)

  • status (str)

  • termination_condition (str)

  • degrees_of_freedom (int)

  • max_abs_equation_residual (float)

class cge_core.models.ifpri.IfpriSystemCalibration(consumer_price_weights, domestic_price_weights, consumer_price_index, domestic_price_index, foreign_saving, total_absorption, investment_share, government_share, walras_residual)#

Bases: object

Savings-investment and price-index benchmark aggregates.

Parameters:

  • consumer_price_weights (Mapping[str, float])

  • domestic_price_weights (Mapping[str, float])

  • consumer_price_index (float)

  • domestic_price_index (float)

  • foreign_saving (float)

  • total_absorption (float)

  • investment_share (float)

  • government_share (float)

  • walras_residual (float)

class cge_core.models.ifpri.IfpriTaxCalibration(activity, value_added, commodity, import_, export, factor, institution)#

Bases: object

Benchmark ad-valorem tax rates.

Parameters:

  • activity (Mapping[str, float])

  • value_added (Mapping[str, float])

  • commodity (Mapping[str, float])

  • import_ (Mapping[str, float])

  • export (Mapping[str, float])

  • factor (Mapping[str, float])

  • institution (Mapping[str, float])

class cge_core.models.ifpri.IfpriTaxData(source_accounts, payments)#

Bases: object

Tax-account mapping and benchmark tax payments extracted from the SAM.

Parameters:

  • source_accounts (Mapping[str, str])

  • payments (Mapping[Tuple[str, str], float])

payment(tax_type, account)#

Return a benchmark tax payment, with omitted cells treated as zero.

Parameters:

  • tax_type (str)

  • account (str)

Return type:

float

cge_core.models.ifpri.apply_ifpri_base_closure(model)#

Apply the active BASE closure recorded for the official test model.

Return type:

None

cge_core.models.ifpri.apply_ifpri_scenario_closure(model, scenario)#

Apply one official policy shock and closure to a benchmark model.

The model must have been created by build_ifpri_scenario_model() so that tariff and import-price shocks are already embedded in its immutable Pyomo parameters.

Parameters:

scenario (IfpriScenario | str)

Return type:

None

cge_core.models.ifpri.build_and_solve_ifpri_scenarios(dataset, scenarios=None, solver=None, perturbation=1.01)#

Build and solve multiple scenarios, returning models and solve reports.

Parameters:
cge_core.models.ifpri.build_ifpri_benchmark_model(dataset, calibration=None)#

Create the initialized Pyomo benchmark model without calling a solver.

Parameters:
Returns:

A pyomo.environ.ConcreteModel whose active equations reproduce the benchmark at their initialized values.

Raises:

IfpriDataError – if the benchmark is incompatible with this milestone.

Return type:

ConcreteModel

cge_core.models.ifpri.build_ifpri_scenario_model(dataset, scenario, calibration=None)#

Build one closed IFPRI policy simulation, initialized at the benchmark.

Parameters:
cge_core.models.ifpri.build_synthetic_ifpri_dataset()#

Return a compact balanced economy with trade, saving, and a tariff.

Return type:

IfpriDataset

cge_core.models.ifpri.calibrate_ifpri_benchmark(dataset)#

Calibrate the supplied IFPRI benchmark entirely by algebra.

The normalization follows the documented test data convention: activity, producer, export, and activity-commodity supply prices start at one, as does the exchange rate. All other prices and quantities are then implied by the SAM and the parsed exogenous inputs.

Parameters:

dataset (IfpriDataset)

Return type:

IfpriBenchmarkCalibration

cge_core.models.ifpri.compare_ifpri_models(base_model, scenario_model, *, scenario=None, components=None, zero_tolerance=1e-12)#

Compare common variables as scenario minus BASE in a DataFrame.

Percentage changes are undefined (NaN) where the absolute BASE value is no larger than zero_tolerance. Variables that exist in only one model, such as a scenario-specific closure variable, remain available through extract_ifpri_solution() but are not included in this common-variable comparison.

Parameters:

  • scenario (object | None)

  • components (Iterable[str] | None)

  • zero_tolerance (float)

Return type:

DataFrame

cge_core.models.ifpri.compare_ifpri_scenarios(base_model, results, *, components=None, zero_tolerance=1e-12)#

Compare every result from build_and_solve_ifpri_scenarios to BASE.

Parameters:
Return type:

DataFrame

cge_core.models.ifpri.extract_ifpri_solution(model, *, label=None, components=None)#

Return one long-form row for every selected active IFPRI variable.

The returned columns are scenario, component, index_1 through index_3, value, and fixed. Scalar variables have blank index columns. All values must be initialized and finite so that an invalid solve missing or nonfinite model state cannot silently enter a report.

Parameters:

  • label (object | None)

  • components (Iterable[str] | None)

Return type:

DataFrame

cge_core.models.ifpri.ifpri_benchmark_residuals(model)#

Return one signed residual for every active benchmark equation.

Parameters:

model (ConcreteModel)

Return type:

Dict[str, float]

cge_core.models.ifpri.ifpri_degrees_of_freedom(model)#

Return closure degrees of freedom after accounting for the objective.

The official NLP has one optimization degree: WALRAS is free and WALRASSQR is minimized subject to WALRASSQR = WALRAS**2. Counting the active scalar objective as the final closure condition therefore yields zero closure degrees of freedom while leaving IPOPT a valid NLP with one more free variable than equality constraints.

Return type:

int

cge_core.models.ifpri.load_ifpri_test_data(source_dir=None)#

Load and validate the external IFPRI test.dat dataset.

Parameters:

source_dir (str | Path | None)

Return type:

IfpriDataset

cge_core.models.ifpri.normalize_ifpri_scenario(scenario)#

Return a validated IfpriScenario from a string or enum value.

Parameters:

scenario (IfpriScenario | str)

Return type:

IfpriScenario

cge_core.models.ifpri.parse_ifpri_test_dat(path)#

Parse the set definitions and benchmark SAM from test.dat.

Parameters:

path (str | Path)

Return type:

IfpriDataset

cge_core.models.ifpri.perturb_ifpri_start(model, factor=1.02)#

Move every free nonzero variable away from the benchmark start.

Parameters:

factor (float)

Return type:

None

cge_core.models.ifpri.resolve_ifpri_source(source_dir=None, filename='test.dat')#

Resolve the external IFPRI data file from an argument or environment.

Parameters:

  • source_dir (str | Path | None)

  • filename (str)

Return type:

Path

cge_core.models.ifpri.solve_ifpri_base(model, solver=None, tee=False)#

Solve a closed IFPRI model and require an optimal termination.

Parameters:

  • solver (str | None)

  • tee (bool)

Return type:

IfpriSolveReport

cge_core.models.ifpri.solve_ifpri_scenario(model, solver=None, tee=False)#

Solve a closed policy scenario with the same NLP formulation as BASE.

Parameters:

  • solver (str | None)

  • tee (bool)

Return type:

IfpriSolveReport

cge_core.models.ifpri.summarize_ifpri_benchmark_residuals(model)#

Summarize current benchmark equation residuals by equation group.

Parameters:

model (ConcreteModel)

Return type:

IfpriResidualReport

cge_core.models.ifpri.summarize_ifpri_results(results)#

Return one solver-diagnostic row for every policy scenario result.

Parameters:

results (Mapping[IfpriScenario | str, Tuple[object, IfpriSolveReport]])

Return type:

DataFrame

cge_core.models.ifpri.validate_dataset(dataset, balance_tolerance=1e-07)#

Run all structural, accounting, and calibration-input checks.

Parameters:
Return type:

None

cge_core.models.ifpri.validate_ifpri_benchmark_model(model, tolerance=1e-08)#

Raise when an initialized benchmark equation exceeds tolerance.

Parameters:

  • model (ConcreteModel)

  • tolerance (float)

Return type:

IfpriResidualReport

cge_core.models.ifpri.validate_ifpri_calibration(dataset, calibration, tolerance=1e-08)#

Check the calibrated benchmark identities without invoking a solver.

Parameters:
Return type:

None

cge_core.models.ifpri.validate_inputs(inputs, sets, sam, tolerance=1e-10)#

Validate calibration-input coverage, ranges, shares, and tax mappings.

Parameters:
Return type:

None

cge_core.models.ifpri.validate_sam(sam, declared_accounts, balance_tolerance=1e-07)#

Validate SAM dimensions, numeric cells, account membership and balance.

Parameters:

  • sam (IfpriSam)

  • declared_accounts (Iterable[str])

  • balance_tolerance (float)

Return type:

None

cge_core.models.ifpri.validate_sets(sets)#

Validate uniqueness and the key IFPRI set-subset relationships.

Parameters:

sets (IfpriSets)

Return type:

None

For the conceptual and validation guide, see IFPRI Standard CGE and IFPRI Validation.