Add HealDA v2 model card

README.md

@@ -1,3 +1,326 @@
----
-license: openmdw-1.1
----
+# Model Overview
+
+## Description
+
+HealDA v2 is a global machine-learning data-assimilation model that maps a
+48-hour sequence of satellite and conventional observations to a 104-channel,
+0.25° atmospheric analysis on a regular latitude–longitude grid. The analysis
+can serve as an initial condition for off-the-shelf machine-learning weather
+forecast models.
+
+Unlike HealDA v1, which processes one analysis time independently, HealDA v2
+uses causal video data assimilation across eight consecutive 6-hourly analysis
+times. Each frame uses observations within ±3 hours of its analysis time, so
+the complete sequence covers 48 hours from the earliest to the latest
+observation time. Temporal attention allows later analyses to use information
+from earlier frames without using future model states. The public inference API
+returns only the final analysis frame.
+
+This checkpoint predicts 104 atmospheric, ocean-surface, cloud, and land-surface
+fields. It was trained with source-level NNJA satellite and conventional
+observations, including microwave and infrared sounders, GNSS radio occultation,
+satellite-derived winds, and in-situ observations.
+
+This model is for research and development only.
+
+### License/Terms of Use
+
+**Governing Terms:** Use of this model is governed by the [Linux Foundation
+OpenMDW License Agreement, version
+1.1](https://github.com/OpenMDW/OpenMDW/blob/main/1.1/LICENSE.OpenMDW-1.1).
+See the `LICENSE` file distributed with the model for the governing terms.
+Third-party data-derived assets distributed with the model are subject to the
+notices in [ATTRIBUTION.md](model_card/ATTRIBUTION.md).
+
+### Deployment Geography
+
+Global
+
+## Use Case
+
+Industry, academic, and government research teams interested in global data
+assimilation, observing-system studies, and initialization of medium-range
+machine-learning weather forecasts. Model analyses are statistical estimates
+and should not be the sole basis for safety-critical decisions.
+
+## Release Date
+
+Hugging Face 10/01/2026 via [nvidia/healda-v2](https://huggingface.co/nvidia/healda-v2)
+
+## Reference(s)
+
+**Papers:**
+
+- [HealDA: Highlighting the importance of initial errors in end-to-end AI
+  weather forecasts](https://arxiv.org/abs/2601.17636)
+
+**Code:**
+
+- [PhysicsNeMo](https://github.com/NVIDIA/physicsnemo)
+- [Earth2Studio](https://github.com/NVIDIA/earth2studio)
+
+## Model Architecture
+
+**Architecture Type:** Custom observation encoder + HEALPix Diffusion
+Transformer (DiT) backbone + mesh-to-grid decoder, used as a deterministic
+regression model. <br>
+
+**Network Architecture:** Sensor-specific point-cloud embedders encode irregular
+observations. Observation-to-pixel cross-attention places those features into an
+internal HEALPix latent representation. A DiT backbone applies spatial
+self-attention and causal temporal attention across eight analysis frames. A
+GraphCast-style mesh-to-grid decoder maps the latent representation directly to
+the native 0.25° regular latitude–longitude output grid. <br>
+
+**This model was developed based on:** HealDA v1 and the Earth2Studio /
+PhysicsNeMo HEALPix transformer stack. <br>
+
+**Number of model parameters:** 917.42 million (~0.92 billion). <br>
+
+## Input(s)
+
+**Input Type(s):**
+
+- Tensor (satellite and conventional observations represented as point-cloud data)
+- Tensor (eight ERA5-derived static conditioning channels and geographic features)
+- Tensor (day of year)
+- Tensor (second of day)
+
+**Input Format(s):** PyTorch tensors <br>
+
+**Input Parameters:**
+
+- Observations: variable-length point clouds organized into eight 6-hourly frames
+- Static conditioning: eight global 0.25° ERA5-derived channels on a
+  `721 × 1440` latitude–longitude grid and their internal HEALPix representation
+- Day of year: two-dimensional tensor `(batch, time)`
+- Second of day: two-dimensional tensor `(batch, time)`
+- Sequence length: eight analysis frames
+
+**Other Properties Related to Input:**
+
+- Observation context: ±3 hours around each frame. Eight frames separated by six
+  hours provide a 48-hour span from the earliest to latest observation time.
+- Microwave sounders: ATMS, AMSU-A, AMSU-B, and MHS.
+- Infrared sounders: AIRS, IASI, and CrIS.
+- Conventional observations: surface stations, aircraft, radiosondes, and buoys,
+  including pressure, temperature, humidity, and wind measurements.
+- GNSS radio occultation: bending-angle observations.
+- Satellite-derived winds: atmospheric motion vectors and ASCAT scatterometer winds.
+- Time-invariant conditioning uses eight channels from ERA5 invariant datasets:
+  orography (`orog`), land-sea mask (`lsm`), standard deviation of subgrid
+  orography (`sdor`), subgrid-orography slope (`slor`), subgrid-orography
+  anisotropy (`isor`), standard deviation of filtered subgrid orography (`sdfor`),
+  and the sine and cosine of subgrid-orography orientation (`anor_sin`,
+  `anor_cos`). Time-varying conditioning includes calendar and solar-zenith
+  features.
+
+## Output(s)
+
+**Output Type(s):** Tensor (104-channel global atmospheric, ocean-surface,
+cloud, and land-surface analysis) <br>
+
+**Output Format(s):** PyTorch tensor <br>
+
+**Output Parameters:** The public inference API returns the final analysis on a
+`721 × 1440` latitude–longitude grid. The tensor has shape equivalent to
+`(batch, 104, latitude=721, longitude=1440)`; interfaces that retain a time
+dimension expose it with length one. <br>
+
+**Other Properties Related to Output:**
+
+- Output grid: global regular latitude–longitude grid at 0.25° resolution,
+  represented by 721 latitude points and 1,440 longitude points.
+- Pressure levels: 1000, 925, 850, 700, 600, 500, 400, 300, 250, 200, 150, 100,
+  and 50 hPa.
+- Three-dimensional fields on all 13 pressure levels: zonal wind (`U`), meridional
+  wind (`V`), temperature (`T`), geopotential (`Z`), specific humidity (`Q`), and
+  vertical velocity (`W`).
+- Additional 10 hPa fields: `U`, `V`, `T`, and `Z`. The checkpoint does not predict
+  `Q` or `W` at 10 hPa.
+- Surface and column fields: total-column water vapour (`tcwv`), 2 m temperature
+  (`tas`), 10 m wind (`uas`, `vas`), 100 m wind (`100u`, `100v`), mean sea-level
+  pressure (`pres_msl`), sea-surface temperature (`sst`), sea-ice concentration
+  (`sic`), surface pressure (`sp`), 2 m dewpoint (`d2m`), skin temperature (`skt`),
+  and total-column water (`tcw`).
+- Cloud fields: total, low, medium, and high cloud cover (`tcc`, `lcc`, `mcc`,
+  `hcc`).
+- Land fields: soil temperature in layers 1 and 2 (`stl1`, `stl2`), volumetric soil
+  water in layers 1 and 2 (`swvl1`, `swvl2`), and snow depth (`sd`).
+
+Our AI models are designed and/or optimized to run on NVIDIA GPU-accelerated
+systems. By leveraging NVIDIA hardware and CUDA software libraries, the model
+achieves faster training and inference than CPU-only execution.
+
+## Software Integration
+
+**Runtime Engine(s):** PyTorch / PhysicsNeMo <br>
+
+**Supported Hardware Microarchitecture Compatibility:**
+
+- NVIDIA Ampere
+- NVIDIA Blackwell
+- NVIDIA Hopper
+
+**Supported Operating System(s):**
+
+- Linux
+
+The integration of foundation and fine-tuned models into AI systems requires
+additional testing using use-case-specific data to ensure safe and effective
+deployment. Following the V-model methodology, iterative testing and validation
+at both unit and system levels are essential to mitigate risks, meet technical
+and functional requirements, and ensure compliance with safety and ethical
+standards before deployment.
+
+## Model Version(s)
+
+**Model version:** HealDA v2, 104-channel, 0.25° checkpoint. <br>
+
+# Training, Testing, and Evaluation Datasets
+
+## Training Dataset
+
+**Data Modality:**
+
+- Other: numerical geophysical point observations and gridded reanalysis fields
+
+**Training Data Size:**
+
+- 35,068 nominal six-hourly ERA5 target times across 2000–2021 and 2023–2024,
+  before availability filtering, paired with a variable number of NNJA point
+  observations
+
+**Link:** [ERA5](https://cds.climate.copernicus.eu/) <br>
+
+**Data Collection Method by dataset:**
+
+- Automatic/Sensors (observations combined with numerical-model reanalysis)
+
+**Labeling Method by dataset:**
+
+- Automatic/Sensors
+
+**Properties:**
+
+Six-hourly ERA5 reanalysis fields on the native 0.25° regular
+latitude–longitude grid are used as supervised targets. Training uses 2000–2021
+and 2023–2024. Calendar year 2022 is held out for validation, and 2025 onward is
+reserved for out-of-sample testing. <br>
+
+ERA5 supplies all gridded atmospheric targets and all static conditioning
+fields. NNJA observations are used only as observation inputs to the data-assimilation
+model. <br>
+
+Per-channel normalization is computed for the 0.25° grid. Area-weighted loss
+and metrics account for the unequal cell areas of a regular latitude–longitude
+grid. Domain masks prevent fields such as sea-surface temperature, sea-ice
+concentration, and soil moisture from being scored outside their valid physical
+domains. <br>
+
+**Attribution:** See [ATTRIBUTION.md](model_card/ATTRIBUTION.md) for any ERA5-derived files redistributed
+with the model package.
+
+**Source:** [NOAA–NASA Joint Archive (NNJA) of Observations for Earth System
+Reanalysis](https://www.psl.noaa.gov/data/nnja_obs/), distributed through the
+public `s3://noaa-reanalyses-pds/observations/reanalysis/` archive. <br>
+
+**License:** [Creative Commons Attribution 4.0 International (CC BY
+4.0)](https://creativecommons.org/licenses/by/4.0/). <br>
+
+**Attribution:** NOAA NASA Joint Archive (NNJA),
+https://www.psl.noaa.gov/data/nnja_obs/. See [ATTRIBUTION.md](model_card/ATTRIBUTION.md) for packaged
+NNJA-derived preprocessing assets and the additional acknowledgement applicable
+to the `amv/merged` stream. <br>
+
+**Data Collection Method by dataset:**
+
+- Automatic/Sensors
+
+**Labeling Method by dataset:**
+
+- Automatic/Sensors
+
+**Properties:**
+
+Satellite observations include microwave and infrared sounders. Conventional
+observations include PrepBUFR surface, aircraft, radiosonde, and buoy reports,
+GNSS radio occultation, and dedicated satellite-wind products. The observing
+system changes over time as instruments enter and leave service. Observation
+inputs follow the same training, validation, and out-of-sample test periods as
+the corresponding ERA5 targets. NNJA is an experimental research dataset under
+active development, and archived content may change as quality-control updates
+are applied. <br>
+
+### Data Processing Description
+
+ERA5 fields are sampled at six-hour intervals on the native 0.25° grid.
+Observations are quality controlled, normalized by channel (and by pressure
+level for conventional observations), spatially thinned, and encoded as
+irregular point clouds. Each training example contains eight sequential analysis
+frames with causal temporal attention.
+
+## Testing Dataset
+
+**Links:** [ERA5](https://cds.climate.copernicus.eu/) and the corresponding
+held-out [NNJA observations](https://www.psl.noaa.gov/data/nnja_obs/). <br>
+
+**Data Collection Method by dataset:**
+
+- Automatic/Sensors
+
+**Labeling Method by dataset:**
+
+- Automatic/Sensors
+
+**Properties:**
+
+Data from 2025 onward is reserved for out-of-sample testing and is not used for
+optimization or model selection. Test coverage extends through the latest
+available matched ERA5 and NNJA observations. <br>
+
+## Evaluation Dataset
+
+**Links:** [ERA5](https://cds.climate.copernicus.eu/) and the corresponding
+held-out [NNJA observations](https://www.psl.noaa.gov/data/nnja_obs/). <br>
+
+**Benchmark Score:** Not reported. <br>
+
+**Data Collection Method by dataset:**
+
+- Automatic/Sensors
+
+**Labeling Method by dataset:**
+
+- Automatic/Sensors
+
+**Properties:**
+
+Validation uses calendar year 2022. Analysis error is evaluated against ERA5 on
+the native 0.25° grid using latitude-area weighting. Downstream forecast
+comparisons use matched forecast models, initialization dates, grids, regridding
+methods, and verification targets. <br>
+
+## Inference
+
+**Acceleration Engine:** PyTorch / PhysicsNeMo <br>
+
+**Test Hardware:**
+
+- NVIDIA Hopper (H100)
+- NVIDIA Blackwell (B300 / GB300)
+
+## Ethical Considerations
+
+NVIDIA believes Trustworthy AI is a shared responsibility and we have
+established policies and practices to enable development for a wide array of AI
+applications. Developers should work with their internal model team to ensure
+this model meets requirements for the relevant industry and use case and
+addresses unforeseen product misuse.
+
+For more detailed information on ethical considerations for this model, please
+see the Model Card++ [Bias](model_card/bias.md), [Explainability](model_card/explainability.md),
+[Safety & Security](model_card/safety.md), and [Privacy](model_card/privacy.md) Subcards.
+
+Please report model quality, risk, security vulnerabilities, or NVIDIA AI
+Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).

model_card/ATTRIBUTION.md

@@ -0,0 +1,68 @@
+# Attribution Notices
+
+This file records notices for data-derived files redistributed with the HealDA
+v2 model package. It does not change the OpenMDW-1.1 terms that govern the model
+weights and NVIDIA-authored files.
+
+## ERA5-derived static conditioning data
+
+**Applies to:** Packaged static-conditioning assets containing the eight
+ERA5-derived channels `orog`, `lsm`, `sdor`, `slor`, `isor`, `sdfor`,
+`anor_sin`, and `anor_cos`.
+
+**Source:** ERA5 invariant datasets produced by the European Centre for
+Medium-Range Weather Forecasts (ECMWF) and distributed through the public NSF
+NCAR ERA5 mirror at
+`s3://nsf-ncar-era5/e5.oper.invariant/197901/`:
+
+| Model channel | ERA5 parameter | Upstream invariant file |
+| --- | --- | --- |
+| `orog` | 129 (`z`, geopotential) | `e5.oper.invariant.128_129_z.ll025sc.1979010100_1979010100.nc` |
+| `lsm` | 172 (`lsm`) | `e5.oper.invariant.128_172_lsm.ll025sc.1979010100_1979010100.nc` |
+| `sdfor` | 074 (`sdfor`) | `e5.oper.invariant.128_074_sdfor.ll025sc.1979010100_1979010100.nc` |
+| `sdor` | 160 (`sdor`) | `e5.oper.invariant.128_160_sdor.ll025sc.1979010100_1979010100.nc` |
+| `isor` | 161 (`isor`) | `e5.oper.invariant.128_161_isor.ll025sc.1979010100_1979010100.nc` |
+| `anor_sin`, `anor_cos` | 162 (`anor`) | `e5.oper.invariant.128_162_anor.ll025sc.1979010100_1979010100.nc` |
+| `slor` | 163 (`slor`) | `e5.oper.invariant.128_163_slor.ll025sc.1979010100_1979010100.nc` |
+
+All source files are the January 1, 1979 invariant snapshot on the 0.25° regular
+latitude–longitude grid.
+
+**License:** [Creative Commons Attribution 4.0 International
+(CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/).
+
+**Changes made:** Orography is converted from geopotential to metres. The source
+fields are normalized for model input; `anor` is encoded as sine and cosine.
+The model uses the fields on the native 0.25° regular latitude–longitude grid
+and in a regridded HEALPix representation.
+
+**Attribution:** Modified from ECMWF Reanalysis data (ERA5), © European Centre
+for Medium-Range Weather Forecasts (ECMWF), distributed through the NSF NCAR
+ERA5 mirror. Licensed under CC BY 4.0.
+
+ECMWF and the European Commission are not responsible for any use that may be
+made of the Copernicus information or data contained in the redistributed asset.
+
+## NNJA-derived observation preprocessing assets
+
+**Applies to:** Packaged observation-channel metadata and normalization
+statistics derived from source-level NNJA observations.
+
+**Source:** [NOAA–NASA Joint Archive (NNJA) of Observations for Earth System
+Reanalysis](https://www.psl.noaa.gov/data/nnja_obs/), distributed through the
+public `s3://noaa-reanalyses-pds/observations/reanalysis/` archive.
+
+**License:** [Creative Commons Attribution 4.0 International
+(CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/).
+
+**Changes made:** Source observations are decoded, quality controlled,
+spatially thinned, organized into model channels, and summarized to produce the
+packaged preprocessing metadata and normalization statistics.
+
+**Attribution:** NOAA NASA Joint Archive (NNJA),
+https://www.psl.noaa.gov/data/nnja_obs/.
+
+**Additional acknowledgement for NNJA `amv/merged`:** EUMETSAT (2021),
+*Atmospheric Motion Vectors Climate Data Record Release 2 — MFG and MSG — 0
+degree*, European Organisation for the Exploitation of Meteorological
+Satellites, [doi:10.15770/EUM_SEC_CLM_0020](https://doi.org/10.15770/EUM_SEC_CLM_0020).

model_card/bias.md

@@ -0,0 +1,4 @@
+Field | Response
+:--|:--
+Participation considerations from adversely impacted groups [protected classes](https://www.senate.ca.gov/content/protected-classes) in model design and testing: | Not Applicable. The model operates on geophysical observations and does not model people or protected-class attributes.
+Measures taken to mitigate against unwanted bias: | Training-only observation dropout reduces reliance on selected wind platforms. Observation availability still varies by location, time, instrument, and platform, and equal geographic performance has not been established.

model_card/explainability.md

@@ -0,0 +1,13 @@
+Field | Response
+:--|:--
+Intended Task/Domain: | Global weather data assimilation and initialization of machine-learning weather forecasts.
+Model Type: | Observation encoder plus a deterministic HEALPix Diffusion Transformer with spatial, temporal, and observation-to-pixel attention, followed by a mesh-to-grid decoder.
+Intended Users: | Weather and climate researchers and developers implementing global data-assimilation and forecast-initialization pipelines.
+Output: | A 104-channel global atmospheric, ocean-surface, cloud, and land-surface analysis on a native 0.25° regular latitude–longitude grid (`721 × 1440`). The public inference API returns only the final frame for downstream forecast initialization. See `overview.md` for the complete grouped variable list.
+Describe how the model works: | All observations are featurized together with their metadata — instrument channel, platform, observation type, location and time — and passed through a single shared tokenizer, which maps each observation to one token. The tokenizer is FiLM-style: the raw measurement is the signal, and the metadata enters through embedding lookups that produce a per-feature scale and shift modulating it. In parallel, static geographic fields are patch-embedded and calendar features are encoded, forming the gridded conditioning input on an internal HEALPix latent representation. The backbone is a stack of transformer blocks, each applying, in order: local spatial attention, restricted per query to tokens within a fixed great-circle (haversine) distance on the sphere, observation-to-pixel cross-attention that injects the observation tokens into the latent, causal temporal attention across the eight frames, and a standard MLP. Frames are six hours apart and each receives observations within ±3 hours, so the sequence spans 48 hours of observations — 42 hours between the first and last frame, extended by the ±3-hour window at each end. Finally, a GraphCast-style mesh-to-grid decoder maps the latent representation directly to the native 0.25° latitude–longitude output grid.
+List the groups (or group characteristics) for which this was tested to produce comparable outcomes: | Not Applicable.
+Technical Limitations & Mitigation: | Performance depends on the density, quality, and historical availability of the observing system. The model may perform poorly for rare or out-of-distribution weather, changing instruments, and regions with sparse observations. It does not impose hard conservation laws or guarantee physical consistency. Domain masks and latitude-area weighting must be applied when scoring the 0.25° output.
+Verified to have met prescribed NVIDIA quality standards: | Yes
+Performance Metrics: | Latitude-area-weighted analysis RMSE and bias against ERA5 by variable and pressure level on the native 0.25° grid; downstream forecast RMSE and anomaly-correlation coefficient under matched initialization and verification; observation-denial sensitivity; throughput and latency.
+Potential Known Risks: | The model may produce incorrect atmospheric states or weather phenomena, particularly for extremes and out-of-distribution observing systems. Errors can propagate and amplify in a downstream forecast model. Outputs should not be the sole basis for safety-critical decisions.
+Licensing: | [Linux Foundation OpenMDW License Agreement, version 1.1](https://github.com/OpenMDW/OpenMDW/blob/main/1.1/LICENSE.OpenMDW-1.1)

model_card/privacy.md

@@ -0,0 +1,11 @@
+Field | Response
+:--|:--
+Generatable or reverse engineerable personal data? | No.
+Personal data used to create this model? | No. Training data consists of geophysical observations and reanalysis fields. Aircraft and station observations may contain platform or station identifiers but are not intended to identify natural persons.
+Was consent obtained for any personal data used? | Not Applicable.
+How often is dataset reviewed? | During dataset creation, model training, evaluation, and before release.
+Was data from user interactions with the AI model (e.g. user input and prompts) used to train the model? | No.
+Is there provenance for all datasets used in training? | Yes. ERA5 supplies the gridded targets and static fields; the NOAA–NASA NNJA archive supplies the observation inputs. Training uses 2000–2021 and 2023–2024, with 2022 held out for validation and 2025 onward reserved for testing.
+Does data labeling (annotation, metadata) comply with privacy laws? | Yes. Labeling is automatic: NNJA observation inputs are paired with numerical ERA5 targets without human annotation.
+Is data compliant with data subject requests for data correction or removal, if such a request was made? | Not Applicable.
+Applicable Privacy Policy | https://www.nvidia.com/en-us/about-nvidia/privacy-policy/

model_card/safety.md

@@ -0,0 +1,6 @@
+Field | Response
+:--|:--
+Model Application Field(s): | Climate
+Describe the life critical impact (if present). | Not Applicable. The checkpoint is intended for research and development and is not intended to be the sole basis for life-critical decisions.
+Use Case Restrictions: | Abide by the [Linux Foundation OpenMDW License Agreement, version 1.1](https://github.com/OpenMDW/OpenMDW/blob/main/1.1/LICENSE.OpenMDW-1.1).
+Model and dataset restrictions: | The Principle of least privilege (PoLP) is applied limiting access for dataset generation and model development. Restrictions enforce dataset access during training, and dataset license constraints are adhered to.