agent_urban_planning.Environment

class Environment(zones, transport, ahlfeldt_params=None, transport_matrix=None, transport_matrix_index=None)

Bases: object

Spatial environment holding zones and transportation network.

The geographic backbone of a simulation. Holds the per-zone properties (housing supply, base prices, amenities, facilities, and Ahlfeldt fundamentals where applicable) and a graph-based TransportNetwork. Optionally also carries an Ahlfeldt-style dense travel-time matrix keyed by zone name when the scenario is a Berlin replication. The edge-list TransportNetwork remains the primary interface; transport_matrix is a zero-copy alternative used by AhlfeldtUtilityEngine for vectorized distance lookups.

Parameters:

• zones (list[Zone]) – List of Zone instances comprising the simulation geography.

• transport (TransportNetwork) – A TransportNetwork describing edges between zones.

• ahlfeldt_params (Optional[AhlfeldtParams]) – Optional AhlfeldtParams describing the structural elasticities of the Berlin model. Present only for Berlin/Ahlfeldt scenarios.

• transport_matrix (Optional[ndarray]) – Optional dense (N, N) travel-time matrix in zone-name order.

• transport_matrix_index (Optional[list[str]]) – Zone names corresponding to the rows / columns of transport_matrix.

Examples

>>> import agent_urban_planning as aup
>>> # Typically built from a scenario YAML, not constructed manually:
>>> # env = aup.Environment.from_config(scenario)
>>> # env.travel_time("Mitte", "Charlottenburg")

classmethod from_config(config)

Build an Environment from a parsed ScenarioConfig.

Materializes per-zone records (including Ahlfeldt fundamentals and synthesized total-floor-area where missing), constructs the TransportNetwork from edge records, and optionally loads a dense travel-time matrix from config.transport_matrix_path when present.

Parameters:

config (ScenarioConfig) – A loaded ScenarioConfig with zones, transport, and optional ahlfeldt_params / transport_matrix_path fields.

Return type:

Environment

Returns:

A fully wired Environment ready for use as the base_env of a SimulationEngine.

Raises:

ValueError – If transport_matrix_path is set but the resulting matrix shape does not match len(zones).

Examples

>>> import agent_urban_planning as aup
>>> # scenario = aup.data.builtin.load("singapore_real_v2")
>>> # env = aup.Environment.from_config(scenario)

travel_time(origin, destination)

Return the travel time in minutes between two zones.

Uses the dense transport_matrix when available (Berlin scenarios); falls back to the edge-list TransportNetwork otherwise. Returns float('inf') if no route exists.

Parameters:

• origin (str) – Source zone name.

• destination (str) – Destination zone name.

Return type:

float

Returns:

Travel time in minutes (float('inf') if disconnected).

Examples

>>> import agent_urban_planning as aup
>>> # env = aup.Environment.from_config(scenario)
>>> # env.travel_time("Mitte", "Mitte")
0.0

get_zone(name)

Look up a zone by name.

Parameters:

name (str) – Zone name (must be present in this environment).

Return type:

Zone

Returns:

The Zone with that name.

Raises:

KeyError – If name is not a known zone in this environment.

Examples

>>> import agent_urban_planning as aup
>>> # env = aup.Environment.from_config(scenario)
>>> # zone = env.get_zone("Mitte")
>>> # zone.housing_supply

property zone_names: list[str]

apply_policy(policy)

Apply a policy and return a new Environment with the changes baked in.

Does not mutate the original environment. Adds new Facility instances to zones that receive facility investments, and updates transport routes (in both directions) for transit investments.

Parameters:

policy (PolicyConfig) – A PolicyConfig describing facility and transit investments.

Return type:

Environment

Returns:

A new Environment instance with the policy’s investments applied. The original environment is unchanged.

Examples

>>> import agent_urban_planning as aup
>>> # env = aup.Environment.from_config(scenario)
>>> # env_after = env.apply_policy(policy)