Equation blocks

Generic CGE building blocks composed by the templates.

Block base classes for equilibria CGE modeling.

Blocks are self-contained equation modules that define economic behavior. Each block declares its required sets, parameters, variables, and equations using Pydantic for validation and introspection.

class equilibria.blocks.base.ParameterSpec(*, name, domains=<factory>, default=None, description='')[source]

Bases: BaseModel

Specification for a block parameter.

Defines a parameter that the block requires, including its name, domains, and default value.

Variables:

  • name (str) – Parameter identifier

  • domains (tuple[str, ...]) – Tuple of set names defining dimensions

  • default (float | None) – Default value (optional)

  • description (str) – Human-readable description

Parameters:
name: str
domains: tuple[str, ...]
default: float | None
description: str
model_config = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class equilibria.blocks.base.VariableSpec(*, name, domains=<factory>, lower=0.0, upper=inf, description='')[source]

Bases: BaseModel

Specification for a block variable.

Defines a variable that the block declares, including its name, domains, and bounds.

Variables:

  • name (str) – Variable identifier

  • domains (tuple[str, ...]) – Tuple of set names defining dimensions

  • lower (float) – Lower bound (default: 0)

  • upper (float) – Upper bound (default: inf)

  • description (str) – Human-readable description

Parameters:
name: str
domains: tuple[str, ...]
lower: float
upper: float
description: str
model_config = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class equilibria.blocks.base.EquationSpec(*, name, domains=<factory>, description='')[source]

Bases: BaseModel

Specification for a block equation.

Defines an equation that the block contributes to the model.

Variables:

  • name (str) – Equation identifier

  • domains (tuple[str, ...]) – Tuple of set names defining equation indices

  • description (str) – Human-readable description

Parameters:
name: str
domains: tuple[str, ...]
description: str
model_config = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class equilibria.blocks.base.Block(*, dummy_defaults={}, name, description='', required_sets=<factory>, parameters=<factory>, variables=<factory>, equations=<factory>)[source]

Bases: BaseModel, CalibrationMixin, ABC

Base class for CGE model blocks.

Blocks are modular components that define economic behavior through equations. Each block declares its required sets, parameters, variables, and equations using Pydantic fields for validation.

Blocks also support calibration from SAM data via the CalibrationMixin.

Variables:
Parameters:

Example

