Installation and Build

Installation and Build

Installation of FTorch is performed using the CMake build system. This is controlled by the CMakeLists.txt file in the root FTorch directory.

• Dependencies
• Basic Installation Instructions
• CMake Build Options
• Building FTorch as a Shared vs. Static library

Dependencies

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

• CMake >= 3.18
• Fortran (2008 standard compliant), C++ (must fully support C++17), and C compilers
• LibTorch¹ or PyTorch
• TorchVision and NumPy (required for examples)

For instructions on how to install PyTorch, TorchVision, and NumPy, see the Python dependencies section below.

For instructions on how to install PyTorch and additional Python dependencies for FTorch's examples, see the Python dependencies section below.

Python dependencies

If LibTorch is not installed then FTorch requires PyTorch to be installed. FTorch's pt2ts utility script has PyTorch as a hard requirement, as well as the ftorch_utils Python module included in the FTorch repo. To install PyTorch and ftorch_utils, run

pip install . --extra-index-url <pytorch-wheel-download-url>

where <pytorch-wheel-download-url> is determined based on the matrix on the PyTorch website.

We recommend also installing the additional dependencies for FTorch's examples (TorchVision, matplotlib, NumPy, and mpi4py) in the same command. This can be achieved by including the examples optional dependencies, as follows:

pip install .[examples] --extra-index-url <pytorch-wheel-download-url>

If you don't want to install ftorch_utils then you can install FTorch's torch and torchvision dependencies using

pip install torch torchvision --index-url <pytorch-wheel-download-url>

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. See the Python dependencies section above for details on how to do this.
• Other Python modules are installed automatically upon building specific tests, namely mpi4py for the MPI example.

Basic Installation Instructions

The following instructions assume a Unix system. For installation on Windows, Apple Silicon, Conda Environments, or Codespaces refer to the system-specific guidance as the process may differ.

To build the library, first clone it from GitHub to your local machine using either ssh:

git clone git@github.com:Cambridge-ICCS/FTorch.git

or https:

git clone https://github.com/Cambridge-ICCS/FTorch.git

Then navigate to the FTorch directory and create a build directory:

cd FTorch
mkdir build
cd build

From here invoke CMake with the Release build type option, plus any other options as required from the table below. Note: you will likely need to provide at least the CMAKE_PREFIX_PATH flag plus any other options to enforce a consistent build on your machine:

cmake .. -DCMAKE_BUILD_TYPE=Release

Finally build and install the library using:

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:

• include/ - contains C header and Fortran mod files
• lib/ - contains cmake directory and .so/.a files
  Note: Depending on your system and architecture lib may be lib64, and you may have .dll files or similar.

CMake build options

The following CMake flags are available and can be passed as arguments through -D<Option>=<Value> in order to tailor your build:

For example, to build using the GNU compilers and install to $HOME/FTorchbin/ we would need to run:

cmake .. \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_Fortran_COMPILER=gfortran \
-DCMAKE_C_COMPILER=gcc \
-DCMAKE_CXX_COMPILER=g++ \
-DCMAKE_PREFIX_PATH=/path/to/venv/lib/python3.xx/site-packages/torch/ \
-DCMAKE_INSTALL_PREFIX=~/FTorchbin

Once this completes you should be able to generate the code and install using:

cmake --build . --target install

Building FTorch as a Shared vs. Static library

FTorch can be built as either a shared or static library depending on how you want to link it with your own application.

By default, FTorch builds as a shared library:

cmake -DBUILD_SHARED_LIBS=ON ...

This configuration dynamically links FTorch with its dependencies (including LibTorch) at runtime. A shared build is recommended for most users because:

• Multiple programs can use the same FTorch installation.
• You can update FTorch without recompiling dependent executables.

If you prefer to include FTorch directly inside your executable, you can build it statically:

cmake -DBUILD_SHARED_LIBS=OFF ...

A static build links all FTorch code directly into your application executable. This can be useful when:

• You want a single self-contained executable.
• You are installing FTorch on an HPC system and intend to use it in an application for which you want maximum reproducibility (i.e., the FTorch version embedded in your application is "frozen").

To this second point on building FTorch as a static library, a brief justification on applications for which this may be relevant is covered here.

For more general details on shared and static libraries as well as their trade-offs, see shared vs. static libraries, a case for static linking, and static linking considered harmful