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:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
