⛈️ LFRic-Atmosphere-Training

This repository hosts the materials for self-learning of the Momentum LFRic Atmosphere. This training is designed to provide an introductory level training for the LFRic Atmospheric model and its associated workflows. The training material includes an overview about the model, development working practices, visualisation of mesh data, LFRic based Science Configurations, and practical exercises for hands-on learning.

The training is structured to cater to users with different levels of expertise, from beginners to advanced users. It covers essential aspects like understanding model input and output files, navigating code repositories, and running model configurations. The goal is to make the training accessible and beneficial for all Momentum users, ensuring they can effectively use the LFRic Atmosphere model.

The LFRic Atmosphere self-learning training can be found at https://metoffice.github.io/LFRic-Atmosphere-Training

📜 I want to contribute

Contributing Guidelines

The following links are here to help set clear expectations for everyone contributing to this project. By working together under a shared understanding, we can continuously improve the project while creating a friendly, inclusive space for all contributors.

Contributors Licence Agreement

Please see the Momentum Contributors Licence Agreement.

Agreement of the CLA can be shown by adding yourself to the CONTRIBUTORS file alongside this one, and is a requirement for contributing to this project.

Code of Conduct

Please be aware of and follow the Momentum Code of Conduct.

Written Style and Restructured Text Quality

When updating this training material, aim for clear and easy-to-understand content. Please keep in mind that this training is intended for an introductory level training.

The repository's continuous integration runs tests for:

• PA11y accessibility standards
• doc8 rst standards - you are encouraged to use doc8 before committing changes. How to check your work

Developing Content - How To Guide

Version Control

The preferred way to contribute to LFRic-Atmosphere-Training is to fork the main repository, then submit a "pull request" (PR).

To create a fork under your own account. Use the following commands to clone the correct repository and create a latest branch pointing to the main branch in this repository.

How clone this repository.

When creating new branches use the latest branch as the parent branch unless a feature branch exists.

# Clone your forked repository into a LFRic-Atmosphere-Training folder
git clone https://github.com/<GITHUB-USERNAME>/LFRic-Atmosphere-Training.git

cd LFRic-Atmosphere-Training

# Add the MetOffice LFRic-Atmosphere-Training repository as an upstream remote
git remote add upstream https://github.com/MetOffice/LFRic-Atmosphere-Training.git

# This gets all the updates from all your remotes (your fork and the central repository)
git fetch --all

# This creates a new branch called latest which follows upstream/main and checks it out.
git checkout upstream/main -b latest

# And to prevent accidentally pushing to upstream/main...
git remote set-url --push upstream no_push

# And to prevent pushing your origin/main branch to unwanted places...
git branch -D main

Development Environment

Dependencies are defined in pyproject.toml. There are two possible setup methods, uv and venv + pip, you only need to use one.

Route 1: uv

How to use UV to work with this repository.

Install `uv` if needed:

python3 -m pip install --user uv

Create or update the project virtual environment (documentation dependencies only):

uv sync --python 3.11

Install optional extras as needed:

# Notebook and exercise dependencies
uv sync --extra notebooks

# Development tooling (e.g., pre-commit hooks)
uv sync --extra dev

# Both optional groups
uv sync --extra notebooks --extra dev

# Everything defined in pyproject.toml optional dependencies
uv sync --all-extras

Activate the environment:

source .venv/bin/activate

If you prefer not to activate the environment, run commands with uv run ... instead.

Route 2: venv/conda + pip

How to use venv/conda and pip to work with this repository.

Create and activate a virtual environment:

# With venv
/path/to/python3.11+ -m venv .venv
source .venv/bin/activate

# With Conda
conda create -n lfric-workflow python=3.12 pip
conda activate lfric-workflow

Install dependencies:

pip install .

Install optional dependencies:

pip install ".[notebooks,dev]"

If you are contributing and want an editable install:

pip install -e ".[notebooks,dev]"

Dependency Policy

• Build environments from pyproject.toml only.
• If dependency updates are needed, update constraints in pyproject.toml and recreate the environment with your selected setup route.

Restructured Text Standards

Rather than writing our own list of rules we use doc8 rst standards.

You may wish to familiarize yourself with these standards from the documentation, but many people find it easier to learn by running the doc8 linter on your work:

doc8 source/

Note

doc8 requires you to have installed doc8 with pip install -e ".[dev]" or uv sync --extra dev.

Building Training Materials

The training materials are based on Sphinx and can be built using the provided Makefile on any desired target format. However, we aim to display the content as HTML pages, and any contributions should ensure these are produced correctly.

To build the LFRic Atmosphere training materials in HTML format run the following command:

# If you are using uv:
uv run make clean html linkcheck

# If you are using venv + pip:
make clean html linkcheck

That concludes the process! You’ll find the generated HTML files within the “build” folder.

Note

You may find it useful to install sphinx-autobuild and develop documentation in an editor while running sphinx-autobuild source/ build/ in a terminal window.

Using Intersphinx Links

Intersphinx has been enabled between these docs and other key LFRic documentation built with Sphinx. To see a full list of references available run:

./etc/bin/intersphinx_reference.py

# Or pipe to a file that you can search in your editor.
./etc/bin/intersphinx_reference.py > intersphinx.ref

Pull Request (PR) Process

1. Create a well-documented PR with a description of changes.
2. Request reviews from the Momentum Partnership Team or other maintainers.
3. Respond to feedback and make changes if required.
4. Wait for approval and merging.

Contacts

If you want to get in contact with us don't hesitate to email the Momentum Partnership Team.