sreda-ml / README.md
Azatyt's picture
Sreda ML 0.6.1: model, card, licence and example
b6f453a verified
|
Raw History Blame Contribute Delete
8.33 kB
metadata
license: apache-2.0
library_name: onnx
pipeline_tag: image-to-image
tags:
  - urban-wind
  - pedestrian-wind
  - wind-comfort
  - cfd
  - lattice-boltzmann
  - surrogate-model
  - u-net
  - onnx

Sreda ML 0.6.1: pedestrian-level wind from building footprints

Sreda ML predicts the mean wind speed 1.75 m above the ground around buildings from their footprints and heights. It is a neural surrogate of the Sreda lattice Boltzmann solver (D3Q27, cumulant collision, large eddy simulation): it was trained on solver results for real and synthetic city blocks and answers in one to two seconds per 150 × 150 m window on a laptop, where the solver needs from tens of minutes to a few hours on a desktop GPU.

Status: preview. Version 0.6.1 did not pass its own acceptance test, written down before training (details in Evaluation). Use it for early design studies and for comparing options. Do not use it to approve a design or to certify wind comfort; check important decisions with a full simulation or a wind tunnel test.

Quick start

pip install numpy onnxruntime
python sreda_ml_example.py model.onnx 270 5

sreda_ml_example.py builds the model inputs from building footprints exactly as the Sreda web app does (checked bit for bit against the app on test scenes), runs the model and returns K on a 0.75 m grid with the x, y coordinates of every cell. Wind speed in m/s at 1.75 m: K × 0.494 × U10, where U10 is the wind speed at 10 m.

What the model predicts

K = ⟨|U|⟩ / U_in: the time-averaged wind speed at 1.75 m divided by the speed of the undisturbed inflow at the same height. The inflow is a logarithmic profile with roughness length z0 = 0.5 m, so U_in(1.75 m) = 0.494 U10. Neutral atmosphere, flat ground, one wind direction per prediction, mean speed only (no gusts).

Inputs and output

All rasters are in wind axes: columns run downstream, rows run across the flow (the downstream axis turned by +90°). Cell size 0.75 m. Batch of two: the frame and its mirror (rows reversed); the prediction is the mean of the first output and the second output with its rows reversed back.

Tensor Shape Content
frames float32 [2, 3, 288, 352] 216 m across × 264 m along the wind, from 96 m upwind to 18 m downwind of the window and 33 m to each side. Channels: building mask; building height / 30 m; signed distance to the nearest wall / 10 m, clipped to [−2, 5], negative inside buildings
ctx float32 [2, 3, 100, 88] Surroundings on a 6 m grid around the window centre: 435 m upwind to 93 m downwind, ±300 m across. Channels: built fraction; mean height of the built part / 30 m; maximum height / 30 m
k_ped float32 [2, 288, 352] K over the frame; valid only in the 150 × 150 m window, rows 44 to 243 and columns 128 to 327

Sites larger than one window: windows on a 120 m grid, blended with weights that fall towards the window edges (implemented in the example). Buildings standing on the ground only; bridges and raised volumes are not seen.

Ensemble of 3 U-Nets (seeds 0, 1, 2), 18.1 M parameters, ONNX opset 17, 72.8 MB. One call (one window, frame and mirror) takes about 1.5 s on a laptop CPU with onnxruntime.

Training data

Labels come from the Sreda solver: flat ground, 6 m base grid with local refinement to 0.75 m near buildings and at pedestrian height in the 150 m window, turbulent logarithmic inflow (z0 = 0.5 m, 5 m/s at 10 m), mean speed averaged over the simulated time. One wind direction per scene. Part of the labels were computed by a CUDA port of the same solver; it passed a calibration against the WebGPU solver within seed-to-seed noise before its labels were used.

Source Scenes Data licence
Synthetic building arrays generated by Sreda 312 Own data
Japanese cities, 3D city models of Project PLATEAU 110 Project PLATEAU, MLIT Japan (PLATEAU terms of use, compatible with CC BY 4.0)
Cities of Russia and Belarus, buildings from OpenStreetMap 300 OpenStreetMap contributors (ODbL 1.0)
European cities: Berlin, Amsterdam, Rotterdam, Paris 104 Berlin LoD2 (dl-de/zero-2-0), 3DBAG by tudelft3d and 3DGI (CC BY 4.0), IGN BD TOPO (Licence Ouverte 2.0)
Total 826

