FTorch

A library for coupling (Py)Torch machine learning models to Fortran

This repository contains code, utilities, and examples for directly calling PyTorch ML models from Fortran.

For full API and user documentation please see the online documentation which is significantly more detailed than this README.

To cite use of this code please refer to Atkinson et al., (2025) DOI:10.21105/joss.07602. See acknowledgment below for more details.

Contents

• Description
• Installation
• Usage
• GPU Support
• Examples
• License
• Contributions
• Authors and Acknowledgment
• Users

Description

It is desirable to be able to run machine learning (ML) models directly in Fortran. Such models are often trained in some other language (say Python) using popular frameworks (say PyTorch) and saved. We want to run inference on this model without having to call a Python executable. To achieve this we use the existing Torch C++ interface.

This project provides a library enabling a user to directly couple their PyTorch models to Fortran code. We provide installation instructions for the library as well as instructions and examples for performing coupling.

```fortran use ftorch ... type(torchmodel) :: model type(torchtensor), dimension(ninputs) :: modelinputsarr type(torchtensor), dimension(noutputs) :: modeloutputarr ... call torchmodelload(model, "/my/saved/TorchScript/model.pt", torchkCPU) call torchtensorfromarray(modelinputsarr(1), inputfortran, inlayout, torchkCPU) call torchtensorfromarray(modeloutputarr(1), outputfortran, outlayout, torchkCPU)

call torchmodelforward(model, modelinputarr, modeloutputarr) ```

The following presentations provide an introduction and overview of FTorch:

• Coupling Machine Learning to Numerical (Climate) Models\ Platform for Advanced Scientific Computing, Zurich - June 2024\ Slides
• Blending Machine Learning and Numerical Simulation, with Applications to Climate Modelling\ Durham HPC days, Durham - May 2024\ Slides
• Reducing the overheads for coupling PyTorch machine learning models to Fortran\ ML & DL Seminars, LSCE, IPSL, Paris - November 2023\ Slides - Recording
• Reducing the Overhead of Coupled Machine Learning Models between Python and Fortran\ RSECon23, Swansea - September 2023\ Slides - Recording

If you are interested in using this library please get in touch.

For a similar approach to calling TensorFlow models from Fortran please see Fortran-TF-lib.

Installation

Dependencies

To install the library requires the following to be installed on the system:

• CMake >= 3.15
• LibTorch<sup>*</sup> or PyTorch
• Fortran (2008 standard compliant), C++ (must fully support C++17), and C compilers

<sup>*</sup> The minimal example provided downloads the CPU-only Linux Nightly binary. Alternative versions may be required.

Additional dependencies of the test suite

FTorch's test suite has some additional dependencies.

• You will also need to install the unit testing framework pFUnit.
• FTorch's test suite requires that PyTorch has been installed, as opposed to LibTorch. We recommend installing torchvision in the same command (e.g., pip install torch torchvision)<sup>*</sup>. Doing so ensures that torch and torchvision are configured in the same way.
• Other Python modules are installed automatically upon building the tests.

<sup>*</sup> For more details, see here.

Windows Support

If building in a Windows environment then you can either use Windows Subsystem for Linux (WSL) or Visual Studio and the Intel Fortran Compiler. For full details on the process see the online Windows documentation.\ Note that LibTorch is not supported for the GNU Fortran compiler with MinGW.

Apple Silicon Support

At the time of writing there are issues building FTorch on Apple Silicon when linking to downloaded LibTorch binaries or pip-installed PyTorch. FTorch can successfully be built, including utilising the MPS backend, from inside a conda environment using the environment files and instructions in conda/.

Conda Support

Conda is not our preferred approach for managing dependencies, but for users who want an environment to build FTorch in we provide guidance and environment files in conda/. Note that these are not minimal and will install Python, PyTorch, and modules required for running the tests and examples.

GitHub Codespace

It is possible to try FTorch through an interactive browser session using GitHub Codespace. Full instructions are in the codespace/ directory.

Library installation

For detailed installation instructions please see the online installation documentation.

To build and install the library:

1. Navigate to the location in which you wish to install the source and run:
   git clone git@github.com:Cambridge-ICCS/FTorch.git to clone via ssh, or
   git clone https://github.com/Cambridge-ICCS/FTorch.git to clone via https.
   
2. Navigate to the root FTorch directory by running:
   cd FTorch/

