Converted .md to .rst, Removed useless text, and Added details descri…

README.rst

@@ -0,0 +1,74 @@
+Philosophy
+===============
+**Important note: at the moment, lots of code is purely being duplicated, because the focus has been made on the use-case (UC) content. Future works will refactor a bit the repository content to really abstract mutualizable data processing logic.**
+
+This project contains a collection of models developed by the Atos AI4sim R&D team and is intended for research purposes. The current workflow is based entirely on NumPy, PyTorch, PyG and Lightning. 
+
+To take care of the boiler-plate, early stopping, and tensorboard logging, training parallelization, we integrate directly with PyTorch Lightning. For each new UC, we use the same file structure. In all the following data, an experiment designates a specific training run with a specific model and a specific dataset + split.
+
+* `configs/` contains the experiments configuration files, following the Lightning CLI format. 
+* `data/` contains the `raw` and `processed` data directories, and normalization factors and explicit train/val/test split sets.
+* `tests/` contains unit tests modules.
+* `notebooks/` contains example Jupyter notebooks, to illustrate the use case code usage.
+* `config.py` exposes global paths and path specific to the current experiment.
+* `data.py` deals with dataset and datamodule creation.
+* `models.py` deals with model and module creation, including training logic.
+* `plotters.py` takes care of plots generation for the test set.
+* `trainer.py` is the main entrypoint responsible for creating a Trainer object, a CLI, and saving artifacts in the experiment directory.
+* `noxfile.py` is the Nox build tool configuration file that defines all targets available for the UC.
+
+Collections
+===============
+Collections are developed through partnerships with the ECMWF, the CERFACS, and INRIA.
+
+* Combustion
+
+    - CNF for Combustion and Flame
+    - R2 and R3 are simulations of Aachen's flame, with different resolution
+
+* Weather Forecast
+
+    - Gravity Wave Drag
+    - 3D Bias Correction
+
+* WMED, Atmosphere-Oceanic Coupling
+
+Quick Start
+===============
+Each UC can be experimented in an easy and quick way using predifined command exposed through the Nox tool.
+
+Requirements
+-----------------
+The following procedures only require [Nox](https://nox.thea.codes/en/stable/) is a python build tool, that allows to define targets (in a similar way that Make does), to simplify command execution in development and CI/CD pipeline. By default, each nox target is executed, in a specific virtualenv that ensure code partitioning and experiments reproducibility.
+::
+    pip install nox
+
+Experiment a use case
+-----------------
+Several Nox targets allow to handle easily an experimentation of any use case on a demo dataset and configuration.
+
+Choose the _Model Collection_ use case you want to experiment and go in.
+::
+    cd weather_forcast/gwd
+There you can display the list of the available targets with 
+::
+    nox --list
+
+Please note, some of them are experimentation oriented, while other ones are CI/CD oriented.
+
+*Coming soon ...*
+
+You can launch a demo training on the model use case with ``nox -s train``
+
+Development mode
+-----------------
+The nox target are also very useful to launch generic command during development phase.
+
+Run unit tests
+~~~~~~~~~~~~~~~~~~~~~~
+You can run the whole unit test suite of a use case, using ``pytest``, with ``nox -s tests``.
+This target also prints out the coverage report and save a xml version in ``.ci-reports/``.
+
+Run linting
+~~~~~~~~~~~~~~~~~~~~~~
+You can run the python linting of the code use case, using ``flake8``, with ``nox -s lint``.

combustion/README.rst

@@ -0,0 +1,17 @@
+CNF Use-Case
+===============
+The following is an effort to improve sub-grid scale LES models for combustion using artificial intelligence. This work is made under the RAISE european project: https://www.coe-raise.eu/
+
+Description
+-----------------
+In the combustion community, the determination of the sub-grid scale contribution to the filtered reaction rate in reacting flows Large Eddy Simulation (LES) is an example of closure problem that has been daunting for a long time. A new approach is proposed for premixed turbulent combustion modeling based on convolutional neural networks by reformulating the problem of subgrid flame surface density estimation as a machine learning task.  In order to train a neural network for this task, a Direct Numerical Simulation (DNS) and the equivalent LES obtained by a spatial filtering of this DNS is needed.
+In a first step, two DNS of a methane-air slot burner are run and then filtered to create the training dataset. Models are trained on this data in a supervised manner. In a second step, a new, unseen and more difficult case was used to ensure network capabilities.
+This third DNS is a short-term transient started from the last field of the second DNS, where inlet velocity is doubled, going from 10 to 20 m/s for 1 ms, and then set back to its original value for 2 more ms.
+
+Dataset
+-----------------
+The dataset can be (downloaded here)[https://www.coe-raise.eu/open-data], which contains 113 scalar fields for a progress variable (input) and the target value of the flame surface density (output) used in for a LES combustion model. Those fields are obtained from DNS simulations and filtered to match a typical LES simulation. More details on how the dataset is created (in this paper)[https://arxiv.org/abs/1810.03691].
+
+Models 
+-----------------
+This problem is approached two ways: via CNNs and with GNNs. A 3D U-net approach is used first to match the Lapeyre's paper. However, CNNs are hardly applicable in complex non-structured grids. GNNs, however, are more suitable for working with unstructured, complex geometries. 

weather_forecast/gwd/README.rst

@@ -0,0 +1,29 @@
+Gravity Wave Drag UC
+===============
+
+Description
+-----------------
+Climate models are complex objects developed over decades and have many components. While the main model renders dynamics (Temperature, Wind speeds, Pressure), models of lesser magnitude substantially refine these predictions by emulating physical processes: radiation, precipitation, evaporation, clouds, as well as Gravity Wave Drag. It caracterizes a phenomenon of vertical propagation of the relief which affects the wind speed over all layers of the atmosphere.
+
+The objective is to substitute the parametrization scheme used in production by a DL model much more efficient at a close-enough accuracy. This experiment is largely inspired from the [work of Chantry et al.](https://agupubs.onlinelibrary.wiley.com/doi/pdfdirect/10.1029/2021MS002477). 
+
+Dataset
+-----------------
+Download the dataset using the Climetlab library developed by ECMWF. An example on how to retrieve the data is largely explained [here](https://git.ecmwf.int/projects/MLFET/repos/maelstrom-nogwd/browse).
+
+Models
+-----------------
+X:
+* ``u``, ``v`` the horizontal wind velocities
+* ``T`` the temperature
+* ``p`` the pressure
+* ``g`` the geopotential
+* 4 surface params that describe the subscale orography
+
+Y:
+* ``u_t``, ``v_t`` as the gravity-wave drag tendencies
+* ``b_f_t`` as the blocking drag tendencies
+
+Two approaches were considered:
+1. An MLP based on the work from Chantry et al., with the DoF
+2. A 1D-CNN that swipes from lower to upper layer of the atmosphere