Update README.md

README.md

@@ -1,3 +1,136 @@
----
-license: cc-by-sa-4.0
----
+---
+license: cc-by-4.0
+pipeline_tag: graph-ml
+language:
+- en
+library_name: anemoi
+---
+
+# AIFS ENS - v1.0
+
+<!-- Provide a quick summary of what the model is/does. -->
+
+Here, we introduce the Artificial Intelligence Forecasting System (AIFS) ENS, 
+an ensemble-based probablistic data driven forecast model developed by the 
+European Centre for Medium-Range Weather Forecasts (ECMWF).
+
+
+AIFS produces highly skilled forecasts for upper-air variables, surface weather parameters and
+tropical cyclone tracks. AIFS ENS is run four times daily alongside ECMWF’s physics-based NWP model and forecasts
+are available to the public under ECMWF’s open data policy (https://www.ecmwf.int/en/forecasts/datasets/open-data). 
+Note that due to the non-determinism of GPUs, users will be unable to exactly reproduce an official AIFS ENS forecast 
+when running AIFS ENS themselves.
+
+For more details please refer to https://confluence.ecmwf.int/display/FCST/Implementation+of+AIFS+Single+v1
+
+## Data Details
+
+### Data parameters
+
+
+**Note** 
+Regarding precipitation units, it's worth noting that AIFS model was trained on \\(m^{3}/m^{2}\\) and will therefore produce precip in that units.
+If one wants to retrieve precipitation from Open data, the units will be \\(mm\\).
+
+
+## Model Details
+
+### Model Description
+
+<!-- Provide a longer summary of what this model is. -->
+
+AIFS is based on a graph neural network (GNN) encoder and decoder, and a sliding window transformer processor, 
+and is trained on ECMWF’s ERA5 re-analysis and ECMWF’s operational numerical weather prediction (NWP) analyses. 
+
+<div style="display: flex; justify-content: center;">
+  <img src="assets/encoder_graph.jpeg" alt="Encoder graph" style="width: 50%;"/>
+  <img src="assets/decoder_graph.jpeg" alt="Decoder graph" style="width: 50%;"/>
+</div>
+
+It has a flexible and modular design and supports several levels of parallelism to enable training on
+high resolution input data. AIFS forecast skill is assessed by comparing its forecasts to NWP analyses
+and direct observational data. 
+
+- **Developed by:** ECMWF
+- **Model type:** Encoder-processor-decoder model
+- **License:** These model weights are published under a Creative Commons Attribution 4.0 International (CC BY 4.0).
+To view a copy of this licence, visit https://creativecommons.org/licenses/by/4.0/
+
+### Model resolution
+
+| | Component | Horizontal Resolution [kms] | Vertical Resolution [levels] |
+|---|:---:|:---:|:---:|
+| Atmosphere | AIFS ENS v1.0 | ~ 31 |  13 |
+
+
+### Model Sources
+
+<!-- Provide the basic links for the model. -->
+
+- **Repository:** [Anemoi](https://anemoi.readthedocs.io/en/latest/index.html) is an open-source framework for
+  creating machine learning (ML) weather forecasting systems, which ECMWF and a range of national meteorological 
+  services across Europe have co-developed.
+- **Paper:** https://arxiv.org/abs/2412.15832
+
+## How to Get Started with the Model
+
+To generate a new forecast using AIFS, you can use [anemoi-inference](https://github.com/ecmwf/anemoi-inference). In the [following notebook](run_AIFS_ENS_v1.ipynb), a 
+step-by-step workflow is specified to run the AIFS using the HuggingFace model:
+
+1. **Install Required Packages and Imports**
+2. **Retrieve Initial Conditions from ECMWF Open Data**
+  - Select a date
+  - Get the data from the [ECMWF Open Data API](https://www.ecmwf.int/en/forecasts/datasets/open-data)
+  - Get input fields
+  - Add the single levels fields and pressure levels fields
+  - Convert geopotential height into geopotential
+  - Create the initial state
+3. **Load the Model and Run the Forecast** 
+  - Download the Model's Checkpoint from Hugging Face
+  - Create a runner
+  - Run the forecast using anemoi-inference
+4. **Inspect the generated forecast**
+  - Plot a field
+
+
+🚨  **Note** we train AIFS using `flash_attention` (https://github.com/Dao-AILab/flash-attention).
+The use of 'Flash Attention' package also imposes certain requirements in terms of software and hardware. Those can be found under #Installation and Features in https://github.com/Dao-AILab/flash-attention
+
+🚨 **Note** the `aifs_ens_v1.0.ckpt` checkpoint just contains the model’s weights. 
+That file does not contain any information about the optimizer states, lr-scheduler states, etc.
+
+
+
+## Citation
+
+<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
+
+If you use this model in your work, please cite it as follows:
+
+**BibTeX:**
+
+```
+@misc{lang2024aifscrps,
+      title={AIFS-CRPS: Ensemble forecasting using a model trained with a loss function based on the Continuous Ranked Probability Score}, 
+      author={Simon Lang and Mihai Alexe and Mariana C. A. Clare and Christopher Roberts and Rilwan Adewoyin and Zied Ben Bouallègue and Matthew Chantry and Jesper Dramsch and Peter D. Dueben and Sara Hahner and Pedro Maciel and Ana Prieto-Nemesio and Cathal O'Brien and Florian Pinault and Jan Polster and Baudouin Raoult and Steffen Tietsche and Martin Leutbecher},
+      year={2024},
+      eprint={2412.15832},
+      archivePrefix={arXiv},
+      primaryClass={physics.ao-ph},
+      url={https://arxiv.org/abs/2412.15832}, 
+}
+
+```
+
+**APA:**
+
+```
+Lang, S., Alexe, M., Clare, M. C., Roberts, C., Adewoyin, R., Bouallègue, Z. B., ... & Leutbecher, M. (2024). AIFS-CRPS: Ensemble forecasting using a model trained with a loss function based on the Continuous Ranked Probability Score. arXiv preprint arXiv:2412.15832.
+
+```
+
+
+## More Information
+
+[Find the paper here](https://arxiv.org/pdf/2412.15832)
+