3. Build the library using CMake with the relevant options from the table below:
   mkdir build cd build cmake .. -DCMAKE_BUILD_TYPE=Release

   The following table of CMake options are available to be passed as arguments to cmake through -D<Option>=<Value>.
   It is likely that you will need to provide at least CMAKE_PREFIX_PATH.
   | Option | Value | Description | | ------------------------------------------------------------------------------------------------- | ---------------------------- | -------------------------------------------------------------- | | CMAKE_Fortran_COMPILER | gfortran / ifx / ifort | Specify a Fortran compiler to build the library with. This should match the Fortran compiler you're using to build the code you are calling this library from.<sup>1</sup> | | CMAKE_C_COMPILER | gcc / icx / icc | Specify a C compiler to build the library with.<sup>1</sup> | | CMAKE_CXX_COMPILER | g++ / icx / icpc | Specify a C++ compiler to build the library with.<sup>1</sup> | | CMAKE_PREFIX_PATH | </path/to/LibTorch/> | Location of Torch installation<sup>2</sup> | | CMAKE_INSTALL_PREFIX | </path/to/install/lib/at/> | Location at which the library files should be installed. By default this is /usr/local | | CMAKE_BUILD_TYPE | Release / Debug | Specifies build type. The default is Debug, use Release for production code | | CMAKE_BUILD_TESTS | TRUE / FALSE | Specifies whether to compile FTorch's test suite as part of the build. | | GPU_DEVICE | NONE / CUDA / HIP / XPU / MPS | Specifies the target GPU backend architecture (if any) <sup>3</sup> | | MULTI_GPU | ON / OFF | Specifies whether to build the tests that involve multiple GPU devices (ON by default if CMAKE_BUILD_TESTS and GPU_DEVICE are set). |

   <sup>1</sup> On Windows this may need to be the full path to the compiler if CMake cannot locate it by default.

   <sup>2</sup> The path to the Torch installation needs to allow CMake to locate the relevant Torch CMake files.
   If Torch has been installed as LibTorch then this should be the absolute path to the unzipped LibTorch distribution. If Torch has been installed as PyTorch in a Python venv (virtual environment), e.g. with pip install torch, then this should be </path/to/venv/>lib/python<3.xx>/site-packages/torch/.
   You can find the location of your torch install by importing torch from your Python environment (import torch) and running `print(torch.file)`

   <sup>3</sup> This is often overridden by PyTorch. When installing with pip, the index-url flag can be used to ensure a CPU-only or GPU-enabled version is installed, e.g. pip install torch --index-url https://download.pytorch.org/whl/cpu. URLs for alternative versions can be found here.

4. Make and install the library to the desired location with either: cmake --build . --target install or, if you want to separate these steps: cmake --build . cmake --install .

Note: If using a machine capable of running multiple jobs this can be sped up by adding --parallel [<jobs>] or -j [<jobs>] to the cmake build command. See the CMake documentation for more information.

Installation will place the following directories at the install location:  
* `CMAKE_INSTALL_PREFIX/include/` - contains header and mod files
* `CMAKE_INSTALL_PREFIX/lib/` - contains `cmake` directory and `.so` files  
_Note: depending on your system and architecture `lib` may be `lib64`, and 
you may have `.dll` files or similar._  
_Note: In a Windows environment this will require administrator privileges for the default install location._

Usage

In order to use FTorch users will typically need to follow these steps:

1. Save a PyTorch model as TorchScript.
2. Write Fortran using the FTorch bindings to use the model from within Fortran.
3. Build and compile the code, linking against the FTorch library

These steps are described in more detail in the online documentation

GPU Support

To run on GPU requires an installation of LibTorch compatible for the GPU device you wish to target (using the GPU_DEVICE CMake option as detailed in the table above) and two main adaptations to the code:

1. When saving a TorchScript model, ensure that it is on the appropriate GPU device type. The pt2ts.py script has a command line argument --device_type, which currently accepts 5 different device types: cpu (default), cuda, hip, xpu, or mps.
2. When using FTorch in Fortran, set the device for the input tensor(s) to the appropriate GPU device type, rather than torch_kCPU. There are currently three options: torch_kCUDA, torch_kHIP, torch_kXPU, or torch_kMPS.

For detailed guidance about running on GPU, including instructions for using multiple devices, please see the online GPU documentation.

Large tensor support

If your code uses large tensors (where large means more than 2,147,483,647 elements in any one dimension (the maximum value of a 32-bit integer)), you may need to compile ftorch with 64-bit integers. For information on how to do this, please see our FAQ

Examples

Examples of how to use this library are provided in the examples directory.
They demonstrate different functionalities of the code and are provided with instructions to modify, build, and run as necessary.

Tests

For information on testing, see the corresponding webpage or the README in the test subdirectory.

License

Copyright © ICCS

FTorch is distributed under the MIT Licence.

Contributions

Contributions and collaborations are welcome.

For bugs, feature requests, and clear suggestions for improvement please open an issue.

If you have built something upon FTorch that would be useful to others, or can address an open issue, please fork the repository and open a pull request.

Detailed guidelines can be found in the online developer documentation.

Code of Conduct

Everyone participating in the FTorch project, and in particular in the issue tracker, pull requests, and social media activity, is expected to treat other people with respect and, more generally, to follow the guidelines articulated in the Python Community Code of Conduct.

Authors and Acknowledgment

FTorch is written and maintained by the ICCS

To cite FTorch in research please refer to:

Atkinson et al., (2025). FTorch: a library for coupling PyTorch models to Fortran. Journal of Open Source Software, 10(107), 7602, https://doi.org/10.21105/joss.07602

See the CITATION.cff file or click 'Cite this repository' on the right.

See Contributors for a full list of contributors.

Used by

The following projects make use of this code or derivatives in some way:

• DataWave CAM-GW
• DataWave - MiMA ML\ See Mansfield and Sheshadri (2024) - DOI: 10.1029/2024MS004292
• Convection parameterisations in ICON\ See Heuer et al. (2024) - DOI: 10.1029/2024MS004398
• To replace a BiCGStab bottleneck in the GloSea6 Seasonal Forecasting model\ See Park and Chung (2025) - DOI: 10.3390/atmos16010060
• Emulation of cloud resolving models to reduce computational cost in E3SM\ See Hu et al. (2025) - DOI: 10.1029/2024MS004618 (and code)

Are we missing anyone? Let us know.