This repository contains documentation, resources, and code for a workshop teaching the use of the ICCS FTorch library for coupling PyTorch models to Fortran code. The session has been designed and delivered by Jack Atkinson (@jatkinson1000), Joe Wallwork (@jwallwork23) and Tom Meltzer (@tommelt) and has been taught at the following workshops/summer schools ICCS '24, ICCS '25, Durham HPC Days 2025 and at the Department of Atmospheric, Oceanic, and Planetary Physics at the University of Oxford. All materials are available such that individuals can cover the course in their own time.
- Learning objectives
- Teaching material
- Prerequisites
- Preparation
- Installation and setup
- License information
- Contribution guidelines and support
The key learning objective from this workshop could be simply summarised as:
Provide the ability to couple PyTorch models to Fortran using FTorch.
However, more specifically we aim to:
- provide a deeper understanding of Torch models and the libtorch library,
- introduce FTorch and it's aims and benefits,
- teach users the full pipeline of taking a PyTorch model and coupling it to a Fortran code,
- introduce the automatic differentiation aspects of FTorch, and
- highlight best practices and efficient use when doing the above.
The slides for this workshop can be viewed on the ICCS Summer School Website:
The slides are generated from markdown using quarto. The raw markdown and html files can be found in the slides directory.
The exercises for the course can be found in the exercises directory.
They consist of:
- Exercise 0: An introduction to Fortran and PyTorch to get up to speed
- Exercise 1: A walkthrough of how to take your net from PyTorch and use it in Fortran
- Exercise 2: A comparison of efficient and inefficient approaches to using FTorch as part of a larger numerical code
- Exercise 3: A demonstration of some of the automatic differentiation features of FTorch
Between exercises 0 and 1 we will also walk through building and installing FTorch,
details for which can be found in the slides and in the build_FTorch.sh
script.
To get the most out of the session we assume a basic understanding in a few areas and for you to do some preparation in advance. Expected knowledge is outlined below, along with resources for reading if you are unfamiliar.
The course uses some elements of Python and assumes some basic knowledge of the ecosystem. This includes:
- use of a python virtual environment,
- installation of dependencies, and
- running python scripts from the command line.
Whilst we are using PyTorch and neural networks in this course we will not be teaching any formal concepts.
- We recommend the video series by 3Blue1Brown, at least chapters 1-3, for an awareness of high-level deep-learning concepts, though this is not essential.
- For an understanding of PyTorch we recommend the Practical Machine Learning with PyTorch workshop (Atkinson and Denholm (2024)) materials for which are available online at github/Cambridge-ICCS/practical-ml-with-pytorch.
The key objective of this course is to call PyTorch code from within Fortran. However, expert knowledge is not a prerequisite. Rather, we will assume that you are comfortable reading Fortran code and familiar with the basic concepts of the language (variables, subroutines, modules etc.) To this end Fortran-Lang provide an excellent quickstart tutorial.
We suggest that participants follow along with the workshop by using a GitHub Codespace (GitHub login required). This allows you to work in a VSCode Web session running code on from a container in the cloud. All GitHub users have a certain number of hours of credit for using codespaces. This can be extended if you have GitHub Education.
To launch a codespace for the workshop navigate to the repository on Github and click the down arrow on the 'code button'. Select 'Codespaces' and then 'Create codespace on main'. This will open a new window and start up an interactive VSCode session.
Once the container is set up you will be dropped into a VSCode session with dependencies (Python, gfortran, and CMake) installed, and a copy of the workshop repository cloned.
Note
Firefox users with enhanced tracking protection will need to disable this for the codespace.
If you wish to follow this workshop on your own machine rather than using GitHub codespaces please follow the instructions below.
In preparation for the course please ensure that your computer contains the following:
- A text editor e.g. vim/neovim, gedit, vscode, sublimetext etc. to open and edit code files
- A terminal emulator e.g. GNOME Terminal, wezterm, Windows Terminal (windows only), iTerm (mac only)
- python virtual environment see Installation and setup
- Fortran, C, and C++ compilers Unless you are familiar with other options we suggest using the Gnu Compiler Collection (GCC) This is freely available, and comes as standard on many systems or is available through all good package managers.
- CMake The CMake build system is used for building FTorch. Similarly it is available online or through all good package managers.
Note
Note for Windows users: We strongly advise using the
Windows Subsystem for Linux (WSL)
for this workshop.
If you wish to proceed on native Windows please follow the specific
FTorch guidance for Windows Users
to prepare a system.
We have linked suitable applications for Windows in the above lists, though you may wish
to refer to Windows' getting-started with Python information
for a complete guide to getting set up.
If you require assistance or further information with any of these please reach out to us before a training session.
Navigate to the location you want to install this repository on your system and clone via https by running:
git clone https://github.com/Cambridge-ICCS/FTorch-workshop.git
This will create a directory FTorch-workshop/ with the contents of this repository.
Please note that if you have a GitHub account and want to preserve any work you do we suggest you first fork the repository and then clone your fork. This will allow you to push your changes and progress from the workshop back up to your fork for future reference.
Before installing any Python packages it is important to first create a Python virtual environment. This provides an insulated environment inside which we can install Python packages without polluting the operating system's Python environment.
python3 -m venv .venv
This will create a directory called .venv/ containing software for the virtual environment.
To activate the environment run:
source .venv/bin/activate
You can now work on python from within this isolated environment, installing packages as you wish without disturbing your base system environment.
When you have finished working on this project run:
deactivate
to deactivate the venv and return to the system python environment.
You can always boot back into the venv as you left it by running the activate command again.
It is now time to install the dependencies for our code, for example PyTorch.
The project has been packaged with a pyproject.toml so can be installed in one go.
From within the root directory in a active virtual environment run:
pip install .
This will download the relevant dependencies into the venv as well as setting up the datasets that we will be using in the course.
The code materials in this project are licensed under the MIT License.
The teaching materials are licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
If you spot an issue with the materials please let us know by opening an issue here on GitHub clearly describing the problem.
If you are able to fix an issue that you spot, or an existing open issue please get in touch by commenting on the issue thread.
Contributions from the community are welcome. To contribute back to the repository please first fork it, make the neccessary changes to fix the problem, and then open a pull request back to this repository clerly describing the changes you have made. We will then preform a review and merge once ready.
If you would like support using these materials, adapting them to your needs, or delivering them please get in touch either via GitHub or via ICCS.