A framework for connecting 3D geometry, physical fields and moving agents in a shared, time-dependent world. Bring together scene assets and simulation outputs, preserve their spatial and temporal meaning, and explore them through interactive visualization.
Current applications span urban environments, wind farms and rotor experiments. The same integration protocol is designed to support other settings and scales, including indoor scenes. The fourth dimension is time.
How to use
- Explore a scene. Open the website to view the published city and wind-farm demonstrations.
- Try the shared contract. The synthetic example demonstrates geometry, fields and trajectories in the unified viewer.
- Work locally. Install the framework to inspect scene configurations, serve available data and run a configured simulation pipeline.
- Add your own simulation. Export results through the integration protocol and connect them to visualization widgets.
Published scenes currently use their existing specialized viewers. The unified viewer supports protocol-based layers and local scene views; migration progress and validation scope are tracked in the implementation status.
Requirements
- Python 3.11+ for the framework CLI, validation and local server.
- A modern browser for interactive visualization.
- Scene inputs and solver dependencies for real simulation runs. GPU and Blender environments are configured separately where needed.
- Node.js for the JavaScript development checks.
A source checkout includes small protocol examples. Large scene datasets and simulation environments are managed separately.
Install
git clone https://github.com/acse-yl222/physics-grounded-4d-world-model-framework.git
cd physics-grounded-4d-world-model-framework
python3 -m venv cache/framework/venv
source cache/framework/venv/bin/activate
python -m pip install -e .
Inspect the registered scenes and start the viewer:
p4d scenes
p4d paths south_ken
p4d serve --port 8769
Open localhost:8769. When local scene runs are absent, the homepage links open the published scenes. You can also open the local synthetic example directly.
Installed packages and workspaces
python -m pip install -e . supports source development. A wheel includes the
canonical schemas, small examples and static viewers. p4d validate /path/to/manifest.json
needs no checkout or scene workspace. Other commands accept p4d --root /path/to/workspace ...;
P4D_ROOT and the legacy UWM_ROOT are also supported, in that order.
An explicit workspace must be an existing directory and can initially be empty.
p4d --root /path/to/empty-directory serve can display the bundled synthetic viewer.
storage.local.json in that workspace controls data_root and cache_root.
Code and bundled resources always come from the installed package, independently
of these paths. External historical inputs are configured in sources.local.json
or UWM_SOURCE_<NAME>; defaults use the configured scene input directory.
Install optional environments with .[birds], .[traffic], .[geometry] or
.[flow]. PyTorch/CUDA, Blender and external SCALED/Wave PDE installations have
additional platform requirements. These extras do not supply weights or city data.
Package entrypoints include python -m traffic.train and
python -m urban_geometry.birds.scripts.run_sim. Historical research scripts outside
these maintained entrypoints retain their documented environments.
Run a simulation
Inspect a scene pipeline first:
p4d run white_city --dry-run
With the scene data and solver environment available, run and retain its outputs:
p4d run --python /path/to/solver/environment/bin/python white_city --run-id my_trial --retain
Intermediate results go to cache/<scene>/pipeline/<run_id>/. Retention validates completed outputs, copies them into project/<scene>/runs/ and refuses to overwrite an existing run. The city pipeline can export a protocol bundle and register it as a scene view.
You can also validate and retain an existing export:
p4d validate /path/to/trial/manifest.json
p4d retain /path/to/completed/trial
See the results
Open the local unified viewer to select available protocol scenes and views. It supports GLB geometry, NPY fields and frame sequences, JSON metadata, and sparse recorded trajectories.
Use p4d serve to load scene data: its HTTP Range support allows NPY data to be read on demand. Layers retain their declared coordinates, units, masks and time samples; unavailable time ranges appear as missing data. The retained South Kensington traffic replay, for example, covers seconds 1–300.
Resources
The resource catalogue provides selected published geometry and simulation assets. Its companion repository organizes them by scene, type and version:
project/<scene>/<resource-type>/<version>/
Each registered resource includes file sizes, SHA-256 hashes and provenance. Some city fields and auxiliary assets remain on the framework's pages branch for compatibility. See resource management for the publication layout and compatibility paths.
Development
The repository separates reusable implementation, retained scene data and disposable workspaces:
src/
urban_geometry/ # Geometry processing and 3D agents
urban_flow/ # Physical models, solvers and flow experiments
traffic/ # Traffic training, prediction and replay
uav_routing/ # UAV ground stations, Wave PDE routes and exports
visualization/ # Viewers, widgets and data adapters
common/ # Storage, contracts, pipelines and HTTP serving
project/
south_ken/ # Scene inputs, configuration and retained results
white_city/
windfarm/
actuator_lab/
... # Further scenes such as delhi_karol_bagh and thapar_university
cache/ # Reproducible intermediates and local environments
schemas/ # Run, scene and view contracts
examples/ # Small protocol examples
For new scenes, solvers or widgets, follow the integration protocol. Widgets consume declared data layers; solvers stay in their domain modules. The architecture overview maps the packages to the run, experiment and modelling workflows. AGENTS.md and the simulation integration skill provide the corresponding agent workflow.
Core checks:
p4d validate examples/contract-v1/manifest.json
python -m unittest discover -s tests -v
node --test tests/test_*.mjs
make test-e2e # Required for every change; see docs/framework/e2e-ci.md
Keep separate backups of unpublished scene data and external originals. The local .history/ directory contains migration recovery material and must not be treated as disposable cache. The main branch holds source and small examples; pages hosts the public site and previously published assets.
Development and formatting
Use Python 3.11+ and the Node 24 version in .nvmrc. Install the pinned development tools once:
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e . -r tools/requirements-dev.txt
PUPPETEER_SKIP_DOWNLOAD=true npm ci
The same entry points run locally, in the commit hook and in CI:
make format # Apply formatting to all owned files
make format-check # Check without changing files
make lint # Ruff lint of the same Python files, without fixing them
make test # Both protocol examples, Python tests and all Node unit tests
pre-commit install # Optional: format and lint staged files, check commit messages
pre-commit run --all-files
Ruff formats Python and Notebook code cells; Prettier handles JavaScript, HTML, CSS, JSON, YAML and Markdown; Taplo handles TOML; shfmt handles shell scripts. Formatting uses a 100-column width for Python, Prettier and TOML, four-space Python/TOML indentation and two-space web/shell indentation. Markdown prose is not rewrapped. Notebook output and metadata are retained.
Ruff also lints Python with its default rule set, which includes import sorting. make lint, the commit hook and CI report findings without changing files; apply fixes deliberately with ruff check --fix <files> and review them. Frozen upstream sources, research handoffs and member code are excluded from linting, and the few project-wide exceptions are explained in the [tool.ruff.lint] section of pyproject.toml.
tools/format.py selects tracked files and new, non-ignored files, then applies the shared .prettierignore boundary and Git exclusions. Maintained legacy code, scene configuration and view files are included. Third-party vendors, .history/, cache/, scene inputs/geometry/runs, synthetic data payloads, published snapshots and recorded provenance are excluded even when tracked. The legacy asset inventory is a generated record and stays unchanged. Unsupported binary formats are never passed to a formatter. Run the unified commands rather than formatting every JSON file recursively. After changing formatting configuration or exclusions, run make format and make format-check over the whole repository.
The short end-to-end check needs Chrome and the [geometry] extra but no city assets, GPU or solver environment:
python -m pip install -e '.[geometry]'
npx puppeteer browsers install chrome
make test-e2e
It runs a generated GLB through the real CLI geometry and visualize stages, retention and view registration, then checks the retained GLB, NPY and the five example layers in the browser through the framework server. Logs, reports and screenshots stay under cache/framework/e2e/; e2e-ci.md lists what must pass. make test-browser runs only the synthetic five-layer browser check. CHROME_PATH can select an existing compatible Chrome installation. Real-city browser tests and GPU/Blender simulations require their own environments and data. The base Python suite reports tests that need torch or the flow stack as skipped; the CPU domain job runs the whole suite again with the CPU solver dependencies, so those tests run there.
Repository CI runs six jobs on every pull request (including stacked PRs), pushes to main and manual dispatch: format and Node unit tests, Python 3.11/3.12/3.14 tests with isolated wheel validation, the full suite with CPU domain dependencies, and E2E smoke. Every change must pass E2E smoke; it has no path filter or conditional skip. Tool versions are pinned, npm uses its lockfile, Actions use full commit SHAs, and the workflow has read-only repository permissions. E2E artifacts contain only the synthetic fixture's logs, report and screenshots. A repository administrator can make the job checks required for merging through branch protection or a ruleset. The separate PR title and commits check runs tools/check_commit_message.py on the title and every commit of a pull request against the format in AGENTS.md, and reruns when a title is edited; pre-commit install applies the same check as a local commit-msg hook.
The pure formatting commit is listed in .git-blame-ignore-revs. To hide that commit when investigating code history:
git blame --ignore-revs-file .git-blame-ignore-revs path/to/file.py
About
A Levistone project. Developed by the authors listed above, affiliated with Imperial College London. Module contributions are recorded in Contribution.md.
The framework began as UrbanWorldModel and now targets geometry- and physics-grounded environments across scales. p4d is the primary command; uwm and UWM_ROOT remain available for compatibility. The original project overview preserves the earlier context.
UAV routes and random flight
South Kensington now supports ground-to-ground Wave PDE routes with 30 m vertical
ascent/descent and independent random UAV animation in the integrated city viewer.
See routing code and reproduction.
