agent_urban_planning.Zone

class Zone(name, housing_supply, housing_base_price, amenity_score, facilities=<factory>, job_density=0.0, private_supply=0, private_base_price=0.0, commercial_floor_area=0.0, residential_floor_area=0.0, productivity_A=0.0, amenity_B=0.0, wage_observed=0.0, floor_price_observed=0.0, productivity_fundamental_a=0.0, amenity_fundamental_b=0.0, total_floor_area=0.0)[source]

Bases: object

One geographic unit (planning area or block) in a scenario.

Carries everything the simulator needs to know about a single location: housing supply, exogenous price level, amenity score, facilities, and optional Ahlfeldt-model fundamentals (productivity A_i, amenity B_i, wage, observed floor price, and the raw pre-agglomeration primitives a_i and b_i). Most fields are populated from a scenario YAML via Environment.from_config().

Variables:

  • name – Unique zone identifier (e.g. "Mitte", "Punggol").

  • housing_supply – Number of HDB units available in this zone.

  • housing_base_price – Exogenous starting HDB price.

  • amenity_score – Generic amenity index used by the Singapore-style utility engines.

  • facilities – List of Facility instances in this zone.

  • job_density – Employment density used as a proxy for workplace attractiveness.

  • private_supply – Number of private housing units (Singapore two-segment scenarios only).

  • private_base_price – Exogenous starting private-market price.

  • commercial_floor_area – Square meters of commercial floor space (Ahlfeldt scenarios).

  • residential_floor_area – Square meters of residential floor space (Ahlfeldt scenarios).

  • productivity_A – Post-agglomeration productivity A_i.

  • amenity_B – Post-agglomeration amenity B_i.

  • wage_observed – Observed wage at the zone (Ahlfeldt scenarios).

  • floor_price_observed – Observed residential floor price.

  • productivity_fundamental_a – Raw (pre-agglomeration) productivity primitive a_i. When endogenous_agglomeration is on, the market re-computes A_i from this each iteration.

  • amenity_fundamental_b – Raw (pre-agglomeration) amenity primitive b_i.

  • total_floor_area – Total square meters of floor (residential + commercial). When endogenous_land_use is on, the unified price P_i clears combined demand against this total.

Parameters:

  • name (str)

  • housing_supply (int)

  • housing_base_price (float)

  • amenity_score (float)

  • facilities (list[Facility])

  • job_density (float)

  • private_supply (int)

  • private_base_price (float)

  • commercial_floor_area (float)

  • residential_floor_area (float)

  • productivity_A (float)

  • amenity_B (float)

  • wage_observed (float)

  • floor_price_observed (float)

  • productivity_fundamental_a (float)

  • amenity_fundamental_b (float)

  • total_floor_area (float)

Examples

>>> from agent_urban_planning.core.environment import Zone, Facility
>>> z = Zone(
...     name="Mitte",
...     housing_supply=10000,
...     housing_base_price=1.0,
...     amenity_score=0.8,
... )
>>> z.has_facility_type("school")
False
name: str
housing_supply: int
housing_base_price: float
amenity_score: float
facilities: list[Facility]
job_density: float = 0.0
private_supply: int = 0
private_base_price: float = 0.0
commercial_floor_area: float = 0.0
residential_floor_area: float = 0.0
productivity_A: float = 0.0
amenity_B: float = 0.0
wage_observed: float = 0.0
floor_price_observed: float = 0.0
productivity_fundamental_a: float = 0.0
amenity_fundamental_b: float = 0.0
total_floor_area: float = 0.0
has_facility_type(facility_type)[source]

Return True if this zone has at least one facility of facility_type.

Parameters:

facility_type (str) – Facility category to search for (e.g. "school", "clinic").

Return type:

bool

Returns:

True when at least one facility of that type is present.

Examples

>>> from agent_urban_planning.core.environment import Zone, Facility
>>> z = Zone(name="x", housing_supply=1, housing_base_price=1.0,
...          amenity_score=0.0)
>>> z.facilities.append(Facility(type="school", capacity=10, quality=1.0))
>>> z.has_facility_type("school")
True
get_facilities_by_type(facility_type)[source]

Return all facilities of the given type in this zone.

Parameters:

facility_type (str) – Facility category to filter on.

Return type:

list[Facility]

Returns:

A list of matching Facility instances. Empty when no match is found.

Examples

>>> from agent_urban_planning.core.environment import Zone, Facility
>>> z = Zone(name="x", housing_supply=1, housing_base_price=1.0,
...          amenity_score=0.0)
>>> z.facilities.append(Facility(type="clinic", capacity=5, quality=0.9))
>>> [f.capacity for f in z.get_facilities_by_type("clinic")]
[5]