>>> class CESValueAdded(Block):
...     name: str = "CES_VA"
...     description: str = "CES value-added production"
...     required_sets: list[str] = ["J", "I"]
...     sigma: float = Field(default=0.8, description="Elasticity")
...
...     def get_calibration_phases(self):
...         return [CalibrationPhase.PRODUCTION]
...
...     def _extract_calibration(self, phase, data, mode, set_manager):
...         # Extract from SAM
...         FD0 = data.get_matrix("F", "J")
...         VA0 = FD0.sum(axis=0)
...         beta_VA = self._compute_shares(FD0, axis=0)
...         return {"FD0": FD0, "VA0": VA0, "beta_VA": beta_VA}
name: str
description: str
required_sets: list[str]
parameters: dict[str, ParameterSpec]
variables: dict[str, VariableSpec]
equations: list[EquationSpec]
model_config = {'arbitrary_types_allowed': True, 'frozen': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod validate_unique_sets(v)[source]

Ensure required sets are unique.

Parameters:

v (list[str])

Return type:

list[str]

abstractmethod setup(set_manager, parameters, variables)[source]

Set up the block in the model.

This method is called when the block is added to a model. It should create and return the actual equation objects.

Parameters:

  • set_manager (SetManager) – Set manager for index validation

  • parameters (dict[str, Parameter]) – Dictionary to add parameters to

  • variables (dict[str, Variable]) – Dictionary to add variables to

Returns:

List of SymbolicEquation objects contributed by this block

Return type:

list[SymbolicEquation]

validate_sets(set_manager)[source]

Validate that all required sets exist.

Parameters:

set_manager (SetManager) – Set manager to check against

Returns:

True if all sets exist

Raises:

ValueError – If a required set is missing

Return type:

bool

get_info()[source]

Get block metadata as dictionary.

Returns:

Dictionary with block information

Return type:

dict[str, Any]

initialize_levels(*, set_manager, parameters, variables, mode='gams_blockwise')[source]

Initialize or update variable levels for this block.

This hook is intentionally optional. Concrete blocks can override it to implement GAMS-style blockwise initialization logic without embedding the logic directly in a solver.

Parameters:

  • set_manager (SetManager) – Set manager with resolved model sets.

  • parameters (dict[str, Any]) – Calibrated parameter values/symbols.

  • variables (dict[str, Any]) – Mutable variable-level container to update in-place.

  • mode (str) – Initialization mode label (e.g. gams_blockwise).

Return type:

None

validate_initialization(*, set_manager, parameters, variables)[source]

Return block residual diagnostics after initialization.

Blocks can override this to report equation-level residuals immediately after initialize_levels. Default implementation returns an empty map.

Parameters:

  • set_manager (SetManager) – Set manager with resolved model sets.

  • parameters (dict[str, Any]) – Calibrated parameter values/symbols.

  • variables (dict[str, Any]) – Current initialized variable levels.

Returns:

Mapping equation_name -> residual.

Return type:

dict[str, float]

class equilibria.blocks.base.BlockRegistry[source]

Bases: object

Registry for block classes.

Maintains a registry of available block types for easy lookup and instantiation.

Example

>>> registry = BlockRegistry()
>>> registry.register(CESValueAdded)
>>> block_class = registry.get("CESValueAdded")
>>> block = block_class(sigma=0.8)
register(block_class)[source]

Register a block class.

Parameters:

block_class (type[Block]) – Block class to register

Raises:

ValueError – If block with same name already registered

Return type:

None

get(name)[source]

Get a block class by name.

Parameters:

name (str) – Block class name

Returns:

Block class

Raises:

KeyError – If block not found

Return type:

type[Block]

list_blocks()[source]

Return list of registered block names.

Return type:

list[str]

create(name, **kwargs)[source]

Create a block instance.

Parameters:

  • name (str) – Block class name

  • **kwargs (Any) – Arguments to pass to block constructor

Returns:

Block instance

Return type:

Block

equilibria.blocks.base.get_registry()[source]

Get the global block registry.

Returns:

Global BlockRegistry instance

Return type:

BlockRegistry

equilibria.blocks.base.register_block(block_class)[source]

Decorator to register a block class.

Example

>>> @register_block
... class CESValueAdded(Block):
...     pass
Parameters:

block_class (type[Block])

Return type:

type[Block]

Production blocks for CGE models with equations.

This module provides production-related equation blocks including: - CES value-added aggregation - Leontief intermediate inputs - CET transformation

class equilibria.blocks.production.CESValueAdded(*, dummy_defaults={}, name='CES_VA', description='CES value-added production', required_sets=<factory>, parameters=<factory>, variables=<factory>, equations=<factory>, sigma=0.8)[source]

Bases: Block

CES value-added production block.

Parameters:
sigma: float
name: str
description: str
model_post_init(_CESValueAdded__context)[source]

Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

Parameters:

_CESValueAdded__context (Any)

Return type:

None

setup(set_manager, parameters, variables)[source]

Set up the block in the model.

This method is called when the block is added to a model. It should create and return the actual equation objects.

Parameters:

  • set_manager – Set manager for index validation

  • parameters – Dictionary to add parameters to

  • variables – Dictionary to add variables to

Returns:

List of SymbolicEquation objects contributed by this block

Return type:

list[SymbolicEquation]

get_calibration_phases()[source]

Return calibration phases for this block.

model_config = {'arbitrary_types_allowed': True, 'frozen': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class equilibria.blocks.production.LeontiefIntermediate(*, dummy_defaults={}, name='Leontief_INT', description='Leontief intermediate inputs', required_sets=<factory>, parameters=<factory>, variables=<factory>, equations=<factory>)[source]

Bases: Block

Leontief intermediate input block.

Parameters:
name: str
description: str
model_post_init(_LeontiefIntermediate__context)[source]

Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

Parameters:

_LeontiefIntermediate__context (Any)

Return type:

None

setup(set_manager, parameters, variables)[source]

Set up the block in the model.

This method is called when the block is added to a model. It should create and return the actual equation objects.

Parameters:

  • set_manager – Set manager for index validation

  • parameters – Dictionary to add parameters to

  • variables – Dictionary to add variables to

Returns:

List of SymbolicEquation objects contributed by this block

Return type:

list[SymbolicEquation]

get_calibration_phases()[source]

Return calibration phases for this block.

model_config = {'arbitrary_types_allowed': True, 'frozen': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class equilibria.blocks.production.CETTransformation(*, dummy_defaults={}, name='CET', description='CET output transformation', required_sets=<factory>, parameters=<factory>, variables=<factory>, equations=<factory>, omega=2.0)[source]

Bases: Block

CET output transformation block.

Parameters:
omega: float
name: str
description: str
model_post_init(_CETTransformation__context)[source]

Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

Parameters:

_CETTransformation__context (Any)

Return type:

None

setup(set_manager, parameters, variables)[source]

Set up the block in the model.

This method is called when the block is added to a model. It should create and return the actual equation objects.

Parameters:

  • set_manager – Set manager for index validation

  • parameters – Dictionary to add parameters to

  • variables – Dictionary to add variables to

Returns:

List of SymbolicEquation objects contributed by this block

Return type:

list[SymbolicEquation]

get_calibration_phases()[source]

Return calibration phases for this block.

model_config = {'arbitrary_types_allowed': True, 'frozen': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class equilibria.blocks.production.PEPProductionAccountingInit(*, dummy_defaults={}, name='PEP_ProductionAccounting_Init', description='PEP blockwise production accounting initialization and validation', required_sets=<factory>, parameters=<factory>, variables=<factory>, equations=<factory>)[source]

Bases: Block

PEP production-accounting blockwise initializer/validator.

Targets accounting consistency for production/intermediate-use identities, especially EQ2, EQ9, EQ65, and EQ67.

Parameters:
name: str
description: str
model_post_init(_PEPProductionAccountingInit__context)[source]

Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

Parameters:

_PEPProductionAccountingInit__context (Any)

Return type:

None

setup(set_manager, parameters, variables)[source]

Set up the block in the model.

This method is called when the block is added to a model. It should create and return the actual equation objects.

Parameters:

  • set_manager (SetManager) – Set manager for index validation

  • parameters (dict[str, Parameter]) – Dictionary to add parameters to

  • variables (dict[str, Variable]) – Dictionary to add variables to

Returns:

List of SymbolicEquation objects contributed by this block

Return type:

list[SymbolicEquation]

initialize_levels(*, set_manager, parameters, variables, mode='gams_blockwise')[source]

Initialize or update variable levels for this block.

This hook is intentionally optional. Concrete blocks can override it to implement GAMS-style blockwise initialization logic without embedding the logic directly in a solver.

Parameters:

  • set_manager (SetManager) – Set manager with resolved model sets.

  • parameters (dict[str, Any]) – Calibrated parameter values/symbols.

  • variables (dict[str, Any]) – Mutable variable-level container to update in-place.

  • mode (str) – Initialization mode label (e.g. gams_blockwise).

Return type:

None

validate_initialization(*, set_manager, parameters, variables)[source]

Return block residual diagnostics after initialization.

Blocks can override this to report equation-level residuals immediately after initialize_levels. Default implementation returns an empty map.

Parameters:

  • set_manager (SetManager) – Set manager with resolved model sets.

  • parameters (dict[str, Any]) – Calibrated parameter values/symbols.

  • variables (dict[str, Any]) – Current initialized variable levels.

Returns:

Mapping equation_name -> residual.

Return type:

dict[str, float]

model_config = {'arbitrary_types_allowed': True, 'frozen': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Trade blocks for CGE models.

This module provides trade-related equation blocks including: - Armington CES import aggregation - CET export transformation

class equilibria.blocks.trade.ArmingtonCES(*, dummy_defaults={}, name='Armington', description='Armington CES import aggregation', required_sets=<factory>, parameters=<factory>, variables=<factory>, equations=<factory>, sigma_m=1.5)[source]

Bases: Block

Armington CES import aggregation block.

Implements Armington aggregation of domestic and imported goods using CES specification. Consumers view domestic and imported varieties as imperfect substitutes.

Required sets:

  • I: Commodities

Equations:

  1. Armington aggregation: QA[i] = A_Ar[i] * (alpha_D[i]*QD[i]^(-rho) + alpha_M[i]*QM[i]^(-rho))^(-1/rho)

  2. FOC domestic: PD[i]/PA[i] = (alpha_D[i]) * (QA[i]/QD[i])^(rho+1)

  3. FOC imports: PM[i]/PA[i] = (alpha_M[i]) * (QA[i]/QM[i])^(rho+1)

Variables:

  • sigma_m (float) – Elasticity of substitution between domestic and imports (default: 1.5)

  • name (str) – Block name (default: “Armington”)

Parameters:
sigma_m: float
name: str
description: str
model_post_init(_ArmingtonCES__context)[source]

Initialize block specifications.

Parameters:

_ArmingtonCES__context (Any)

Return type:

None

setup(set_manager, parameters, variables)[source]

Set up the Armington block.

Parameters:

  • set_manager (SetManager)

  • parameters (dict[str, Parameter])

  • variables (dict[str, Variable])

Return type:

list[SymbolicEquation]

get_calibration_phases()[source]

Return calibration phases for this block.

model_config = {'arbitrary_types_allowed': True, 'frozen': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class equilibria.blocks.trade.CETExports(*, dummy_defaults={}, name='CET_Exports', description='CET export transformation', required_sets=<factory>, parameters=<factory>, variables=<factory>, equations=<factory>, sigma_e=2.0)[source]

Bases: Block

CET export supply block.

Implements Constant Elasticity of Transformation between domestic sales and exports. Producers can transform output between domestic and export markets.

Required sets:

  • J: Production sectors (or I: Commodities)

Equations:

  1. CET: Z[j] = B_X[j] * (xi_D[j]*XD[j]^rho + xi_E[j]*XE[j]^rho)^(1/rho)

  2. FOC: PE[j]/PD[j] = (xi_E[j]/xi_D[j]) * (XE[j]/XD[j])^(rho-1)

Variables:

  • sigma_e (float) – Elasticity of transformation (default: 2.0)

  • name (str) – Block name (default: “CET_Exports”)

Parameters:
sigma_e: float
name: str
description: str
model_post_init(_CETExports__context)[source]

Initialize block specifications.

Parameters:

_CETExports__context (Any)

Return type:

None

setup(set_manager, parameters, variables)[source]

Set up the CET exports block.

Parameters:

  • set_manager (SetManager)

  • parameters (dict[str, Parameter])

  • variables (dict[str, Variable])

Return type:

list[SymbolicEquation]

get_calibration_phases()[source]

Return calibration phases for this block.

model_config = {'arbitrary_types_allowed': True, 'frozen': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class equilibria.blocks.trade.PEPTradeFlowInit(*, dummy_defaults={}, name='PEP_TradeFlow_Init', description='PEP blockwise trade-flow initialization and validation', required_sets=<factory>, parameters=<factory>, variables=<factory>, equations=<factory>)[source]

Bases: Block

PEP trade-flow blockwise initializer/validator (EQ57-EQ64).

This block is meant for blockwise level initialization workflows where variable levels are updated from calibrated PEP parameters and immediately validated against trade equations.

Parameters:
name: str
description: str
model_post_init(_PEPTradeFlowInit__context)[source]

Initialize block specifications.

Parameters:

_PEPTradeFlowInit__context (Any)

Return type:

None

setup(set_manager, parameters, variables)[source]

No symbolic equations here; this block provides init/validation hooks.

Parameters:

  • set_manager (SetManager)

  • parameters (dict[str, Parameter])

  • variables (dict[str, Variable])

Return type:

list[SymbolicEquation]

initialize_levels(*, set_manager, parameters, variables, mode='gams_blockwise')[source]

Initialize trade-flow levels from calibrated benchmark maps.

Parameters:
Return type:

None

validate_initialization(*, set_manager, parameters, variables)[source]

Validate EQ57-EQ64 residuals for initialized trade-flow levels.

Parameters:
Return type:

dict[str, float]

model_config = {'arbitrary_types_allowed': True, 'frozen': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class equilibria.blocks.trade.PEPTradeTransformationInit(*, dummy_defaults={}, name='PEP_TradeTransformation_Init', description='PEP blockwise trade transformation initialization and validation', required_sets=<factory>, parameters=<factory>, variables=<factory>, equations=<factory>)[source]

Bases: Block

PEP trade transformation blockwise initializer/validator (EQ58-EQ59).

Parameters:
name: str
description: str
model_post_init(_PEPTradeTransformationInit__context)[source]

Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

Parameters:

_PEPTradeTransformationInit__context (Any)

Return type:

None

setup(set_manager, parameters, variables)[source]

Set up the block in the model.

This method is called when the block is added to a model. It should create and return the actual equation objects.

Parameters:

  • set_manager (SetManager) – Set manager for index validation

  • parameters (dict[str, Parameter]) – Dictionary to add parameters to

  • variables (dict[str, Variable]) – Dictionary to add variables to

Returns:

List of SymbolicEquation objects contributed by this block

Return type:

list[SymbolicEquation]

initialize_levels(*, set_manager, parameters, variables, mode='gams_blockwise')[source]

Initialize or update variable levels for this block.

This hook is intentionally optional. Concrete blocks can override it to implement GAMS-style blockwise initialization logic without embedding the logic directly in a solver.

Parameters:

  • set_manager (SetManager) – Set manager with resolved model sets.

  • parameters (dict[str, Any]) – Calibrated parameter values/symbols.

  • variables (dict[str, Any]) – Mutable variable-level container to update in-place.

  • mode (str) – Initialization mode label (e.g. gams_blockwise).

Return type:

None

validate_initialization(*, set_manager, parameters, variables)[source]

Return block residual diagnostics after initialization.

Blocks can override this to report equation-level residuals immediately after initialize_levels. Default implementation returns an empty map.

Parameters:

  • set_manager (SetManager) – Set manager with resolved model sets.

  • parameters (dict[str, Any]) – Calibrated parameter values/symbols.

  • variables (dict[str, Any]) – Current initialized variable levels.

Returns:

Mapping equation_name -> residual.

Return type:

dict[str, float]

model_config = {'arbitrary_types_allowed': True, 'frozen': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class equilibria.blocks.trade.PEPCommodityBalanceInit(*, dummy_defaults={}, name='PEP_CommodityBalance_Init', description='PEP blockwise commodity balance initialization and validation', required_sets=<factory>, parameters=<factory>, variables=<factory>, equations=<factory>)[source]

Bases: Block

PEP commodity-balance blockwise initializer/validator.

Reconciles commodity quantities by coupling: - EQ57 (margins), - EQ63 (Armington CES quantity), - EQ79 (composite value identity), - EQ84 (composite-good market clearing).

Parameters:
name: str
description: str
model_post_init(_PEPCommodityBalanceInit__context)[source]

Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

Parameters:

_PEPCommodityBalanceInit__context (Any)

Return type:

None

setup(set_manager, parameters, variables)[source]

Set up the block in the model.

This method is called when the block is added to a model. It should create and return the actual equation objects.

Parameters:

  • set_manager (SetManager) – Set manager for index validation

  • parameters (dict[str, Parameter]) – Dictionary to add parameters to

  • variables (dict[str, Variable]) – Dictionary to add variables to

Returns:

List of SymbolicEquation objects contributed by this block

Return type:

list[SymbolicEquation]

initialize_levels(*, set_manager, parameters, variables, mode='gams_blockwise')[source]

Initialize or update variable levels for this block.

This hook is intentionally optional. Concrete blocks can override it to implement GAMS-style blockwise initialization logic without embedding the logic directly in a solver.

Parameters:

  • set_manager (SetManager) – Set manager with resolved model sets.

  • parameters (dict[str, Any]) – Calibrated parameter values/symbols.

  • variables (dict[str, Any]) – Mutable variable-level container to update in-place.

  • mode (str) – Initialization mode label (e.g. gams_blockwise).

Return type:

None

validate_initialization(*, set_manager, parameters, variables)[source]

Return block residual diagnostics after initialization.

Blocks can override this to report equation-level residuals immediately after initialize_levels. Default implementation returns an empty map.

Parameters:

  • set_manager (SetManager) – Set manager with resolved model sets.

  • parameters (dict[str, Any]) – Calibrated parameter values/symbols.

  • variables (dict[str, Any]) – Current initialized variable levels.

Returns:

Mapping equation_name -> residual.

Return type:

dict[str, float]

model_config = {'arbitrary_types_allowed': True, 'frozen': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class equilibria.blocks.trade.PEPTradeMarketClearingInit(*, dummy_defaults={}, name='PEP_TradeMarketClearing_Init', description='PEP blockwise trade market-clearing initialization and validation', required_sets=<factory>, parameters=<factory>, variables=<factory>, equations=<factory>)[source]

Bases: Block

PEP trade market-clearing blockwise initializer/validator (EQ64/EQ88).

Parameters:
name: str
description: str
model_post_init(_PEPTradeMarketClearingInit__context)[source]

Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

Parameters:

_PEPTradeMarketClearingInit__context (Any)

Return type:

None

setup(set_manager, parameters, variables)[source]

Set up the block in the model.

This method is called when the block is added to a model. It should create and return the actual equation objects.

Parameters:

  • set_manager (SetManager) – Set manager for index validation

  • parameters (dict[str, Parameter]) – Dictionary to add parameters to

  • variables (dict[str, Variable]) – Dictionary to add variables to

Returns:

List of SymbolicEquation objects contributed by this block

Return type:

list[SymbolicEquation]

initialize_levels(*, set_manager, parameters, variables, mode='gams_blockwise')[source]

Initialize or update variable levels for this block.

This hook is intentionally optional. Concrete blocks can override it to implement GAMS-style blockwise initialization logic without embedding the logic directly in a solver.

Parameters:

  • set_manager (SetManager) – Set manager with resolved model sets.

  • parameters (dict[str, Any]) – Calibrated parameter values/symbols.

  • variables (dict[str, Any]) – Mutable variable-level container to update in-place.

  • mode (str) – Initialization mode label (e.g. gams_blockwise).

Return type:

None

validate_initialization(*, set_manager, parameters, variables)[source]

Return block residual diagnostics after initialization.

Blocks can override this to report equation-level residuals immediately after initialize_levels. Default implementation returns an empty map.

Parameters:

  • set_manager (SetManager) – Set manager with resolved model sets.

  • parameters (dict[str, Any]) – Calibrated parameter values/symbols.

  • variables (dict[str, Any]) – Current initialized variable levels.

Returns:

Mapping equation_name -> residual.

Return type:

dict[str, float]

model_config = {'arbitrary_types_allowed': True, 'frozen': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Demand blocks for CGE models.

This module provides consumer demand-related equation blocks including: - LES (Linear Expenditure System) - Cobb-Douglas demand

class equilibria.blocks.demand.LESConsumer(*, dummy_defaults={}, name='LES_Consumer', description='Linear Expenditure System consumer demand', required_sets=<factory>, parameters=<factory>, variables=<factory>, equations=<factory>)[source]

Bases: Block

Linear Expenditure System (LES) consumer demand block.

Implements LES demand system where consumers have: - Subsistence consumption (minimum requirements) - Supernumerary consumption (discretionary spending)

The LES demand function is: QD[i] = gamma[i] + (beta[i] / PA[i]) * (Y - sum_j PA[j] * gamma[j])

Where: - QD[i] = demand for commodity i - gamma[i] = subsistence consumption - beta[i] = marginal budget share - PA[i] = price of commodity i - Y = total income - sum_j PA[j] * gamma[j] = subsistence expenditure

Variables:

name (str) – Block name (default: “LES_Consumer”)

Parameters:
name: str
description: str
model_post_init(_LESConsumer__context)[source]

Initialize block specifications.

Parameters:

_LESConsumer__context (Any)

Return type:

None

setup(set_manager, parameters, variables)[source]

Set up the LES consumer block.

Parameters:

  • set_manager (SetManager)

  • parameters (dict[str, Parameter])

  • variables (dict[str, Variable])

Return type:

list[SymbolicEquation]

get_calibration_phases()[source]

Return calibration phases for this block.

model_config = {'arbitrary_types_allowed': True, 'frozen': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class equilibria.blocks.demand.CobbDouglasConsumer(*, dummy_defaults={}, name='CD_Consumer', description='Cobb-Douglas consumer demand', required_sets=<factory>, parameters=<factory>, variables=<factory>, equations=<factory>)[source]

Bases: Block

Cobb-Douglas consumer demand block.

Implements Cobb-Douglas utility with constant expenditure shares.

The Cobb-Douglas demand function is: QD[i] = (alpha[i] * Y) / PA[i]

Where: - QD[i] = demand for commodity i - alpha[i] = expenditure share (constant) - Y = total income - PA[i] = price of commodity i

Variables:

name (str) – Block name (default: “CD_Consumer”)

Parameters:
name: str
description: str
model_post_init(_CobbDouglasConsumer__context)[source]

Initialize block specifications.

Parameters:

_CobbDouglasConsumer__context (Any)

Return type:

None

setup(set_manager, parameters, variables)[source]

Set up the Cobb-Douglas consumer block.

Parameters:

  • set_manager (SetManager)

  • parameters (dict[str, Parameter])

  • variables (dict[str, Variable])

Return type:

list[SymbolicEquation]

get_calibration_phases()[source]

Return calibration phases for this block.

model_config = {'arbitrary_types_allowed': True, 'frozen': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Institution blocks for CGE models.

This module provides institution-related equation blocks including: - Household income and expenditure - Government budget - Rest of world (trade balance)

class equilibria.blocks.institutions.Household(*, dummy_defaults={}, name='Household', description='Household income and expenditure', required_sets=<factory>, parameters=<factory>, variables=<factory>, equations=<factory>)[source]

Bases: Block

Household income and expenditure block.

Models household income from factor payments and expenditure on commodities.

Income sources: - Factor payments (labor, capital) - Transfers from government - Transfers from abroad

Variables:

name (str) – Block name (default: “Household”)

Parameters:
name: str
description: str
model_post_init(_Household__context)[source]

Initialize block specifications.

Parameters:

_Household__context (Any)

Return type:

None

setup(set_manager, parameters, variables)[source]

Set up the household block.

Parameters:

  • set_manager (SetManager)

  • parameters (dict[str, Parameter])

  • variables (dict[str, Variable])

Return type:

list[SymbolicEquation]

get_calibration_phases()[source]

Return calibration phases for this block.

model_config = {'arbitrary_types_allowed': True, 'frozen': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class equilibria.blocks.institutions.Government(*, dummy_defaults={}, name='Government', description='Government budget', required_sets=<factory>, parameters=<factory>, variables=<factory>, equations=<factory>)[source]

Bases: Block

Government budget block.

Models government revenue (taxes) and expenditure.

Revenue sources: - Production taxes - Import tariffs - Income taxes

Expenditures: - Government consumption - Transfers to households - Savings

Variables:

name (str) – Block name (default: “Government”)

Parameters:
name: str
description: str
model_post_init(_Government__context)[source]

Initialize block specifications.

Parameters:

_Government__context (Any)

Return type:

None

setup(set_manager, parameters, variables)[source]

Set up the government block.

Parameters:

  • set_manager (SetManager)

  • parameters (dict[str, Parameter])

  • variables (dict[str, Variable])

Return type:

list[SymbolicEquation]

get_calibration_phases()[source]

Return calibration phases for this block.

model_config = {'arbitrary_types_allowed': True, 'frozen': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class equilibria.blocks.institutions.RestOfWorld(*, dummy_defaults={}, name='ROW', description='Rest of world (foreign sector)', required_sets=<factory>, parameters=<factory>, variables=<factory>, equations=<factory>)[source]

Bases: Block

Rest of World (foreign sector) block.

Models trade balance and foreign transfers.

Variables:

name (str) – Block name (default: “ROW”)

Parameters:
name: str
description: str
model_post_init(_RestOfWorld__context)[source]

Initialize block specifications.

Parameters:

_RestOfWorld__context (Any)

Return type:

None

setup(set_manager, parameters, variables)[source]

Set up the ROW block.

Parameters:

  • set_manager (SetManager)

  • parameters (dict[str, Parameter])

  • variables (dict[str, Variable])

Return type:

list[SymbolicEquation]

get_calibration_phases()[source]

Return calibration phases for this block.

model_config = {'arbitrary_types_allowed': True, 'frozen': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Equilibrium blocks for CGE models.

This module provides market equilibrium-related equation blocks: - Market clearing conditions - Price normalization

class equilibria.blocks.equilibrium.MarketClearing(*, dummy_defaults={}, name='MarketClearing', description='Market clearing conditions', required_sets=<factory>, parameters=<factory>, variables=<factory>, equations=<factory>)[source]

Bases: Block

Market clearing condition block.

Ensures supply equals demand for all commodities: QS[i] = QD[i] for all commodities i

Where: - QS[i] = total supply of commodity i (domestic + imports) - QD[i] = total demand for commodity i (intermediate + final)

Variables:

name (str) – Block name (default: “MarketClearing”)

Parameters:
name: str
description: str
model_post_init(_MarketClearing__context)[source]

Initialize block specifications.

Parameters:

_MarketClearing__context (Any)

Return type:

None

setup(set_manager, parameters, variables)[source]

Set up the market clearing block.

Parameters:

  • set_manager (SetManager)

  • parameters (dict[str, Parameter])

  • variables (dict[str, Variable])

Return type:

list[SymbolicEquation]

get_calibration_phases()[source]

Return calibration phases for this block.

model_config = {'arbitrary_types_allowed': True, 'frozen': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class equilibria.blocks.equilibrium.PriceNormalization(*, dummy_defaults={}, name='PriceNorm', description='Price normalization (numeraire)', required_sets=<factory>, parameters=<factory>, variables=<factory>, equations=<factory>, numeraire='')[source]

Bases: Block

Price normalization block.

Sets the numeraire price to fix the price level: P[numeraire] = 1

Variables:

  • name (str) – Block name (default: “PriceNorm”)

  • numeraire (str) – Name of numeraire commodity (default: first commodity)

Parameters:
name: str
description: str
numeraire: str
model_post_init(_PriceNormalization__context)[source]

Initialize block specifications.

Parameters:

_PriceNormalization__context (Any)

Return type:

None

setup(set_manager, parameters, variables)[source]

Set up the price normalization block.

Parameters:

  • set_manager (SetManager)

  • parameters (dict[str, Parameter])

  • variables (dict[str, Variable])

Return type:

list[SymbolicEquation]

get_calibration_phases()[source]

Return calibration phases for this block.

model_config = {'arbitrary_types_allowed': True, 'frozen': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class equilibria.blocks.equilibrium.FactorMarketClearing(*, dummy_defaults={}, name='FactorMarket', description='Factor market clearing', required_sets=<factory>, parameters=<factory>, variables=<factory>, equations=<factory>)[source]

Bases: Block

Factor market clearing block.

Ensures factor supply equals factor demand: FSUP[f] = FD[f] for all factors f

Where: - FSUP[f] = supply of factor f - FD[f] = demand for factor f

Variables:

name (str) – Block name (default: “FactorMarket”)

Parameters:
name: str
description: str
model_post_init(_FactorMarketClearing__context)[source]

Initialize block specifications.

Parameters:

_FactorMarketClearing__context (Any)

Return type:

None

setup(set_manager, parameters, variables)[source]

Set up the factor market clearing block.

Parameters:

  • set_manager (SetManager)

  • parameters (dict[str, Parameter])

  • variables (dict[str, Variable])

Return type:

list[SymbolicEquation]

get_calibration_phases()[source]

Return calibration phases for this block.

model_config = {'arbitrary_types_allowed': True, 'frozen': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class equilibria.blocks.equilibrium.PEPMacroClosureInit(*, dummy_defaults={}, name='PEP_MacroClosure_Init', description='PEP blockwise macro closure initialization and validation', required_sets=<factory>, parameters=<factory>, variables=<factory>, equations=<factory>)[source]

Bases: Block

PEP macro closure blockwise initializer/validator.

Reconciles: - EQ44 (YROW), - EQ45 / EQ46 (SROW, CAB), - EQ87 (IT = savings closure), - EQ93 (GDP_FD identity).

Parameters:
name: str
description: str
model_post_init(_PEPMacroClosureInit__context)[source]

Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

Parameters:

_PEPMacroClosureInit__context (Any)

Return type:

None

setup(set_manager, parameters, variables)[source]

Set up the block in the model.

This method is called when the block is added to a model. It should create and return the actual equation objects.

Parameters:

  • set_manager (SetManager) – Set manager for index validation

  • parameters (dict[str, Parameter]) – Dictionary to add parameters to

  • variables (dict[str, Variable]) – Dictionary to add variables to

Returns:

List of SymbolicEquation objects contributed by this block

Return type:

list[SymbolicEquation]

initialize_levels(*, set_manager, parameters, variables, mode='gams_blockwise')[source]

Initialize or update variable levels for this block.

This hook is intentionally optional. Concrete blocks can override it to implement GAMS-style blockwise initialization logic without embedding the logic directly in a solver.

Parameters:

  • set_manager (SetManager) – Set manager with resolved model sets.

  • parameters (dict[str, Any]) – Calibrated parameter values/symbols.

  • variables (dict[str, Any]) – Mutable variable-level container to update in-place.

  • mode (str) – Initialization mode label (e.g. gams_blockwise).

Return type:

None

validate_initialization(*, set_manager, parameters, variables)[source]

Return block residual diagnostics after initialization.

Blocks can override this to report equation-level residuals immediately after initialize_levels. Default implementation returns an empty map.

Parameters:

  • set_manager (SetManager) – Set manager with resolved model sets.

  • parameters (dict[str, Any]) – Calibrated parameter values/symbols.

  • variables (dict[str, Any]) – Current initialized variable levels.

Returns:

Mapping equation_name -> residual.

Return type:

dict[str, float]

model_config = {'arbitrary_types_allowed': True, 'frozen': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].