international_buyer
agents.international_buyer
International buyer agent module for the EcoWHEATaly model.
Defines the InternationalBuyer agent representing a world-region wheat buyer (e.g., North Africa, Central Asia). Each buyer maintains per-producer demand functions and evolves its buying strategy by shifting demand from expensive to cheap producers over time.
InternationalBuyer
Bases: Agent
Repast4py agent representing an international wheat buyer.
Each buyer is associated with a geographic area that has its own domestic demand and production. It maintains linear demand functions toward each international producer and adjusts them based on observed price differentials and transport costs.
Attributes:
| Name | Type | Description |
|---|---|---|
TYPE |
Agent type identifier used by repast4py context. |
initializeBuyingStrategy(int_availability_status)
Initialize demand functions toward each international producer.
Builds per-producer linear demand functions characterized by a quantity at the average price, a higher-demand quantity, and an elasticity. Allocates import demand across producers based on their export market shares. Also prepares the bought-quantities tracking structure with transport cost information.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
int_availability_status
|
DataFrame summarizing each producer's output, export openness, and market share. |
required |
update_transport_costs(delta_tc)
Update transport cost coefficients and recalculate per-producer costs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
delta_tc
|
Increment to add to both sea and land transport cost coefficients (per ton per km). |
required |
answerDemandQueryFromProducer(prodName)
Return this buyer's demand function parameters for a producer.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prodName
|
Area name of the querying producer. |
required |
Returns:
| Type | Description |
|---|---|
|
A pandas Series with demand at average price, higher |
|
|
demand, and demand elasticity for the given producer. |
checkObtainedQuantitiesAndEvolveBuyingStrategy(tmpcontext)
Update buying strategy based on latest market outcomes.
Records the equilibrium prices and exchanged quantities from each producer, then shifts demand from expensive to cheap producers using a logistic function of the price range. Applies optional simulated annealing to reduce the magnitude of demand shifts over time.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tmpcontext
|
The simulation Model instance providing access to the repast4py context. |
required |
switchAnnealingOn()
Enable simulated annealing on demand reallocation.
switchAnnealingOff()
Disable simulated annealing on demand reallocation.
resetPercentageToMove(percentage)
Set the percentage of demand to shift between producers.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
percentage
|
New demand-movement fraction (0 to 1). |
required |
resetAnnealingSpeed(speed)
Set the annealing speed for demand reallocation decay.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
speed
|
New annealing speed coefficient. |
required |
resetDemandElasticity(new_elasticity)
Set the demand elasticity for all producer demand functions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
new_elasticity
|
New elasticity value applied to all demand functions. |
required |
save()
Serialize the agent state for MPI communication.
Returns:
| Type | Description |
|---|---|
Tuple
|
The agent's unique identifier tuple |
print_status()
Print a short status message identifying this agent.