Installation of FTorch is performed using the CMake build system.
This is controlled by the CMakeLists.txt file in the root FTorch directory.
To install FTorch requires the following to be installed on the system:
FTorch's test suite has some additional dependencies.
torchvision in
the same command (e.g., pip install torch torchvision).2 Doing so
ensures that torch and torchvision are configured in the same way.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 fileslib/ - contains cmake directory and .so/.a fileslib may be lib64, and
you may have .dll files or similar.The following CMake flags are available and can be passed as arguments through -D<Option>=<Value>
in order to tailor your build:
| 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.3 |
CMAKE_C_COMPILER |
gcc / icx / icc |
Specify a C compiler to build the library with.3 |
CMAKE_CXX_COMPILER |
g++ / icx / icpc |
Specify a C++ compiler to build the library with.3 |
CMAKE_PREFIX_PATH |
</path/to/libTorch/> |
Location of Torch installation4 |
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.5 |
GPU_DEVICE |
NONE / CUDA / HIP / XPU / MPS |
Specifies the target GPU architecture (if any)6 |
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). |
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
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:
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:
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
Note
For discussion on how to build and link another code to the FTorch library see the generic usage example, and the detailed discussion on the HPC page.
The minimal example provided downloads the CPU-only Linux Nightly binary. Alternative versions to match hardware may be required. ↩
This may need to be the full path to the compiler if CMake cannot locate it by default. ↩↩↩
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__) ↩
To run the tests, your system's MPI must support use mpi_f08.
Note that OpenMPI < v2.0 and MPICH < v3.1 do not support this module. ↩
This must match the installed PyTorch/Libtorch library. 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. ↩