diff --git a/docs/README.md b/docs/README.md index 74af6e3..954fb0d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -25,6 +25,10 @@ historical branch scar. - `tsr-inspired-taa-spec.md`: temporal resolve design and guide-buffer intent. - `stochastic-transparent-surface-pipeline.md`: density/extinction and transparent field rendering notes. +- `planetary-flow-organ.md`: architecture and ownership map for reusable + cube-sphere stochastic ocean/atmosphere flow fields. +- `planetary-flow-implementation-plan.md`: staged execution plan for dataset + provenance, cube-sphere bakes, model training, and runtime integration. ## Migration And Demo Context diff --git a/docs/planetary-flow-implementation-plan.md b/docs/planetary-flow-implementation-plan.md new file mode 100644 index 0000000..420b262 --- /dev/null +++ b/docs/planetary-flow-implementation-plan.md @@ -0,0 +1,178 @@ +# Planetary Flow Implementation Plan + +This is the execution plan for Fensalir's planetary flow organ. It is ordered to +prove ownership and data shape before expensive model work. + +## Invariants + +- Fensalir owns the reusable stochastic advection contract and runtime + streaming machinery. +- Source datasets are offline evidence with provenance, not runtime authority. +- The runtime representation is cube-sphere native. +- The model emits stochastic advection parameters, not only deterministic flow + vectors. +- Client repos can consume, visualize, or condition flow; they do not bypass + the engine field evidence path. +- LOD inheritance must preserve physical continuity across parent and child + tiles. + +## Phase 0: Scope And Provenance + +Deliverables: + +- source manifest format for dataset id, URL, license, citation, access date, + variable list, spatial grid, temporal cadence, and derived artifacts; +- initial source rows for ETOPO 2022, GEBCO, ERA5, OSCAR, PlasticAdrift, and + candidate CMEMS/HYCOM products; +- decision on local storage shape for raw downloads and cube-sphere bakes. + +Verification: + +- a provenance report can be generated without model code; +- no training shard can be created without a source manifest row. + +## Phase 1: Cube-Sphere Bake Pipeline + +Deliverables: + +- offline tool that samples lat/lon or NetCDF/Zarr inputs into `CubeTileKey` + pages; +- baked static channels: elevation, bathymetry, land/sea mask, slope, + curvature, coastline distance, source quality; +- baked dynamic channel fixture from a small ERA5/OSCAR subset; +- metric metadata per tile: area scale, local tangent frame, latitude/Coriolis, + projection id, and missing-data mask. + +Verification: + +- round-trip sample checks against source grids at known points; +- area-weighted global summary checks; +- cross-face continuity checks; +- debug image or CSV dump for one tile pyramid. + +## Phase 2: Contract Skeleton + +Deliverables: + +- `PlanetaryFlowDomain`, `PlanetaryFlowRequest`, `PlanetaryFlowSample`, and + `PlanetaryFlowClaim` contracts; +- encoding enum or equivalent for `StochasticAdvection`; +- field evidence validation for Transport-layer flow claims; +- test fixtures with synthetic flow pages. + +Verification: + +- contract round-trip tests; +- validation rejects missing model/source versions and invalid covariance; +- synthetic claims can pass through the field evidence planner without D3D12 + flow rendering. + +## Phase 3: Synthetic Runtime Slice + +Deliverables: + +- analytic synthetic flow model over cube-sphere tiles; +- baked/evaluated flow pages at multiple LODs; +- debug visualization for mean velocity, covariance ellipse, confidence, and + inherited versus evaluated LOD. + +Verification: + +- particles or probe samples advect continuously across tile and face edges; +- parent-to-child values are consistent under aggregation; +- camera-driven selected cuts request the same flow path as direct debug + sampling. + +## Phase 4: Baseline Learning Pipeline + +Deliverables: + +- Python training workspace or external tool boundary with sharded data loader; +- baseline local tile-pyramid model; +- outputs: mean tangent velocity and covariance; +- losses: vector regression, negative log likelihood, smoothness, and + parent-child scale consistency; +- held-out region/time evaluation. + +Training plan: + +- start with ERA5 10m wind over a small temporal window; +- add OSCAR surface currents as the first ocean target; +- train on cube-sphere pages, not raw lat/lon; +- normalize per variable and preserve masks; +- keep model identity, source versions, and normalization stats with every + checkpoint. + +Verification: + +- beat a persistence/climatology baseline; +- visualize residuals by latitude, coastline distance, and LOD; +- check conservation-ish behavior through particle rollouts, not only per-cell + vector error. + +## Phase 5: PlasticAdrift Auxiliary Target + +Deliverables: + +- importer for PlasticAdrift probability outputs and/or transition matrix where + license/access are verified; +- cube-sphere mapping from debris probability cells to transport targets; +- auxiliary loss from predicted stochastic parameters to observed transition + distributions over a lead time; +- validation cases for known garbage-patch accumulation behavior. + +Verification: + +- probability mass remains normalized after cube-sphere remap within declared + omission thresholds; +- rollouts from predicted parameters reproduce broad PlasticAdrift transition + behavior better than deterministic current-only advection. + +## Phase 6: Hierarchical Model And Streaming + +Deliverables: + +- hierarchical graph or neural-operator model over cube-sphere tiles; +- parent/child and same-level neighbor edges; +- streaming evaluation for requested selected cuts; +- cache/page residency keyed by model and conditioning versions; +- uncertainty-driven refinement. + +Architecture hypotheses to test: + +- local patch encoder plus graph head for first production model; +- hierarchical graph neural operator for long-term arbitrary LOD; +- sparse transition logits only where PlasticAdrift-style debris transport + needs them; +- covariance output via Cholesky factors to guarantee positive semidefinite + diffusion. + +Verification: + +- stable cross-LOD particle rollouts; +- bounded frame-time budget under camera motion; +- debug report ties visible flow to model version, source versions, and selected + LOD. + +## Phase 7: Renderer And Simulation Integration + +Deliverables: + +- D3D12 flow page resources; +- compute shader helpers for stochastic particle advection; +- debug overlays and capture fixtures; +- API for clients to request flow at world points or publish visual consumers. + +Verification: + +- headless capture shows nonblank flow diagnostics; +- direct sampling, debug visualization, and particle advection agree on the + sampled layer; +- stale pages cannot silently render after model/source version changes. + +## Recommended First Cut + +Build the synthetic runtime slice before downloading the ocean. Then train the +small ERA5 wind model. Then add OSCAR. Then PlasticAdrift. The ocean will try to +turn this into a grand expedition immediately; make the contract prove it can +hold a cup of water first. diff --git a/docs/planetary-flow-organ.md b/docs/planetary-flow-organ.md new file mode 100644 index 0000000..fcffb38 --- /dev/null +++ b/docs/planetary-flow-organ.md @@ -0,0 +1,277 @@ +# Planetary Flow Organ + +## Objective + +Add a reusable planetary flow organ to Fensalir that predicts stochastic +advection parameter sets over optimized cube-sphere domains. The organ should +serve whole-planet ocean-surface and atmospheric flow to renderers and +simulations at arbitrary LOD: fine near the camera, coarse far away, and always +bounded by explicit uncertainty. + +The product is not "one current vector per point." The product is a streamable +transport field: + +```text +cube-sphere tile + time/context + static planet geometry + dynamic state +-> stochastic advection parameters +-> renderer/simulation samples, transition kernels, and uncertainty telemetry +``` + +## Authority Map + +Owner: `Aquarium.Engine.Fractal` should own the domain math, tile identity, +LOD/residency contract, training data preparation shape, and inference packet +schema. Runtime inference may later move to a dedicated ML package, but the +engine owns the field contract that clients consume. + +Inputs: cube-sphere tile address, projection metadata, static relief/bathymetry, +land/sea mask, latitude/Coriolis features, calendar/season phase, optional +recent atmosphere/ocean state, and dataset provenance/version. + +Outputs: bounded stochastic advection parameter tiles for atmosphere and ocean +surface. The first output schema should support mean velocity, covariance or +diffusivity, optional transition-kernel logits over neighboring cells, and +calibration/confidence. + +Derived state: visualization arrows, particle paths, current speed heatmaps, +plastic trajectories, and gameplay/weather effects are derived views. They do +not own flow truth. + +Forbidden writers: renderer shaders, demo clients, PlasticAdrift import code, +weather dataset loaders, and particle systems must not invent private flow +fields. They may request or display flow packets; they may not become alternate +advection authorities. + +Shared paths: direct camera streaming, background planetary simulation, offline +training export, replay from persisted time, and imported dataset validation +all use the same cube-sphere tile key, same normalization metadata, and same +flow packet schema. + +Deletion line: do not add a lat-long-only flow path as a convenient prototype +that later needs adapters. Lat-long sources are ingestion formats; cube-sphere +tiles are the engine domain. + +## Current Mechanism + +Fensalir already has the right substrate: + +- `CubeTileKey` names a six-face quadtree tile. +- cube-sphere projections exist for normalized and tangent mappings. +- surface pages, residency planning, and selected cuts already express + streamable planetary surface data. +- the field architecture already distinguishes Form, Appearance, and Transport + evidence. Planetary flow belongs in Transport. + +The missing organ is a data and inference path that fills cube-sphere Transport +pages with stochastic advection parameters instead of authored brush evidence. + +## Invariants + +- Cube-sphere tile identity is the runtime domain. Lat-long is only source data + layout or debug view. +- Static relief alone is not a sufficient predictor. Bathymetry/topography can + shape flow, but dynamic atmosphere/ocean state and time conditioning are real + inputs. +- A stochastic output must expose uncertainty. A mean vector without dispersion + is a visualization convenience, not the organ. +- Conservative LOD summaries remain renderable. Missing high-resolution child + tiles fall back to parent flow summaries. +- Learned priority may choose what to refine first; it may not replace packet + validity, tile bounds, provenance, or calibration checks. +- PlasticAdrift-style transition matrices are validation and auxiliary targets, + not full ocean-dynamics truth. + +## Output Parameterization + +Start with a compact packet that can represent both velocity-like and +transition-matrix targets: + +```text +FlowTilePacket + Domain: CubeTileKey, projection id, cell spacing, time basis + Layer: oceanSurface | atmosphereNearSurface | atmospherePressureLevel + MeanVelocity: tangent-space u/v per sample + Diffusivity: symmetric 2x2 tangent covariance or log-Cholesky parameters + NeighborKernel: optional logits over fixed cube-tile neighbor stencil + DivergenceCurl: optional diagnostic channels + Confidence: calibration, dataset mask, and extrapolation flags + Provenance: source dataset, model version, normalization version +``` + +The first implementation should train mean velocity and diffusivity. Add +neighbor-kernel logits once ingestion can derive transition targets from +drifter/plastic or rollouts. A full dense transition matrix is useful offline, +but it is too large as the primary render packet. + +## Dataset Spine + +Static planet geometry: + +- GEBCO_2025 Grid: global land/ocean terrain at 15 arc-second resolution, with + source-type identifier grid and attribution request. +- NOAA ETOPO 2022: 15 arc-second global relief, useful as a CC0-licensed + baseline. + +Atmosphere targets: + +- ERA5 through the Copernicus Climate Data Store: hourly global reanalysis from + 1940 onward, 0.25 degree public data, useful for wind and pressure fields. + +Ocean targets: + +- Copernicus Marine GLORYS12V1 global ocean physics reanalysis: eddy-resolving + 1/12 degree, daily/monthly currents, sea level, temperature, salinity, and + related fields from 1993 onward. +- OSCAR surface currents: satellite-derived upper-ocean currents at coarse + global resolution, useful for surface-current validation and lightweight + baselines. +- HYCOM/NCODA global products: high-resolution operational/reanalysis ocean + fields, useful but operationally rougher because availability and exact data + gaps matter. + +Plastic/drifter transport: + +- PlasticAdrift/Adrift style transition matrices provide probability + distributions over future surface positions from observed drifter-derived + transport. Use them to supervise or validate stochastic surface transport, + especially transition kernels and long-horizon debris behavior. + +See `../research/planetary-flow-organ-literature.md` for source-backed notes. + +## Model Hypotheses + +### Baseline + +Use deterministic interpolation and simple stochastic residuals first: + +```text +source reanalysis field +-> reproject to cube-sphere tile pyramid +-> train predictor for mean velocity +-> fit residual covariance/diffusivity per biome/season/tile scale +``` + +This proves ingestion, normalization, tiling, loss functions, and packet +streaming before the neural architecture gets to wear a crown. + +### Strong Candidate + +Use a graph/operator hybrid: + +- graph mesh over cube-sphere tiles for domain adjacency, seams, and variable + LOD; +- local multiscale tile encoder for relief/bathymetry and recent dynamic + fields; +- message passing across neighboring and parent/child tiles; +- operator-style global context for long-range circulation; +- probabilistic head emitting mean velocity, log-Cholesky diffusivity, and + optional neighbor-kernel logits. + +This follows the useful parts of GraphCast and MeshGraphNets while preserving +Fensalir's cube-sphere domain instead of importing an icosahedral mesh as a +second planetary truth. + +### Alternative + +Train an SFNO/FourCastNet-like global model for atmosphere/ocean state +forecasting, then distill or sample it into cube-sphere flow packets. This is +attractive for global coherence but less naturally aligned with arbitrary +camera-driven LOD. + +### Probabilistic Extension + +Use diffusion, flow matching, or latent-variable ensembles only after the +packet schema and deterministic/stochastic residual baseline are measurable. +GenCast proves diffusion-style ensemble weather can work; it also proves that +sampling cost is real. Fensalir should not pay that cost per visible tile unless +the result beats calibrated covariance and ensemble heads. + +## Training Plan + +1. Ingest static relief into a cube-sphere pyramid. + Preserve source resolution, vertical datum notes, land/sea mask, slope, + curvature, roughness, and coastline distance. + +2. Ingest ERA5 and GLORYS/OSCAR/HYCOM targets. + Normalize to common time slices, tangent basis, units, masks, and + cube-sphere tile pyramid levels. Store source provenance per tile/time. + +3. Build the baseline target set. + Atmosphere: near-surface winds first, then pressure-level winds. Ocean: + surface `uo/vo` or equivalent currents first. Plastic: transition + distributions as auxiliary/validation targets. + +4. Train a single-tile local model. + Inputs are multi-channel multiscale crops around a target cell: relief, + slope, land/sea, Coriolis/latitude, season phase, and recent dynamic fields. + Output mean velocity plus diagonal covariance. + +5. Add cross-tile and parent/child context. + Replace pure crops with cube-sphere graph adjacency and LOD-aware message + passing. Verify seams explicitly. + +6. Add stochastic transport heads. + Upgrade covariance to full tangent 2x2 log-Cholesky. Add neighbor-kernel + logits over a small stencil where transition data supports it. + +7. Validate at the layer users see. + Check one-step vector RMSE, calibrated uncertainty, multi-step trajectory + spread, PlasticAdrift-style transition behavior, visible tile LOD stability, + seam continuity, and parent/child summary consistency. + +8. Distill for runtime. + Export a tile-streaming inference package or precomputed coefficient pages + with model/version metadata. Runtime packets must be small enough for camera + streaming and cache eviction. + +## Implementation Roadmap + +### Phase A: Schema And Data Map + +- Add `FlowTilePacket` and source provenance notes in docs before code. +- Define tangent-space basis conventions for each cube face. +- Decide the first tile pyramid levels used for training and runtime. +- Create ingestion manifests for GEBCO/ETOPO, ERA5, GLORYS, OSCAR, HYCOM, and + PlasticAdrift. + +### Phase B: Offline Reprojection + +- Build offline reprojection from lat-long/source grids to cube-sphere tiles. +- Emit min/mean/max/std summaries for parent LODs. +- Validate seam continuity and area weighting. + +### Phase C: Baseline Flow Pages + +- Store mean velocity and simple covariance pages as engine-readable Transport + pages. +- Add debug visualization: vectors, speed, uncertainty ellipse, mask, source + version, parent/child mismatch. + +### Phase D: Training Harness + +- Train local multiscale baseline on reanalysis targets. +- Add held-out years/regions and no-cheating temporal splits. +- Compare against source interpolation and seasonal climatology. + +### Phase E: Graph/LOD Model + +- Add cube-sphere adjacency graph and parent/child message passing. +- Train seam-aware, LOD-aware stochastic packets. +- Verify arbitrary camera streaming by requesting mixed-resolution cuts and + comparing against full-resolution source fields. + +### Phase F: Runtime Inference Or Distillation + +- Choose between precomputed flow pages, local tile inference, or hybrid + coarse-global plus local-refinement inference. +- Lower results into shared field resource pages and debug telemetry. + +## Cut Lines + +- No demo-owned flow field. +- No lat-long runtime authority. +- No bathymetry-only predictor except as an explicit baseline. +- No stochastic claims without calibration plots. +- No neural architecture before the baseline proves ingestion and packet + semantics. +- No per-pixel weather model in the renderer. The renderer samples packets. diff --git a/research/README.md b/research/README.md index 7af3dd8..b545403 100644 --- a/research/README.md +++ b/research/README.md @@ -14,6 +14,9 @@ Fensalir keeps engine-relevant research here. strategy and receipt ladder. - `rendering/fensalir-spine-emblem-ifs-demo.md`: Fensalir splash visual target. - `rendering/fractal-projection-report.md`: cube projection measurement notes. +- `planetary-flow-organ-literature.md`: source-backed sidecar distillation for + stochastic transport, bathymetry/topography, reanalysis targets, model + literature, and architecture hypotheses for cube-sphere flow. - `d3d12/`: source synthesis and migration research for the renderer spine. Client-only visual grammar belongs in the client repos. Engine research stays diff --git a/research/planetary-flow-organ-literature.md b/research/planetary-flow-organ-literature.md new file mode 100644 index 0000000..21d89ac --- /dev/null +++ b/research/planetary-flow-organ-literature.md @@ -0,0 +1,164 @@ +# Planetary Flow Organ Research Notes + +This note distills the research sidecar for a Fensalir organ that predicts +stochastic advection parameter sets over cube-sphere planetary domains. + +## 1. Stochastic Lagrangian And Plastic Transport + +PlasticAdrift/Adrift is best treated as a stochastic transition target, not as a +velocity field. The Adrift paper describes a statistical transition-matrix +representation built from trajectories of more than 15,000 surface drifters, +and the PlasticAdrift site refers to its own transition matrix and ten-year +probability animations. + +Implementation implication: use PlasticAdrift as auxiliary supervision or +validation for surface transport kernels: + +```text +cell now -> probability over future cells +``` + +This can train or check neighbor-kernel logits, effective diffusivity, seasonal +connectivity, and multi-step debris spread. It should not be the only ocean +truth because it represents observed surface drift statistics, not full ocean +state. + +Sources: + +- PlasticAdrift: https://plasticadrift.org/ +- Adrift.org.au paper abstract: https://www.sciencedirect.com/science/article/abs/pii/S0022098114002445 +- McAdam and van Sebille transition matrices: https://dbc.library.uu.nl/handle/1874/362629 + +## 2. Bathymetry And Topography + +GEBCO_2025 is the best current high-resolution global relief/bathymetry source +for broad use. It provides global land/ocean elevation on a 15 arc-second grid, +with 43,200 x 86,400 samples, NetCDF distribution, WGS84 assumption, and a +source-type identifier grid. GEBCO asks for attribution in publications. + +NOAA ETOPO 2022 is a strong baseline because it is a 15 arc-second global +relief model and the ESSD dataset paper states that ETOPO data are covered by +CC0-1.0 in NOAA metadata. It is especially useful where a permissive licensing +posture matters more than the newest GEBCO revision. + +Implementation implication: ingest both. Use ETOPO as the permissive default +and GEBCO as the higher-confidence bathymetry option with explicit attribution +and source-type channels. + +Sources: + +- GEBCO_2025 Grid: https://www.gebco.net/data-products-gridded-bathymetry-data/gebco2025-grid +- GEBCO gridded data: https://www.gebco.net/data_and_products/gridded_bathymetry_data/ +- NOAA ETOPO: https://www.ncei.noaa.gov/products/etopo-global-relief-model +- ETOPO 2022 ESSD paper/license note: https://essd.copernicus.org/articles/17/1835/2025/ + +## 3. Atmosphere And Ocean Targets + +ERA5 is the default atmospheric target. Copernicus describes ERA5 as global +hourly reanalysis from 1940 onward, updated about five days behind real time, +with 0.25 degree grids and 37 pressure levels. Copernicus Climate Data Store +access is open, free, and unrestricted, though users accept dataset licenses. + +GLORYS12V1 through Copernicus Marine is the best first ocean reanalysis target: +global eddy-resolving 1/12 degree, 50 vertical levels, altimetry-era coverage +from 1993 onward, daily/monthly means, currents, sea level, temperature, +salinity, mixed-layer depth, and ice variables. Copernicus Marine describes its +service as free and open access; registration and acknowledgement still matter. + +OSCAR is a useful surface-current baseline and validation product. It estimates +upper-ocean currents from satellite sea-surface height, winds, and SST gradients +using simplified geostrophic/Ekman/thermal-wind dynamics. Data.gov lists the +OSCAR final 0.25 degree product under a U.S. government works license URL. + +HYCOM/NCODA provides high-resolution global ocean prediction/reanalysis access +through HYCOM servers. HYCOM states the data are UNCLASSIFIED, Distribution A, +approved for public release, with a demonstration-product disclaimer and +availability caveats. Treat HYCOM as valuable but operationally messier than +GLORYS for the first reproducible training set. + +Implementation implication: train v1 on ERA5 plus GLORYS, validate against +OSCAR and PlasticAdrift, then consider HYCOM for higher-resolution or near-real +time ocean variants. + +Sources: + +- ERA5 climate reanalysis: https://climate.copernicus.eu/climate-reanalysis +- Copernicus Climate Data Store: https://climate.copernicus.eu/climate-data-store +- GLORYS global ocean physics reanalysis: https://data.marine.copernicus.eu/product-detail/GLOBAL_MULTIYEAR_PHY_001_030 +- Copernicus Marine about/free access: https://marine.copernicus.eu/about/ +- OSCAR data.gov entry: https://catalog.data.gov/dataset/ocean-surface-current-analyses-real-time-oscar-surface-currents-final-0-25-degree-version- +- ESR OSCAR overview: https://www.esr.org/data-products/oscar/oscar-surface-currents/ +- HYCOM data server/disclaimer: https://www.hycom.org/ +- HYCOM reanalysis acknowledgement: https://www.hycom.org/publications/acknowledgements/ocean-reanalysis-data + +## 4. Neural And Operator Architectures + +GraphCast proves the graph-on-sphere family for global weather. It operates on a +0.25 degree lat-long grid but uses graph neural networks and a high-resolution +multi-scale mesh representation to predict 227 atmospheric variables at 6-hour +steps. The important lesson for Fensalir is not the lat-long input. It is the +encoder/processor/decoder shape and learned multi-scale spherical mesh. + +FourCastNet and SFNO prove the operator-learning family. FNOs are attractive +because operator learning can be resolution-aware, and SFNO specifically avoids +flat Fourier artifacts on spherical geometry while producing stable atmospheric +rollouts. This is relevant for global coherence and low-rank long-distance +structure. + +MeshGraphNets proves learned simulation over arbitrary meshes. This maps well +to cube-sphere tiles, seam adjacency, and parent/child LOD graphs. + +GenCast proves probabilistic weather through conditional diffusion and a +graph-transformer-style spherical denoiser. It produces ensemble forecasts, but +sampling is more expensive than deterministic MLWP. For Fensalir, this is a +later uncertainty-upgrade path, not the first runtime packet machine. + +Implementation implication: start with a cube-sphere graph encoder plus local +multiscale tile encoder. Add SFNO/global-context distillation if local graph +context cannot capture long-range circulation. Keep diffusion/flow matching for +offline ensemble generation or teacher models until runtime cost is justified. + +Sources: + +- GraphCast: https://deepmind.google/research/publications/22598/ +- SFNO: https://research.nvidia.com/publication/2023-06_spherical-fourier-neural-operators-learning-stable-dynamics-sphere +- FourCastNet: https://authors.library.caltech.edu/records/k959a-53q45 +- NVIDIA FourCastNet V2/SFNO variables: https://docs.api.nvidia.com/nim/reference/nvidia-fourcastnet +- MeshGraphNets: https://arxiv.org/abs/2010.03409 +- GenCast: https://www.nature.com/articles/s41586-024-08252-9 +- NeuralGCM hybrid model context: https://www.nature.com/articles/s41586-024-07744-y + +## 5. Stochastic Advection Outputs + +Candidate outputs: + +- mean tangent velocity: cheapest and easiest to compare with ERA5/GLORYS; +- diagonal or full diffusivity tensor: compact stochastic spread; +- transition kernel over a fixed neighbor stencil: closest to PlasticAdrift and + best for particle/debris advection on discrete tiles; +- calibrated uncertainty/ensemble moments: needed for visible confidence and + simulation honesty; +- seasonal/time conditioning: required because static geometry alone cannot + determine circulation; +- source/provenance flags: needed where source data is sparse, masked, stale, or + extrapolated. + +Recommendation: first train mean velocity plus full 2x2 tangent covariance, +then add neighbor-kernel logits where transition data is available. A dense +global transition matrix is an offline research artifact, not a runtime packet. + +## Short Recommendations + +1. Use cube-sphere tiles as runtime authority from day one. +2. Use ETOPO as the permissive relief baseline; add GEBCO with attribution and + TID/source-type channels. +3. Train atmosphere on ERA5 and ocean surface on GLORYS first. +4. Use OSCAR and PlasticAdrift as validation/auxiliary transport targets. +5. Treat HYCOM as a later high-resolution or near-real-time source because its + access/disclaimer/data-gap profile is rougher. +6. Start with mean velocity plus calibrated covariance, then add transition + kernels. +7. Use a cube-sphere graph/operator hybrid; do not force the engine to adopt a + second spherical mesh as flow truth. +8. Keep diffusion/flow matching as an ensemble teacher or offline uncertainty + model until the runtime cost earns its keep. diff --git a/state/evidence-planetary-flow-organ.md b/state/evidence-planetary-flow-organ.md new file mode 100644 index 0000000..25f2a0c --- /dev/null +++ b/state/evidence-planetary-flow-organ.md @@ -0,0 +1,18 @@ +# Planetary Flow Organ Evidence + +Date: 2026-05-29 + +Fensalir is the right owner for reusable planetary flow only after the problem +is reduced to engine mechanisms: cube-sphere addressing, dataset provenance, +stochastic advection contracts, selected-cut streaming, GPU resources, and +debug evidence. Client repos own planet meaning and consumers. + +Useful correction: PlasticAdrift is not a velocity-vector field. It is +transition-matrix style surface transport evidence. The runtime organ should +distill such evidence into mean velocity, covariance/diffusivity, optional +sparse transition logits, and calibrated uncertainty. + +Do not train elevation-only flow and call it ocean/atmosphere. Relief is a +static conditioning channel. Dynamic state from ERA5, OSCAR/CMEMS/HYCOM, time +phase, Coriolis/latitude, sea-surface variables, masks, and source quality must +participate before the prediction has authority. diff --git a/state/map.yaml b/state/map.yaml index 3a97654..dc5d0f7 100644 --- a/state/map.yaml +++ b/state/map.yaml @@ -97,12 +97,24 @@ invariants: resource in `Common` so OBS/EVE/native consumers can transition it for GPU-side reads without inheriting Fensalir's internal copy-destination state. + - Planetary ocean/atmosphere flow is an engine field organ when reduced to + reusable stochastic advection machinery. Fensalir owns cube-sphere flow + addressing, dataset provenance, model contracts, stochastic advection + parameter schema, selected-cut streaming, and renderer/simulation lowerings. + Client repos may choose planet meaning and consume flow, but must not own a + private planetary flow truth path. Lat/lon datasets are offline evidence; + runtime flow authority is cube-sphere native. next_actions: - Keep origin pointed at https://github.com/GameCult/Fensalir.git. - Keep `dotnet build Fensalir.sln` green after the split. - Cut the rendering rebuild through explicit field-domain/field-claim contracts before adding another backend-specific visual path. + - Build the planetary flow organ in staged cuts: provenance manifest, static + relief and reanalysis cube-sphere bake pipeline, stochastic advection + contracts, synthetic runtime slice, ERA5/OSCAR baseline learning, then + PlasticAdrift transition validation and hierarchical arbitrary-LOD + streaming. - Extend the D3D12 field packet/resource resolver beyond its first structured/curve-buffer cut. Current contracts, DSL, and renderer registry can validate and plan resource-backed TubeField packets, import shared GPU