Heights of Russian and Belarusian buildings are OpenStreetMap levels × 3 m; sites were taken where heights are known for at least 98 % of the built area. Test cities and test sites were never used in training.

Evaluation

Correlation coefficient r of K between the model and the Sreda solver over the whole window, averaged over scenes; version 0.6.1 next to version 0.6 on the same scenes.

Test set (not in training) Scenes 0.6.1 0.6
Cities of Kazakhstan, Belarus and Russia: Astana, Minsk, Yekaterinburg 18 0.831 0.829
· high-rise 3 0.824 0.798
· historic centres 3 0.839 0.835
· low-rise 3 0.888 0.879
· microdistricts (large-panel housing estates) 3 0.832 0.846
· mid-rise 3 0.705 0.716
· mixed 3 0.896 0.902
· Astana 6 0.797 0.789
· Minsk 6 0.870 0.878
· Yekaterinburg 6 0.825 0.821
Japanese cities held out from training 18 0.881 0.882
· high-rise 4 0.851 0.851
· low-rise, low density 4 0.913 0.914
· mid-rise 5 0.853 0.862
· blocks similar to the AIJ Niigata district 5 0.907 0.904
Osaka 10 0.884 0.876
· high-rise 2 0.818 0.796
· low-rise, low density 2 0.893 0.888
· mid-rise 3 0.890 0.884
· blocks similar to the AIJ Niigata district 3 0.916 0.914

Against wind-tunnel measurements of the Architectural Institute of Japan (AIJ benchmark cases): correlation coefficient C.C. of the speed ratio at the measurement points.

Case 0.6.1 0.6
Niigata (AIJ Case E), wind W 0.868 0.869
Niigata (AIJ Case E), wind NNE 0.665 0.632
AIJ Case C, 0H, 0° 0.954 0.963
AIJ Case C, 0H, 22.5° 0.896 0.909
AIJ Case C, 0H, 45° 0.915 0.901
AIJ Case C, 1H, 0° 0.910 0.909
AIJ Case C, 1H, 22.5° 0.909 0.898
AIJ Case C, 1H, 45° 0.891 0.893
AIJ Case C, 2H, 0° 0.880 0.870
AIJ Case C, 2H, 22.5° 0.806 0.774
AIJ Case C, 2H, 45° 0.911 0.915
AIJ Case D, 0° 0.859 0.859
AIJ Case D, 22.5° 0.869 0.863
AIJ Case D, 45° 0.873 0.868

Acceptance test of this version, written down before training:

  • Not passed. mean r on the test cities 0.831 is below 0.87; Astana 0.797 is below 0.80; mid-rise 0.705 is below 0.80; gain over 0.6 on the test cities +0.001, needed +0.02; AIJ Case C, 0H, 0°: scatter error S.E. 0.130 against 0.111 of 0.6 (allowed up to 1.1 times); AIJ Case C, 1H, 0°: scatter error S.E. 0.129 against 0.111 of 0.6 (allowed up to 1.1 times); Osaka: below 0.83: high-rise 0.818.

Limitations

  • Buildings only: no terrain, trees or water; ground is flat.
  • Weakest in high-rise and dense mid-rise districts; towers above 133 m were not in the training data.
  • Mean speed at 1.75 m only; no gusts, turbulence intensity or comfort classes.
  • Heights from OpenStreetMap levels carry their own errors; the model cannot correct its input.

Licence and attribution

The model weights and the example code are released under the Apache License 2.0. The training labels were computed on building data from:

  • © OpenStreetMap contributors. Contains information from OpenStreetMap, which is made available under the Open Database License (ODbL).
  • 3D city models of Project PLATEAU, Ministry of Land, Infrastructure, Transport and Tourism of Japan (MLIT); terms compatible with CC BY 4.0.
  • 3DBAG by tudelft3d and 3DGI, CC BY 4.0.
  • IGN, BD TOPO, Licence Ouverte 2.0.
  • Geoportal Berlin, 3D building models LoD2, dl-de/zero-2-0.
  • Copernicus DEM GLO-30 (used to select flat sites): © DLR e.V. 2010-2014 and © Airbus Defence and Space GmbH 2014-2018 provided under COPERNICUS by the European Union and ESA; all rights reserved.

AIJ wind tunnel data were used only to evaluate the model and are not distributed here.

Links

SHA-256 of model.onnx: 0a4f27e3b83f22ec108a4a078ade7a51fbf6e7b4f5f0c6256ed5402f90c035b3