SimWrapper Extension#

SimWrapper is a browser-based, client-side tool for exploring transport simulation outputs. It accepts simple YAML configuration files describing dashboards of maps, tables and charts. Nothing is uploaded to the internet, everything is kept local. The application is open-source and designed so that non-coding stakeholders can open a dashboard in their browser and interact with results.

The SimWrapper extension generates portable dashboard configuration for visualising an AequilibraE project with the simwrapper.app or explore.outerloop.io. At the time of writing Outer Loop is hosting a preview version of SimWrapper while the required changes are being unstreamed.

You can view an example dashboard at explore.outerloop.io by selecting “Chicago AequilibraE Example” from the Example Dashboards section.

Usage#

  • The generator is implemented as aequilibrae.utils.simwrapper.generate_simwrapper_config.SimwrapperConfigGenerator.

  • A CLI entry point is installed as the aeq-sim script (registered in the package entry points).

  • Output: a dashboard.yaml file and data files (CSV and Vega-Lite JSON) written into the chosen <output_dir>. A data subfolder named simwrapper_data/ is created under the output directory for CSV and Vega-Lite spec files.

Quickstart — CLI#

$ aeq-sim --project /path/to/project --output-dir simwrapper

If you omit --project, the CLI defaults to the current directory (.). If you omit --output-dir, the CLI will write to a simwrapper folder by default.

CLI options

  • --project / -p: project root (folder containing project_database.sqlite).

  • --output-dir / -o: output directory (created inside the project).

  • --max-results-tables: limits the number of results scenarios included. When not provided, the generator defaults to three results.

  • --results-tables: explicit list of results table names to include (space-separated, e.g. --results-tables table_1 table_2). When not provided, defaults to the first max-results-tables tables.

  • --centroid-link-types: explicit link-type names considered centroid connectors (space-separated, e.g. --centroid-link-types centroid connector).

  • --quiet / -q: suppress informational output.

Note

output_dir must reside inside the project directory. Absolute paths outside the project are rejected.

Quickstart — Python API#

from aequilibrae.project import Project
from aequilibrae.utils.simwrapper.generate_simwrapper_config import SimwrapperConfigGenerator

prj = Project()
prj.open('/path/to/project')

gen = SimwrapperConfigGenerator(prj, output_dir='simwrapper', max_results_tables=3)
gen.write_yamls()

The constructor accepts the same configuration knobs available in the CLI (output_dir, max_results_tables, results_tables, centroid_link_types). output_dir must be located inside the project directory; absolute paths outside the project will raise a ValueError.

What the generator writes#

All generated files are written into the chosen output directory (<output_dir>).

  • <output_dir>/dashboard.yaml — the SimWrapper dashboard configuration.

  • Data files referenced by the dashboard (CSV and Vega-Lite JSON specs), for example assignment convergence CSVs and assignment_convergence.vega.json.

The generator instance exposes a generated_files mapping after writing the outputs. This dict-like object maps descriptive keys (for example "dashboard" or "assignment_convergence") to pathlib.Path objects pointing to the written files. It is useful for programmatic inspection or other downstream processing.

Viewing the dashboard#

Warning

SimWrapper requires a Chromium-based browser (such as Google Chrome or Microsoft Edge) to access local files.

  1. Open simwrapper.app or explore.outerloop.io in your browser.

  2. Select “view local files” then select the project folder (the one containing project_database.sqlite)

Notes#

  • The YAML dashboard references data files using a relative path, so the dashboard may be shared by sharing the entire project.

  • If your project contains many results scenarios, use --max-results-tables or results_tables to control which scenarios are included; the generator attempts to pick the most recent scenarios automatically when not specified. Selection is based on the timestamp field when present (most recent first), with a fallback ordering by table_name when timestamps are not available. When centroid link types are not specified the generator attempts to infer them from the project’s link types (names containing “centroid” or “connector”) or from the links table.

  • If you do not want any results scenarios included, pass --max-results-tables 0 to the CLI or max_results_tables=0 to the Python API; the generator will omit results panels from the dashboard in that case.