Examples
The endpoints are described on the API page.
curl
BASE=https://aij.eddy3d.com/api # newest release; append /3.2.1 to pin
curl -s $BASE/index.json | jq '.versions, (.endpoints[].path)'
curl -s $BASE/cases.json | jq '.cases[] | {id, title, counts, engines}'
curl -s $BASE/cases/B.json | jq '{frame, units, known_issues}'
curl -s $BASE/validation.json | jq '.cases[] | {case, engines: [.engines[] | {engine, status}]}'
# Downloads: take the URL from the document, then check the SHA-256.
url=$(curl -s $BASE/cases/B.json | jq -r '.points.csv.url')
sha=$(curl -s $BASE/cases/B.json | jq -r '.points.csv.sha256')
curl -s -o caseB.csv "$url" && echo "$sha caseB.csv" | sha256sum -c -
curl -s $BASE/cases/D/geometry.json | jq '.files[0].boxes | length' # 83
curl -s $BASE/cases/C/validation.json | jq '.results[] | {run_id, headline}'
curl -s -o aij_geometry.zip "$(curl -s $BASE/geometry.json | jq -r '.archive.url')"
Python
Standard library only. This script runs as written against the live API.
import csv, hashlib, io, json, statistics, urllib.request
# The newest release. To pin the analysis to one release, append its number (any in /api/versions.json): ".../api/3.2.1".
BASE = "https://aij.eddy3d.com/api"
def fetch(url):
# A descriptive User-Agent: the site's CDN rejects urllib's default one (see Clients on the API page).
req = urllib.request.Request(url, headers={"User-Agent": "aij-uwe-example/1.0"})
with urllib.request.urlopen(req) as r:
return r.read()
def get_json(path):
return json.loads(fetch(f"{BASE}/{path}"))
def download(d):
"""Fetch a download object and check it arrived intact."""
body = fetch(d["url"])
assert hashlib.sha256(body).hexdigest() == d["sha256"], f"{d['path']} is corrupt or stale"
return body
index = get_json("index.json")
print(index["versions"]) # API version, data version (a SHA-256 of the data)
case = get_json("cases/B.json")
print(case["frame"]["x"]) # read the frame and the known issues BEFORE the numbers
print(case["known_issues"][0][:80])
pts = get_json("cases/B/points.json")
U_H = case["configuration"]["U_H_m_s"]
centre = [p for p in pts["points"] if abs(p["y"]) < 1e-9 and p["U"] is not None]
print(len(centre), "centre-plane points; U/U_H at the first:", round(centre[0]["U"] / U_H, 3))
rows = list(csv.DictReader(io.StringIO(download(case["points"]["csv"]).decode())))
print(len(rows), "rows in points.csv; columns", list(rows[0]))
geom = get_json("cases/D/geometry.json")
print(len(geom["files"][0]["boxes"]), "boxes in Case D") # boxes where the geometry is boxes: no STL parsing
stl = download(geom["files"][0]) # ...or the STL itself, checked against its SHA-256
summary = get_json("validation.json") # every case and engine in one table
for c in summary["cases"]:
print(c["case"], {e["engine"]: e["status"] for e in c["engines"]})
# Recompute a published score from the per-point pairs behind it.
val = get_json("cases/A/validation.json")
run = next(r for r in val["results"] if r["run_id"] == "A.openfoam12-realizableKE")
pairs = list(csv.DictReader(io.StringIO(download(run["pairs"]).decode())))
R = statistics.correlation([float(p["U_meas"]) for p in pairs], [float(p["U_model"]) for p in pairs])
print("R of U/U_H recomputed:", round(R, 4), "published:", round(run["scores"]["velocity.U"]["R"], 4))
The last line prints R of U/U_H recomputed: 0.9548 published: 0.9548.
Geometry conventions
Every STL is in metres. units in geometry.json says whether the file is at model scale (what the tunnel measured) or full scale; frame.origin in the case document names the origin.
| Cases | Scale | Origin | \(+x\) |
|---|---|---|---|
| A, B | model | building centre | along the wind at \(\mathrm{WD} = 0\) |
| C, D | model | array centre | along the wind at \(\mathrm{WD} = 0\) |
| E | full (as its 3dm and workbook) | centre of the reproduced area | east (\(+y\) north) |
| F | full (scaled up from 1:800) | centre of the reproduced area | east (\(+y\) north) |
| G | full (field) | leeward face of the belt | downwind |
| H, J | model | leeward face of the building | along the wind at \(\mathrm{WD} = 0\) |
| I | model | cube centre | along the wind at \(\mathrm{WD} = 0\) |
| K, L | model | a cube of the array | along the wind at \(\mathrm{WD} = 0\) |
| M | full (scaled up from 1:600) | turntable centre | north (\(+y\) west) |
Nomenclature: symbols, columns and scores
Geometry, reference scales and release
- \(H\), \(b\), \(D\) (m) — height of the building, cube, tower or tree belt; width of the building; edge of the cubes of Case C: the lengths the cases are drawn and normalised by
- \(U_H\) (m/s) — reference speed: the mean approach-flow speed at the height \(H\) (each Data page gives the value used)
- \(U_R\), \(H_R\), \(Z_R\) (m/s, m) — reference speed and height of a workbook: Case E, \(U_R\) at \(Z_R\) = 250 m full scale (1 m in the model); Case M, \(U_R\) and \(H_R\) at the reference point of the tunnel and of each field run
- \(U_{\mathrm{ref}}\), \(L_{\mathrm{ref}}\) (m/s, m) — reference speed and length of a case’s normalisation: \(U_H\) and \(H\) (\(U_R\) and \(H_R\) in Case M); for the velocity ratios the approach speed at 15.9 m (Case E) or at 500 m (Case F)
- \(U_b\) (m/s) — Case G: mean approach-flow speed at 9 m, the normalisation of its approach-flow table
- \(q\), \(c_{\mathrm{gas}}\) (m³/s, ppm) — tracer release of the experiment: volume flow of the released gas, and its tracer content (\(10^6\) ppm when pure); \(Q\) is the source strength given to a solve
- \(R_b\) (dimensionless) — bulk Richardson number of the heated-floor cases J and L (negative: unstable stratification)
- \(\mathrm{Re_H}\), \(\mathrm{Re_D}\) (dimensionless) — Reynolds numbers \(U_H H/\nu\) and \(U_H D/\nu\) (\(\nu\): kinematic viscosity of air)
- \(u_\ast\), \(z_0\), \(\kappa\) (m/s, mm, dimensionless) — friction velocity and roughness length of the log law fitted to the approach flow, and the von Kármán constant (0.41)
- \(\mathrm{WD}\) (column
wind_direction_deg; °) — wind direction (each frame says how it is counted); \(\mathrm{WD_R}\) is the mean direction of a field run at its reference point (Case M) - \(x\), \(y\), \(z\) (columns
x,y,z; m) — coordinates in the case’s frame (\(+x\), \(+y\) and \(+z\) are the positive directions; each Data page says which way \(+x\) points), \(z\) up from the floor of the tunnel or from the ground - \(\mathrm{d}x\) (m) — lattice spacing of the OpenLB and FluidX3D runs, in metres or as a fraction of \(H\) (\(H/64\))
- \(L_r\) (m) — reattachment length behind the building, read from a wake line at ground level; reported as \(L_r/H\)
Velocity and turbulence
- \(U\), \(V\), \(W\) (columns
U,V,W; m/s) — mean velocity along \(+x\), \(+y\), \(+z\); \(V\) is positive toward \(+y\) in every case - \(\lvert\mathbf{U}\rvert\) (m/s) — magnitude of the mean velocity vector, \(\sqrt{U^2+V^2+W^2}\)
- \(V_{\mathrm{s}}\) (column
Vs; m/s) — mean omnidirectional scalar speed of a thermistor (never a vector magnitude) - \(\overline{u'u'}\), \(\overline{v'v'}\), \(\overline{w'w'}\) (columns
uu,vv,ww; m²/s²) — velocity variances (overbar: time average, prime: fluctuation about it) - \(\overline{u'v'}\), \(\overline{u'w'}\), \(\overline{v'w'}\) (columns
uv,uw,vw; m²/s²) — Reynolds shear stresses - \(k = \tfrac{1}{2}\left(\overline{u'u'}+\overline{v'v'}+\overline{w'w'}\right)\) (column
k; m²/s²) — turbulent kinetic energy - \(U/U_{\mathrm{ref}}\) (column
velocity_ratio; dimensionless) — mean speed over the case’s reference speed (\(V_{\mathrm{s}}/U_{\mathrm{ref}}\) for a thermistor) - \(\sigma_{U/U_{\mathrm{ref}}}\) (column
velocity_ratio_sd; dimensionless) — standard deviation ofvelocity_ratioover the observations behind a field value (Case F) - \(k/U_{\mathrm{ref}}^2\) (column
k_ratio; dimensionless) — turbulent kinetic energy over the square of the reference speed, where only normalised values are published (Case G)
Concentration and temperature
- \(C\) (column
C; ppm) — mean tracer-gas concentration as published (volume fraction \(\times 10^6\) of the released gas diluted in air) - \(c_{\mathrm{rms}}\) (column
c_rms; ppm) — root mean square of the concentration fluctuation - \(c_0\) (ppm) — reference concentration, defined for each case on its Data page: \(c_0 = \dfrac{c_{\mathrm{gas}}\thinspace q}{U_H H^2}\) (\(U_R H_R^2\) in the denominator in Case M)
- \(c^\ast\) (column
concentration_ratio; dimensionless) — dimensionless concentration \(c^\ast = C/c_0\); the value of a solve is \(c\thinspace U_H H^2/Q\) for its mean concentration \(c\) and its source strength \(Q\) - \(\mathrm{Sc_t}\) (dimensionless) — turbulent Schmidt number of a solve (0.3, 0.5 and 0.7)
- \(T\), \(T_{\mathrm{rms}}\) (columns
T,T_rms; °C, K) — mean air temperature as published (Cases J and L) and the root mean square of its fluctuation - \(\overline{u'c'}\), \(\overline{v'c'}\), \(\overline{w'c'}\) (columns
uc,vc,wc; ppm·m/s) — turbulent concentration fluxes - \(\overline{u'\theta'}\), \(\overline{v'\theta'}\), \(\overline{w'\theta'}\) (columns
uT,vT,wT; K·m/s) — turbulent heat fluxes (\(\theta'\): the temperature fluctuation) - \(\theta = \dfrac{T_f - T}{T_f - T_H}\) (dimensionless) — floor-referenced temperature the solves of Cases J and L are scored on: 0 at the floor, 1 in the approach air at \(H\); \(T_f\) is the floor temperature and \(T_H\) the temperature of the approach flow at \(H\)
Scores
- \(n\) — number of pairs of a measured value \(o_i\) and a modelled value \(p_i\) at one point
- \(R\) — Pearson correlation coefficient of the pairs
- \(R^2\) — square of \(R\): share of the measured variance a linear fit to the model explains
- \(\mathrm{FAC2}\) — fraction of pairs with \(0.5 \le p_i/o_i \le 2\)
- \(\mathrm{FB}\) — fractional bias \(2(\overline{o}-\overline{p})/(\overline{o}+\overline{p})\), positive when the model is low
- \(\mathrm{HR}\) (hit rate) — fraction of pairs with \(\lvert p_i-o_i\rvert/\lvert o_i\rvert \le \delta_{\mathrm{rel}}\) or \(\lvert p_i-o_i\rvert \le \delta_{\mathrm{abs}}\), where \(\delta_{\mathrm{rel}} = 0.25\) and \(\delta_{\mathrm{abs}} = 0.05\thinspace U_H\) for a velocity component
- \(\mathrm{NMSE} = \dfrac{\overline{(o-p)^2}}{\overline{o}\thinspace \overline{p}}\) — normalised mean square error
- \(\mathrm{NAD} = \dfrac{\overline{\lvert o-p\rvert}}{\overline{o}+\overline{p}}\) — normalised absolute difference
- \(\mathrm{MG} = \exp\overline{(\ln o-\ln p)}\) — geometric mean bias
- \(\mathrm{VG} = \exp\overline{(\ln o-\ln p)^2}\) — geometric variance
- The ratio of \(\mathrm{FAC2}\) keeps its sign, so a model of the other sign than the measurement is a miss; \(\mathrm{FB}\), \(\mathrm{NMSE}\) and \(\mathrm{NAD}\) divide by the means, so they are undefined (shown as —) for a signed component unless the measured and the modelled mean are both positive
- VDI 3783-9 calls the hit rate \(q\) and the tolerances \(D\) and \(W\); on this site those letters keep their other meanings (\(q\) the tracer release rate, \(D\) the block size of Case C, \(W\) the vertical velocity)
- The detection limit of a concentration is one value per case, \(10^{-3}\) of the largest measured value. It sets \(\delta_{\mathrm{abs}}\) of the hit rate and the both-below rule of \(\mathrm{FAC2}\), and floors the values in \(\mathrm{MG}\) and \(\mathrm{VG}\).
- The scores \(\mathrm{FB}\), \(\mathrm{FAC2}\), \(\mathrm{NMSE}\), \(\mathrm{NAD}\), \(\mathrm{MG}\) and \(\mathrm{VG}\) follow Chang & Hanna (2004); the hit rate follows VDI 3783-9.
Quantities scored
- \(U\), \(V\) and \(W\) (mean velocity components) over \(U_H\)
- \(k\) (turbulent kinetic energy) over \(U_H^2\)
- the speed \(\lvert\mathbf{U}\rvert\) and \(\sqrt{\lvert\mathbf{U}\rvert^2+2k}\), against a thermistor’s \(V_{\mathrm{s}}\)
- \(c^\ast = C/c_0\) (dimensionless concentration) at turbulent Schmidt numbers \(\mathrm{Sc_t}\) of 0.3, 0.5 and 0.7
- \(\theta\) (floor-referenced temperature)
E and F keep their geographic frame, and their wind directions are meteorological: the direction the wind comes from, N = 0°, clockwise. In F and M the heights are above the tunnel floor, not the ground.
The files. Outward normals, LF line endings, one solid per file. Every file is watertight: each body is closed, consistently wound and positive in volume. Where two bodies touch along an edge (11 edges in E) the edge is listed under body_contacts in geometry.json. F and M are one body each, closed with a 1 m base slab below \(z = 0\).
The checks. The build checks every STL: triangle count, bodies, boundary edges, winding, signed volume, and the bounding box against the stated dimensions. scripts/check_geometry.py parses the written files again and fails on any open or inconsistently wound body. validation/render_geometry.py draws each file from the same code that writes it; those are the renders on the case pages.