This repository contains documentation, resources, and code for the a workshop
teaching use of the ICCS FTorch library
for coupling PyTorch models to Fortran code.
The session has been designed and delivered by
Jack Atkinson (@jatkinson1000)
and has been taught at the
ICCS
summer schools.
All materials are available such that individuals can cover the course in their own time.
- Learning Objectives
- Teaching material
- Preparation and prerequisites
- 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, 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.
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.
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 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.
If you have never done this before don't worry: it is very good practise, especially when you are working on multiple projects, and easy to do.
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.