Firms API Reference

This section documents the Firms agent in the macromodel package, which represents the productive sector of the economy and manages firm-level production, pricing, investment, and financial decisions.

The Firms agent includes comprehensive support for productivity dynamics through: - Productivity Investment Planning: Firms can strategically invest in productivity improvements based on expected returns - Total Factor Productivity (TFP) Growth: Multiple models for how productivity evolves over time, including deterministic, stochastic, and sector-specific growth patterns - Endogenous Growth: Productivity improvements driven by firm-level investment decisions, creating a feedback loop between profitability and productivity

The Firms agent also supports flexible production structures through: - Substitution Bundles: Groups of inputs that can be substituted for one another using CES (Constant Elasticity of Substitution) production functions - Bundled Leontief Production: Combines fixed-proportion Leontief technology for most inputs with CES substitution within specified bundles (e.g., energy inputs) - Dynamic Input Mix: Firms adjust their input combinations based on relative prices, allowing for realistic responses to price shocks and policy changes - Sector-Specific Configurations: Different industries can have different substitution possibilities, reflecting technological constraints

macromodel.agents.firms.firms.Firms

A collection of producing firms in the economy.

This class represents the productive sector of the economy, managing multiple firms that produce goods using labor, intermediate inputs, and capital inputs. Each firm: - Makes production decisions based on expected demand and capacity - Sets prices based on costs and market conditions - Hires workers and sets wages - Manages inventory and input stocks - Makes investment decisions - Handles financial decisions (borrowing, etc.) - Can become insolvent

The firms operate in discrete time steps, with each period involving: 1. Planning (production targets, input needs, hiring) 2. Market participation (labor, credit, goods markets) 3. Production and sales 4. Financial settlement (wages, loans, taxes)

Attributes:

Name	Type	Description
country_name	str	Country the firms operate in
all_country_names	list[str]	All countries in simulation
n_industries	int	Number of industry sectors
functions	dict[str, Callable]	Production and decision functions
ts	FirmTimeSeries	Time series data for firms
states	dict[str, ndarray]	Current state variables
base_intermediate_inputs_productivity_matrix	ndarray	Input-output coefficients
base_capital_inputs_productivity_matrix	ndarray	Capital productivity coefficients
base_capital_inputs_depreciation_matrix	ndarray	Capital depreciation rates
goods_criticality_matrix	ndarray	Critical input requirements
intermediate_inputs_utilisation_rate	float	Input capacity utilization
capital_inputs_utilisation_rate	float	Capital capacity utilization
capital_inputs_delay	ndarray	Investment implementation lags
depreciation_rates	ndarray	Asset depreciation rates
average_initial_price	ndarray	Initial price levels
configuration	FirmsConfiguration	Model parameters
industries	list[str]	Industry sector names

from_pickled_agent(synthetic_firms: SyntheticFirms, configuration: FirmsConfiguration, country_name: str, all_country_names: list[str], goods_criticality_matrix: pd.DataFrame | np.ndarray, average_initial_price: np.ndarray, industries: list[str], add_emissions: bool = False) classmethod

Create a Firms instance from pickled synthetic data.

Factory method that constructs a Firms object from serialized synthetic data, configuration parameters, and initial economic conditions.

Parameters:

Name	Type	Description	Default
synthetic_firms	SyntheticFirms	Synthetic firm data	required
configuration	FirmsConfiguration	Model configuration parameters	required
country_name	str	Country identifier	required
all_country_names	list[str]	All countries in simulation	required
goods_criticality_matrix	DataFrame | ndarray	Input criticality coefficients	required
average_initial_price	ndarray	Initial price levels	required
industries	list[str]	Industry sector names	required
add_emissions	bool	Whether to track emissions. Defaults to False.	False

Returns:

Name	Type	Description
Firms		Initialized Firms instance

Functions

Demography

macromodel.agents.firms.func.demography.FirmDemography

Abstract base class for managing firm demographics and survival.

This class defines strategies for handling firm insolvency and survival in the economy. It determines which firms remain active based on their financial health, specifically: - Equity position (net worth) - Deposit balances (liquidity)

The demography management is crucial for: - Maintaining realistic firm turnover - Handling business failures - Ensuring market discipline - Modeling creative destruction

Target Production

macromodel.agents.firms.func.target_production.TargetProductionSetter

Abstract base class for determining firms' target production levels.

This class defines strategies for setting production targets based on various factors: - Expected demand - Current inventory levels - Input constraints (labor, intermediate, capital) - Financial constraints (equity, debt, credit)

The class uses multiple parameters to weight different factors: - Inventory management (existing and target ratios) - Financial constraints (debt/equity limits) - Input considerations (how much each input type affects targets)

Attributes:

Name	Type	Description
existing_inventory_fraction	float	Weight given to current inventory in target calculation
target_inventory_to_production_fraction	float	Desired inventory-to-production ratio
financial_constrains_fraction	float	Weight of financial constraints on targets
maximum_debt_to_equity_ratio	float	Maximum allowed debt/equity ratio
intermediate_inputs_target_considers_labour_inputs	float	Weight of labor constraints on intermediate inputs
intermediate_inputs_target_considers_intermediate_inputs	float	Weight of input constraints on intermediate inputs
intermediate_inputs_target_considers_capital_inputs	float	Weight of capital constraints on intermediate inputs
capital_inputs_target_considers_labour_inputs	float	Weight of labor constraints on capital inputs
capital_inputs_target_considers_intermediate_inputs	float	Weight of input constraints on capital inputs
capital_inputs_target_considers_capital_inputs	float	Weight of capital constraints on capital inputs

