Glossary

This page defines terms specific to Pymetropolis (the pipeline, its configuration, and its demand-side data model). For terms about the METROPOLIS2 simulator itself (agent, vehicle, route, …), see the Metropolis-Core glossary.

• Activity: Action performed by a Person at a location, for some duration, between two Trips (e.g. working, shopping).
• Configuration file: TOML file passed to the pymetropolis command, defining a simulation instance: which Steps to run and with which Parameters. A configuration can also reference one or more extra-population configuration files (see Population).
• Custom Step: A Step subclass defined by a user in a Python file listed under custom_steps, loaded alongside the built-in Steps. A Custom Step whose name matches an existing Step’s name replaces it. See the Custom Steps page.
• DataFile: External, user-provided data file referenced from the configuration file through a path parameter (e.g. osm_file, synthetic_population.eqasim_output) — as opposed to a MetroFile, which Pymetropolis produces itself. Pymetropolis tracks a DataFile’s modification time, so a Step reading one re-runs automatically when the underlying file changes.
• Eqasim: External synthetic-population generation pipeline. EqasimImportStep imports its output as a Population’s Persons, Households, and Trips.
• Extra population: See Population.
• Household: Group of Persons in a synthetic population who share a home, used e.g. to draw car/motorcycle/bicycle ownership. Represented by the HouseholdsFile MetroFile.
• Main directory: Directory, set with the main_directory parameter, under which every MetroFile produced during a run is stored.
• Main population: See Population.
• MetroFile: A single file produced and/or consumed by the pipeline, stored under the main directory at a fixed path, typically as a Parquet or GeoParquet file. See the MetroFiles reference.
• MobiSurvStd: Standardized format for French Household Travel Survey data. Used, e.g., by MobiSurvStdImportStep to import surveyed Trips, and as an alternative Household Travel Survey source for Eqasim.
• Mode: Way of performing a Trip (e.g. car_driver, public_transit, walking). See the Modes page for the full list and their properties.
• Non-primary edge: See Primary edge.
• OD matrix (origin-destination matrix): Table specifying, for pairs of zones or nodes, the number of Trips between them.
• Parameter: A typed, validated value read from the configuration file (e.g. mode_choice.modes), bound to a Step. See the Parameters reference.
• Pedestrian network: Infrastructure of ways that can be walked or cycled on.
• Person: An individual in a synthetic population, member of a Household, making one or more Trips. Represented by the PersonsFile MetroFile.
• Pipeline: The full sequence of Steps that Pymetropolis determines and runs for a given configuration file, each one reading Parameters and MetroFiles and producing MetroFiles in turn.
• Population: An independent set of demand data (Persons/Households/Trips, or an OD matrix) simulated together, with its own Steps, preferences, and modes, while sharing common infrastructure (e.g. the road network) with any other population in the same run. The main population is defined directly in the main configuration file; extra populations are declared with extra_populations and each has its own configuration file and population_name. See the Multiple-demand page.
• PopulationFile: A MetroFile whose path is namespaced by population (containing a {population} placeholder, e.g. demand/{population}/trips/trips.parquet), so that every population gets its own copy.
• PopulationStep: A Step that runs once for every population in the current run, rather than once for the whole pipeline.
• Primary edge: An edge of the road network that is actually simulated by Metropolis-Core, as opposed to a non-primary (or secondary) edge, which is assumed to always be under free-flow conditions. By default every edge is primary; the road_network.secondary_types parameter can mark some edge types (e.g. residential roads) as secondary so they are excluded from simulation while still being usable for the access/egress parts of a road trip. See road_network.ensure_primary_connected too.
• Purpose: Category of activity at the origin or destination of a Trip: "home", "work", "education", "shopping", "task", "leisure", "escort", or "other".
• Road network: Infrastructure of roads that can be used by vehicles. See also the Metropolis-Core glossary for the underlying edge/node graph representation, and Primary edge for which edges are actually simulated.
• Schedule preferences: The parameters of an agent’s schedule-delay utility, penalizing starting the next Activity earlier or later than the desired time (tstar). See the Departure time page.
• Secondary edge: See Primary edge.
• Simulation area: Geographic polygon restricting where the population and road network are simulated. Represented by the SimulationAreaFile MetroFile.
• Step: A single unit of computation in the pipeline: it reads some Parameters and MetroFiles, does some work, and writes one or more MetroFiles. See the Steps reference.
• Surplus: The utility an agent obtains from the Trip/Mode choices they end up making (their maximum expected utility, given their choice models). Also called expected utility.
• Synthetic population: A set of Persons, Households, and Trips generated (e.g. by Eqasim) or resampled to represent a real population, used as a population’s demand data.
• Tour: Sequence of Trips made by a Person starting and ending at home. Represented at the tour level by the ToursFile MetroFile.
• Trip: A single journey by a Person from one activity to the next (e.g. home to work), the basic unit of demand generated for a population. Not to be confused with a road/virtual trip in the Metropolis-Core glossary, which is the corresponding simulated movement on the network.
• tstar (t*): Desired time at which a Person wants to start their next Activity. Central to schedule preferences: starting earlier or later than tstar is penalized in an agent’s departure-time-choice utility.
• Urban type: Classification of a location’s surroundings by density/urbanization, e.g. "central_city", "suburb", "isolated_city", or "outside_urban_unit" for France. Used, e.g., to condition Mode preferences or trip-purpose matching on how urban an area is.
• Value of time (alpha): Parameter giving the monetary penalty per hour spent traveling by a given Mode, i.e. how costly agents perceive travel time to be.
• Zone: Geographic area used to aggregate origins/destinations for an OD matrix or for analyzing results at different spatial scales. Pymetropolis supports up to five hierarchical zone levels (level1 to level5) — see the Zones page.