Update README.md

README.md

@@ -5,62 +5,72 @@ language:
 tags:
 - climate
 ---
-# Convection Parameterization in CAM
 
-Note that this repository and code is still work in progress and undergoing significant development.
-Once a useable release is produced it will be tagged.
+# CAM-ML-YOG-v0: Machine Learning-based Convection Parameterization
 
-## Description
-This repository contains code as part of an effort to deploy machine learning (ML) models of geophysical parameterisations into the [Community Earth System Model (CESM)](https://www.cesm.ucar.edu/).
-This work is part of the [M<sup>2</sup>LInES](https://m2lines.github.io/) project aiming to improve performance of climate models using ML models for subgrid parameterizations.
+This repository contains a machine learning-based implementation of the convection parameterization in CAM (Community Atmosphere Model), leveraging PyTorch.
 
-A Neural Net providing a subgrid parameterization of atmospheric convection in a [single column model](https://www.arm.gov/publications/proceedings/conf04/extended_abs/randall_da.pdf) has been developed and successfully deployed as part of an atmospheric simulation.
-The work is described in a [GRL paper](https://agupubs.onlinelibrary.wiley.com/doi/10.1029/2020GL091363) with [accompanying code available](https://github.com/yaniyuval/Neural_nework_parameterization/tree/v.1.0.3). The repository contains the neural net and its implementation into a simple system for atmospheric modelling, [SAM](http://rossby.msrc.sunysb.edu/~marat/SAM.html).
+## Model Overview
+The model is a PyTorch adaptation of the original Fortran-based convection parameterization in CAM. It simulates subgrid-scale convection processes within a climate model and was developed to improve accuracy and efficiency.
 
-The aims of this repository are to:
-1. develop a standalone fortran module based on this neural net that can be used elsewhere,
-2. deploy the module in another atmospheric model, and
-3. evaluate its performance.
+### Key Features:
+- **Architecture**: The model is built with custom neural network layers as seen in [torch_nets/models.py](https://github.com/m2lines/convection-parameterization-in-CAM/blob/main/torch_nets/models.py).
+- **Data Handling**: Fortran-derived model weights are seamlessly converted to PyTorch, ensuring compatibility with existing CAM configurations.
+- **Training and Fine-tuning**: The model can be retrained or fine-tuned using custom climate data.
 
-We may also perform an investigation into interfacing the pytorch implementation of the Neural Net using the [pytorch-fortran bridging code](https://github.com/Cambridge-ICCS/fortran-pytorch-lib) developed at the [Institute of Computing for Climate Science](https://cambridge-iccs.github.io/).
+## Model Conversion and Upload
+This model was converted from the original CAM implementation by extracting the weights from Fortran and converting them into a PyTorch-compatible format. This conversion process involved the following steps:
+1. **Extract Fortran Weights**: Weights were extracted from the original CAM Fortran implementation.
+2. **Convert to PyTorch**: Using custom scripts, the weights were converted into a format compatible with PyTorch models.
+3. **Upload to Hugging Face**: The model was validated and uploaded to the Hugging Face Model Hub.
 
-The model will first be deployed into the [Single Column Atmospheric Model (SCAM)](https://www.cesm.ucar.edu/models/simple/scam) - a single column version of the CESM.
-We plan to evaluate performance using SCAM in the gateIII configuration for tropical convection in a similar manner described by the [SCAM6 pulication in JAMES](https://agupubs.onlinelibrary.wiley.com/doi/10.1029/2018MS001578).
-This will compare model performance to data from an intense observation period (IOP) described in an [AMS publication](https://journals.ametsoc.org/view/journals/atsc/36/1/1520-0469_1979_036_0053_saposs_2_0_co_2.xml).
+## Usage
 
-Long term developments of this project will seek to re-deploy more complex ML parameterizations into mode complex atmospheric models such as the [Community Atmospheric Model (CAM)](https://www.cesm.ucar.edu/models/cam) part of the CESM.
+To use the model in PyTorch, first install the necessary dependencies:
 
-
-## Repository structure
-
-```
-├── NN_module
-│   └── ...
-└── torch_nets
-    └── ...
+```bash
+pip install torch huggingface_hub
 ```
 
+Then, download and load the model as follows:
 
+```python
+from huggingface_hub import hf_hub_download
+import torch
 
-### Contents
+# Download model weights
+model_path = hf_hub_download(repo_id="ICCS/cam-ml-yog-v0", filename="model.pth")
 
-### `NN_module/`
-This folder contains the fortran neural net extracted from the [code referenced above](https://github.com/yaniyuval/Neural_nework_parameterization/tree/v.1.0.3), along with any dependencies, that may be compiled as a standalone fortran module.
+# Load model (replace 'YourModel' with the appropriate model class from torch_nets/models.py)
+model = YourModel()
+model.load_state_dict(torch.load(model_path))
+model.eval()
 
-Currently there is code that can be built on CSD3 using the included shell script.
+# Use the model for predictions
+input_data = ...  # Prepare your climate input data
+output = model(input_data)
+```
 
-This now needs cleaning up, testing, and a proper makefile creating (see open issues #9 and #10).
+### Fine-tuning
 
-### ``torch_nets/``
-The directory contains the PyTorch versions of the neural networks we are interested in.
+The model is designed to be easily fine-tuned using domain-specific climate data:
 
+```python
+# Fine-tune the model
+optimizer = torch.optim.Adam(model.parameters(), lr=1e-4)
+loss_fn = torch.nn.MSELoss()
 
-## Contributing
+# Example training loop
+for epoch in range(epochs):
+    optimizer.zero_grad()
+    output = model(input_data)
+    loss = loss_fn(output, target_data)
+    loss.backward()
+    optimizer.step()
+```
 
-This repository is currently private as it is new and work in progress.
-Open tickets can be viewed at ['Issues'](https://github.com/m2lines/convection-parameterization-in-CAM/issues).
+## Weight Updates
+Please note that weight updates may be necessary as improvements are made to the model (see [Issue #66](https://github.com/m2lines/convection-parameterization-in-CAM/issues/66)).
 
-To contribute find a relevant issue or open a new one and assign yourself to work on it.
-Then create a branch in which to add your contribution and open a pull request.
-Once ready assign a reviewer and request a code review.
-Merging should _only_ be performed once a code review has taken place.
+## References
+For more details on the original implementation and how to contribute to the model’s development, see the [GitHub repository](https://github.com/m2lines/convection-parameterization-in-CAM).