Labour Productivity

macromodel.agents.firms.func.labour_productivity.LabourProductivitySetter

Abstract base class for determining labor productivity adjustments.

This class defines strategies for calculating labor productivity factors based on: - Work effort potential and limits - Input availability and constraints - Industry-specific productivity baselines - Adjustment speed parameters

The productivity setting process considers: - Maximum allowable work effort increases - Complementarity with other inputs - Speed of productivity adjustments

Attributes:

Name	Type	Description
max_increase_in_work_effort	float	Maximum allowed increase in productivity through work effort
consider_intermediate_inputs	float	Weight given to intermediate input constraints (0 to 1)
consider_capital_inputs	float	Weight given to capital input constraints (0 to 1)
work_effort_increase_speed	float	Rate at which work effort adjustments are implemented

Wage Setting

macromodel.agents.firms.func.wage_setter.FirmWageSetter

Abstract base class for determining firms' wage-setting strategies.

This class defines strategies for calculating wages based on: - Labor market conditions (tightness, supply/demand) - Worker productivity and effort - Tax considerations - Historical wage levels and adjustments

The wage setting process considers: - Market tightness markups based on hiring success - Work effort incentives - Tax-adjusted gross/net wage conversions

Attributes:

Name	Type	Description
labour_market_tightness_markup_scale	float	Scale factor for wage adjustments based on labor market tightness
markup_time_span	int	Number of periods to consider when calculating labor market tightness markup
max_increase_in_work_effort	float	Maximum allowed increase in work effort-based wage adjustments

Price Setting

macromodel.agents.firms.func.prices.PriceSetter

Abstract base class for determining firms' price-setting strategies.

This class defines strategies for calculating prices based on: - Market conditions (supply, demand, inventories) - Cost factors (unit costs, inflation) - Competitive positioning (sector averages) - Adjustment speeds and noise

The price setting process considers: - General inflation expectations - Demand-pull inflation pressures - Cost-push inflation pressures - Random price variations

Attributes:

Name	Type	Description
price_setting_noise_std	float	Standard deviation of random price adjustments
price_setting_speed_gf	float	Speed of general inflation pass-through (0 to 1)
price_setting_speed_dp	float	Speed of demand-pull inflation adjustments (0 to 1)
price_setting_speed_cp	float	Speed of cost-push inflation adjustments (0 to 1)

Production

macromodel.agents.firms.func.production.ProductionSetter

Abstract base class for determining firms' production processes.

This class defines strategies for calculating production levels and input usage based on: - Production technology (Leontief, Linear, etc.) - Input availability and constraints - Input productivity and criticality - Utilization rates - Input substitution bundles

The production process considers: - Labor inputs and constraints - Intermediate inputs (materials, supplies) - Capital inputs (machinery, equipment) - Input criticality and substitutability - Substitution between goods in the same bundle

Excess Demand

macromodel.agents.firms.func.excess_demand.ExcessDemandSetter

Abstract base class for determining firms' excess demand levels.

This class defines strategies for calculating excess demand based on: - Production constraints from various inputs - Target vs. actual production levels - Input-specific consideration weights

Excess demand represents unfulfilled market demand due to: - Labor constraints - Intermediate input constraints - Capital input constraints

Attributes:

Name	Type	Description
consider_intermediate_inputs	float	Weight given to intermediate input constraints (0 to 1)
consider_capital_inputs	float	Weight given to capital input constraints (0 to 1)
consider_labour_inputs	float	Weight given to labor input constraints (0 to 1)

Desired Labour

macromodel.agents.firms.func.desired_labour.DesiredLabourSetter

Abstract base class for determining firms' desired labor inputs.

This class defines strategies for calculating optimal labor demand based on: - Production targets - Input constraints (intermediate and capital) - Complementarity between labor and other inputs

The labor demand calculation considers the interaction between different factors of production, with configurable weights for: - Intermediate input constraints (materials, supplies) - Capital input constraints (machinery, equipment)

Attributes:

Name	Type	Description
consider_intermediate_inputs	float	Weight given to intermediate input constraints Clipped to range [0,1], where higher values mean stronger complementarity
consider_capital_inputs	float	Weight given to capital input constraints Clipped to range [0,1], where higher values mean stronger complementarity

Productivity Investment Planning

macromodel.agents.firms.func.productivity_investment_planner.ProductivityInvestmentPlanner

Abstract base class for planning firms' productivity investments.

This class defines strategies for determining optimal investment in productivity improvements based on: - Expected returns from TFP growth - Available financial resources - Hurdle rates and risk preferences - Market conditions and demand expectations

The investment planning follows the framework in Section 3 of the productivity examination document, implementing the decision logic for allocating resources to productivity improvements.

Attributes:

Name	Type	Description
hurdle_rate	float	Minimum required rate of return (ρ_min)
max_investment_fraction	float	Maximum investment as fraction of output (θ)
investment_effectiveness	float	How investment translates to TFP growth (φ)
investment_elasticity	float	Returns to scale parameter (α)

Productivity Growth (TFP)

macromodel.agents.firms.func.productivity_growth.ProductivityGrowth

Abstract base class for computing Total Factor Productivity (TFP) growth.

This class defines strategies for calculating how firms' productivity grows over time based on: - Base/exogenous growth rates - Investment in productivity improvements - Stochastic shocks (optional)

TFP affects all inputs uniformly, allowing firms to produce more output with the same amount of inputs.