Quickstart - First local run

This page shows the main first run for Mobility.

The goal is to:

  • define a small study area,

  • build a synthetic population,

  • simulate weekday trips for that population,

  • inspect a first set of outputs.

The code on this page follows the maintained example script in examples/quickstart-fr.py.

Before you start

Install Mobility first by following the installation page.

This quickstart assumes that your Mobility data folders are already configured. The example script reads them from the environment variables:

  • MOBILITY_PACKAGE_DATA_FOLDER

  • MOBILITY_PROJECT_DATA_FOLDER

If you prefer, you can also call mobility.set_params() with explicit paths.

What this example does

The example uses:

  • Limoges, France, with a 10 km radius, to use the smaller Limousin OSM extract,

  • the French EMP mobility survey,

  • a synthetic population of 1000 people,

  • three transport modes: car, walk, and bicycle,

  • three activities: home, work, and other.

It then computes weekday trip plans, global metrics, and a first origin-destination flow plot.

Complete example

import os
import dotenv
import mobility

dotenv.load_dotenv()

mobility.set_params(
    package_data_folder_path=os.environ["MOBILITY_PACKAGE_DATA_FOLDER"],
    project_data_folder_path=os.environ["MOBILITY_PROJECT_DATA_FOLDER"]
)

# Using Limoges and a limited radius to reuse the smaller Limousin OSM extract
transport_zones = mobility.TransportZones("fr-87085", radius=10.0)

# Using EMP, the latest national mobility survey for France
survey = mobility.EMPMobilitySurvey()

# Creating a synthetic population of 1000 for the area
population = mobility.Population(transport_zones, sample_size=1000)

# Simulating trips for this population for car, walk, bicycle
population_trips = mobility.PopulationGroupDayTrips(
    population=population,
    modes=[
        mobility.CarMode(transport_zones),
        mobility.WalkMode(transport_zones),
        mobility.BicycleMode(transport_zones),
    ],
    activities=[
        mobility.HomeActivity(),
        mobility.WorkActivity(),
        mobility.OtherActivity(population=population),
    ],
    surveys=[survey],
    parameters=mobility.GroupDayTripsParameters(
        run=mobility.GroupDayTripsRunParameters(n_iterations=1),
        mode_sequences=mobility.GroupDayTripsModeSequenceParameters(
            mode_sequence_search_parallel=False,
        ),
    ),
)

# You can get weekday plan steps to inspect them
weekday_run = population_trips.run("weekday")
weekday_plan_steps = weekday_run.get()["plan_steps"].collect()

# You can compute global metrics for weekday trips
global_metrics = weekday_run.results().metrics.aggregate()

# You can plot weekday OD flows, with labels for prominent cities
weekday_results = weekday_run.results()
labels = weekday_results.metrics.get_prominent_cities()
weekday_results.metrics.plot_od_flows(labels=labels)

# You can get a report of the parameters used in the model
report = weekday_run.parameters_dataframe()

Reading the example

1. Configure Mobility

mobility.set_params(...) tells Mobility where to store shared datasets and project-specific datasets.

On a first run, this step can also trigger data preparation and R package setup depending on your environment.

2. Define the study area

transport_zones = mobility.TransportZones("fr-87085", radius=10.0)

This creates the study area around Limoges and builds the transport-zone input used by the rest of the workflow.

3. Build the population and model inputs

survey = mobility.EMPMobilitySurvey()
population = mobility.Population(transport_zones, sample_size=1000)

The survey provides observed mobility behaviour patterns. The synthetic population provides the local population that will be simulated.

4. Simulate weekday trips

population_trips = mobility.PopulationGroupDayTrips(
    population=population,
    modes=[
        mobility.CarMode(transport_zones),
        mobility.WalkMode(transport_zones),
        mobility.BicycleMode(transport_zones),
    ],
    activities=[
        mobility.HomeActivity(),
        mobility.WorkActivity(),
        mobility.OtherActivity(population=population),
    ],
    surveys=[survey],
    parameters=mobility.GroupDayTripsParameters(
        run=mobility.GroupDayTripsRunParameters(n_iterations=1),
        mode_sequences=mobility.GroupDayTripsModeSequenceParameters(
            mode_sequence_search_parallel=False,
        ),
    ),
)

PopulationGroupDayTrips is the main workflow object in this quickstart. It combines:

  • a population,

  • available transport modes,

  • daily activities,

  • survey data,

  • model parameters.

5. Inspect the outputs

weekday_run = population_trips.run("weekday")
weekday_plan_steps = weekday_run.get()["plan_steps"].collect()
global_metrics = weekday_run.results().metrics.aggregate()
weekday_results = weekday_run.results()
report = weekday_run.parameters_dataframe()

These outputs are useful for a first check:

  • weekday_plan_steps gives access to simulated weekday trip-plan steps,

  • global_metrics provides aggregated indicators,

  • weekday_results gives access to result plots and summaries,

  • report lists the parameters used for the run.

What to expect

A successful run should give you:

  • a dataframe-like table of weekday plan steps,

  • aggregated weekday indicators,

  • an origin-destination flow plot,

  • a parameter report for traceability.

The first execution can take noticeably longer than later ones because Mobility may need to prepare local data and dependencies. This example uses the same Limousin OSM extract as the tests, so later runs can reuse the cache.

Common first-run issues

Missing environment variables

If MOBILITY_PACKAGE_DATA_FOLDER or MOBILITY_PROJECT_DATA_FOLDER are not defined, the example script will fail before the model starts.

In that case, either:

  • define these variables in your environment or .env file,

  • or replace the set_params call with explicit folder paths.

Long setup time

The first run can be slow because Mobility may download, prepare, or cache data, and may also install required R packages.

Windows and R package installation

If R package installation fails behind a proxy, see the installation page for the Windows-specific workaround using r_packages_download_method="wininet".

Next steps

After this first run, the next useful pages are:

  • transport zones,

  • transport modes,

  • trips,

  • carbon computation and scenario analysis.