Skip to content

Application development environment

What's available

ARCHER2 runs the HPE Cray Linux Environment (a version of SUSE Linux), and provides a development environment which includes:

  • Software modules via a standard module framework
  • Three different compiler environments (AMD, Cray, and GNU)
  • MPI, OpenMP, and SHMEM
  • Scientific and numerical libraries
  • Parallel Python and R
  • Parallel debugging and profiling
  • Singularity containers

Access to particular software, and particular versions, is managed by an Lmod module framework. Most software is available by loading modules, including the different compiler environments

You can see what compiler environments are available with:

auser@uan01:~> module avail PrgEnv

--------------------------------------- /opt/cray/pe/lmod/modulefiles/core ----------------------------------------
   PrgEnv-aocc/8.3.3    PrgEnv-cray/8.3.3 (L)    PrgEnv-gnu/8.3.3

  Where:
   L:  Module is loaded

Module defaults are chosen based on Find First Rules due to Name/Version/Version modules found in the module tree.
See https://lmod.readthedocs.io/en/latest/060_locating.html for details.

Use "module spider" to find all possible modules and extensions.
Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".

Other software modules can be searched using the module spider command:

auser@uan01:~> module spider

---------------------------------------------------------------------------------------------------------------
The following is a list of the modules and extensions currently available:
---------------------------------------------------------------------------------------------------------------
  PrgEnv-aocc: PrgEnv-aocc/8.3.3

  PrgEnv-cray: PrgEnv-cray/8.3.3

  PrgEnv-gnu: PrgEnv-gnu/8.3.3

  amd-uprof: amd-uprof/3.6.449

  aocc: aocc/3.2.0

  aocc-mixed: aocc-mixed/3.2.0

  aocl: aocl/3.1, aocl/4.0

  arm/forge: arm/forge/22.1.3

  atp: atp/3.14.16

  bolt: bolt/0.7, bolt/0.8

  boost: boost/1.72.0, boost/1.81.0

  castep: castep/22.11

  cce: cce/15.0.0

...output trimmed...

A full discussion of the module system is available in the Software environment section.

A consistent set of modules is loaded on login to the machine (currently PrgEnv-cray, see below). Developing applications then means selecting and loading the appropriate set of modules before starting work.

This section is aimed at code developers and will concentrate on the compilation environment, building libraries and executables, specifically parallel executables. Other topics such as Python and Containers are covered in more detail in separate sections of the documentation.

Tip

If you want to get back to the login module state without having to logout and back in again, you can just use: 

module restore
This is also handy for build scripts to ensure you are starting from a known state.

Compiler environments

There are three different compiler environments available on ARCHER2:

  • AMD Compiler Collection (AOCC)
  • GNU Compiler Collection (GCC)
  • HPE Cray Compiler Collection (CCE) (current default compiler environment)

The current compiler suite is selected via the PrgEnv module , while the specific compiler versions are determined by the relevant compiler module. A summary is:

Suite name Compiler Environment Module Compiler Version Module
CCE PrgEnv-cray cce
GCC PrgEnv-gnu gcc
AOCC PrgEnv-aocc aocc

For example, at login, the default set of modules are:

auser@ln03:~> module list

  1) craype-x86-rome                         6) cce/15.0.0             11) PrgEnv-cray/8.3.3
  2) libfabric/1.12.1.2.2.0.0                7) craype/2.7.19          12) bolt/0.8
  3) craype-network-ofi                      8) cray-dsmml/0.2.2       13) epcc-setup-env
  4) perftools-base/22.12.0                  9) cray-mpich/8.1.23      14) load-epcc-module
  5) xpmem/2.5.2-2.4_3.30__gd0f7936.shasta  10) cray-libsci/22.12.1.1

from which we see the default compiler environment is Cray (indicated by PrgEnv-cray (at 11 in the list above) and the default compiler module is cce/15.0.0 (at 6 in the list above). The compiler environment will give access to a consistent set of compiler, MPI library via cray-mpich (at 9), and other libraries e.g., cray-libsci (at 10 in the list above).

Switching between compiler environments

Switching between different compiler environments is achieved using the module load command. For example, to switch from the default HPE Cray (CCE) compiler environment to the GCC environment, you would use:

auser@ln03:~> module load PrgEnv-gnu

Lmod is automatically replacing "cce/15.0.0" with "gcc/11.2.0".


Lmod is automatically replacing "PrgEnv-cray/8.3.3" with "PrgEnv-gnu/8.3.3".


Due to MODULEPATH changes, the following have been reloaded:
  1) cray-mpich/8.1.23

If you then use the module list command, you will see that your environment has been changed to the GCC environment:

auser@ln03:~> module list

Currently Loaded Modules:
  1) craype-x86-rome                         6) bolt/0.8          11) cray-dsmml/0.2.2
  2) libfabric/1.12.1.2.2.0.0                7) epcc-setup-env    12) cray-mpich/8.1.23
  3) craype-network-ofi                      8) load-epcc-module  13) cray-libsci/22.12.1.1
  4) perftools-base/22.12.0                  9) gcc/11.2.0        14) PrgEnv-gnu/8.3.3
  5) xpmem/2.5.2-2.4_3.30__gd0f7936.shasta  10) craype/2.7.19

Switching between compiler versions

Within a given compiler environment, it is possible to swap to a different compiler version by swapping the relevant compiler module. To switch to the GNU compiler environment from the default HPE Cray compiler environment and than swap the version of GCC from the 11.2.0 default to the older 10.3.0 version, you would use

auser@ln03:~> module load PrgEnv-gnu

Lmod is automatically replacing "cce/15.0.0" with "gcc/11.2.0".


Lmod is automatically replacing "PrgEnv-cray/8.3.3" with "PrgEnv-gnu/8.3.3".


Due to MODULEPATH changes, the following have been reloaded:
  1) cray-mpich/8.1.23

auser@ln03:~> module load gcc/10.3.0

The following have been reloaded with a version change:
  1) gcc/11.2.0 => gcc/10.3.0

The first swap command moves to the GNU compiler environment and the second swap command moves to the older version of GCC. As before, module list will show that your environment has been changed:

auser@ln03:~> module list

Currently Loaded Modules:
  1) craype-x86-rome                         6) bolt/0.8          11) cray-libsci/22.12.1.1
  2) libfabric/1.12.1.2.2.0.0                7) epcc-setup-env    12) PrgEnv-gnu/8.3.3
  3) craype-network-ofi                      8) load-epcc-module  13) gcc/10.3.0
  4) perftools-base/22.12.0                  9) craype/2.7.19     14) cray-mpich/8.1.23
  5) xpmem/2.5.2-2.4_3.30__gd0f7936.shasta  10) cray-dsmml/0.2.2

Compiler wrapper scripts: cc, CC, ftn

To ensure consistent behaviour, compilation of C, C++, and Fortran source code should then take place using the appropriate compiler wrapper: cc, CC, and ftn, respectively. The wrapper will automatically call the relevant underlying compiler and add the appropriate include directories and library locations to the invocation. This typically eliminates the need to specify this additional information explicitly in the configuration stage. To see the details of the exact compiler invocation use the -craype-verbose flag to the compiler wrapper.

The default link time behaviour is also related to the current programming environment. See the section below on Linking and libraries.

Users should not, in general, invoke specific compilers at compile/link stages. In particular, gcc, which may default to /usr/bin/gcc, should not be used. The compiler wrappers cc, CC, and ftn should be used (with the underlying compiler type and version set by the module system). Other common MPI compiler wrappers e.g., mpicc, should also be replaced by the relevant wrapper, e.g. cc (commands such as mpicc are not available on ARCHER2).

Important

Always use the compiler wrappers cc, CC, and/or ftn and not a specific compiler invocation. This will ensure consistent compile/link time behaviour.

Tip

If you are using a build system such as Make or CMake then you will need to replace all occurrences of mpicc with cc, mpicxx/mpic++ with CC and mpif90 with ftn.

Compiler man pages and help

Further information on both the compiler wrappers, and the individual compilers themselves are available via the command line, and via standard man pages. The man page for the compiler wrappers is common to all programming environments, while the man page for individual compilers depends on the currently loaded programming environment. The following table summarises options for obtaining information on the compiler and compile options:

Compiler suite C C++ Fortran
Cray man clang man clang++ man crayftn
GNU man gcc man g++ man gfortran
Wrappers man cc man CC man ftn

Tip

You can also pass the --help option to any of the compilers or wrappers to get a summary of how to use them. The Cray Fortran compiler uses ftn --craype-help to access the help options.

Tip

There are no man pages for the AOCC compilers at the moment.

Tip

Cray C/C++ is based on Clang and therefore supports similar options to clang/gcc. clang --help will produce a full summary of options with Cray-specific options marked "Cray". The clang man page on ARCHER2 concentrates on these Cray extensions to the clang front end and does not provide an exhaustive description of all clang options. Cray Fortran is not based on Flang and so takes different options from flang/gfortran.

Which compiler environment?

If you are unsure which compiler you should choose, we suggest the starting point should be the GNU compiler collection (GCC, PrgEnv-gnu); this is perhaps the most commonly used by code developers, particularly in the open source software domain. A portable, standard-conforming code should (in principle) compile in any of the three compiler environments.

For users requiring specific compiler features, such as coarray Fortran, the recommended starting point would be Cray. The following sections provide further details of the different compiler environments.

Warning

Intel compilers are not currently available on ARCHER2.

GNU compiler collection (GCC)

The commonly used open source GNU compiler collection is available and provides C/C++ and Fortran compilers.

Switch the the GCC compiler environment from the default CCE (cray) compiler environment via:

auser@ln03:~> module load PrgEnv-gnu

Lmod is automatically replacing "cce/15.0.0" with "gcc/11.2.0".


Lmod is automatically replacing "PrgEnv-cray/8.3.3" with "PrgEnv-gnu/8.3.3".


Due to MODULEPATH changes, the following have been reloaded:
  1) cray-mpich/8.1.23

Warning

If you want to use GCC version 10 or greater to compile Fortran code, with the old MPI interfaces (i.e. use mpi or INCLUDE 'mpif.h') you must add the -fallow-argument-mismatch option (or equivalent) when compiling otherwise you will see compile errors associated with MPI functions. The reason for this is that past versions of gfortran have allowed mismatched arguments to external procedures (e.g., where an explicit interface is not available). This is often the case for MPI routines using the old MPI interfaces where arrays of different types are passed to, for example, MPI_Send(). This will now generate an error as not standard conforming. The -fallow-argument-mismatch option is used to reduce the error to a warning. The same effect may be achieved via -std=legacy.

If you use the Fortran 2008 MPI interface (i.e. use mpi_f08) then you should not need to add this option.

Fortran language MPI bindings are described in more detail at in the MPI Standard documentation.

Useful Gnu Fortran options

Option Comment
-O<level> Optimisation levels: -O0, -O1, -O2, -O3, -Ofast. -Ofast is not recommended without careful regression testing on numerical output.
-std=<standard> Default is gnu
-fallow-argument-mismatch Allow mismatched procedure arguments. This argument is required for compiling MPI Fortran code with GCC version 10 or greater if you are using the older MPI interfaces (see warning above)
-fbounds-check Use runtime checking of array indices
-fopenmp Compile OpenMP (default is no OpenMP)
-v Display verbose output from compiler stages

Tip

The standard in -std may be one of f95 f2003, f2008 or f2018. The default option -std=gnu is the latest Fortran standard plus gnu extensions.

Warning

Past versions of gfortran have allowed mismatched arguments to external procedures (e.g., where an explicit interface is not available). This is often the case for MPI routines where arrays of different types are passed to MPI_Send() and so on. This will now generate an error as not standard conforming. Use -fallow-argument-mismatch to reduce the error to a warning. The same effect may be achieved via -std=legacy.

Reference material

Cray Compiling Environment (CCE)

The Cray Compiling Environment (CCE) is the default compiler at the point of login. CCE supports C/C++ (along with unified parallel C UPC), and Fortran (including co-array Fortran). Support for OpenMP parallelism is available for both C/C++ and Fortran (currently OpenMP 4.5, with a number of exceptions).

The Cray C/C++ compiler is based on a clang front end, and so compiler options are similar to those for gcc/clang. However, the Fortran compiler remains based around Cray-specific options. Be sure to separate C/C++ compiler options and Fortran compiler options (typically CFLAGS and FFLAGS) if compiling mixed C/Fortran applications.

As CCE is the default compiler environment on ARCHER2, you do not usually need to issue any commands to enable CCE.

Note

The CCE Clang compiler uses a GCC 8 toolchain so only C++ standard library features available in GCC 8 will be available in CCE Clang. You can add the compile option --gcc-toolchain=/opt/gcc/11.2.0/snos to use a more recent version of the C++ standard library if you wish.

Useful CCE C/C++ options

When using the compiler wrappers cc or CC, some of the following options may be useful:

Language, warning, Debugging options:

Option Comment
-std=<standard> Default is -std=gnu11 (gnu++14 for C++) [1]
--gcc-toolchain=/opt/cray/pe/gcc/12.2.0/snos Use the GCC 12.2.0 toolchain instead of the default 11.2.0 version packaged with CCE

Performance options:

Option Comment
-Ofast Optimisation levels: -O0, -O1, -O2, -O3, -Ofast. -Ofast is not recommended without careful regression testing on numerical output.
-ffp=level Floating point maths optimisations levels 0-4 [2]
-flto Link time optimisation

Miscellaneous options:

Option Comment
-fopenmp Compile OpenMP (default is off)
-v Display verbose output from compiler stages

Notes

  1. Option -std=gnu11 gives c11 plus GNU extensions (likewise c++14 plus GNU extensions). See https://gcc.gnu.org/onlinedocs/gcc-4.8.2/gcc/C-Extensions.html
  2. Option -ffp=3 is implied by -Ofast or -ffast-math

Useful CCE Fortran options

Language, Warning, Debugging options:

Option Comment
-m <level> Message level (default -m 3 errors and warnings)

Performance options:

Option Comment
-O <level> Optimisation levels: -O0 to -O3 (default -O2)
-h fp<level> Floating point maths optimisations levels 0-3
-h ipa Inter-procedural analysis

Miscellaneous options:

Option Comment
-h omp Compile OpenMP (default is -hnoomp)
-v Display verbose output from compiler stages

CCE Reference Documentation

AMD Optimizing Compiler Collection (AOCC)

The AMD Optimizing Compiler Collection (AOCC) is a clang-based optimising compiler. AOCC also includes a flang-based Fortran compiler.

Load the AOCC compiler environment from the default CCE (cray) compiler environment via:

auser@ln03:~> module load PrgEnv-aocc

Lmod is automatically replacing "cce/15.0.0" with "aocc/3.2.0".


Lmod is automatically replacing "PrgEnv-cray/8.3.3" with "PrgEnv-aocc/8.3.3".


Due to MODULEPATH changes, the following have been reloaded:
  1) cray-mpich/8.1.23

AOCC reference material

Message passing interface (MPI)

HPE Cray MPICH

HPE Cray provide, as standard, an MPICH implementation of the message passing interface which is specifically optimised for the ARCHER2 interconnect. The current implementation supports MPI standard version 3.1.

The HPE Cray MPICH implementation is linked into software by default when compiling using the standard wrapper scripts: cc, CC and ftn.

You do not need to do anything to make HPE Cray MPICH available when you log into ARCHER2, it is available by default to all users.

Switching to alternative UCX MPI implementation

HPE Cray MPICH can use two different low-level protocols to transfer data across the network. The default is the Open Fabrics Interface (OFI), but you can switch to the UCX protocol from Mellanox.

Which performs better will be application-dependent, but our experience is that UCX is often faster for programs that send a lot of data collectively between many processes, e.g. all-to-all communications patterns such as occur in parallel FFTs.

Note

You do not need to recompile your program - you simply load different modules in your Slurm script.

module load craype-network-ucx 
module load cray-mpich-ucx

The performance benefits will also vary depending on the number of processes, so it is important to benchmark your application at the scale used in full production runs.

MPI reference material

MPI standard documents: https://www.mpi-forum.org/docs/

Linking and libraries

Linking to libraries is performed dynamically on ARCHER2.

Important

Static linking is not supported on ARCHER2. If you attempt to link statically, you will see errors similar to: 

/usr/bin/ld: cannot find -lpmi
/usr/bin/ld: cannot find -lpmi2
collect2: error: ld returned 1 exit status

One can use the -craype-verbose flag to the compiler wrapper to check exactly what linker arguments are invoked. The compiler wrapper scripts encode the paths to the programming environment system libraries using RUNPATH. This ensures that the executable can find the correct runtime libraries without the matching software modules loaded.

The library RUNPATH associated with an executable can be inspected via, e.g.,

$ readelf -d ./a.out

(swap a.out for the name of the executable you are querying).

Commonly used libraries

Modules with names prefixed by cray- are provided by HPE Cray, and work with any of the compiler environments and. These modules should be the first choice for access to software libraries if available.

Tip

More information on the different software libraries on ARCHER2 can be found in the Software libraries section of the user guide.

Available HPE Cray Programming Environment releases on ARCHER2

ARCHER2 currently has the following HPE Cray Programming Environment releases available:

  • 22.12: Current default

You can find information, notes, and lists of changes for current and upcoming ARCHER2 HPE Cray programming environments in the HPE Cray Programming Environment GitHub repository.

Tip

We recommend that users use the most recent version of the PE available to get the latest improvements and bug fixes.

Compiling on compute nodes

Sometimes you may wish to compile in a batch job. For example, the compile process may take a long time or the compile process is part of the research workflow and can be coupled to the production job. Unlike login nodes, the /home file system is not available.

An example job submission script for a compile job using make (assuming the Makefile is in the same directory as the job submission script) would be:

#!/bin/bash

#SBATCH --job-name=compile
#SBATCH --time=00:20:00
#SBATCH --nodes=1
#SBATCH --ntasks-per-node=1
#SBATCH --cpus-per-task=1

# Replace the account code, partition and QoS with those you wish to use
#SBATCH --account=t01        
#SBATCH --partition=standard
#SBATCH --qos=standard


make clean

make

Note

If you want to use a compiler environment other than the default then you will need to add the module load command before the make command. e.g. to use the GCC compiler environemnt:

module load PrgEnv-gnu

You can also use a compute node in an interactive way using salloc. Please see Section Using salloc to reserve resources for further details. Once your interactive session is ready, you can load the compilation environment and compile the code.

Using the compiler wrappers for serial compilations

The compiler wrappers link with a number of HPE-provided libraries automatically. It is possible to compile codes in serial with the compiler wrappers to take advantage of the HPE libraries.

To set up your environment for serial compilation, you will need to run:

  module load craype-network-none
  module remove cray-mpich

Once this is done, you can use the compiler wrappers (cc for C, CC for C++, and ftn for Fortran) to compile your code in serial.

Managing development

ARCHER2 supports common revision control software such as git.

Standard GNU autoconf tools are available, along with make (which is GNU Make). Versions of cmake are available.

Tip

Some of these tools are part of the system software, and typically reside in /usr/bin, while others are provided as part of the module system. Some tools may be available in different versions via both /usr/bin and via the module system. If you find the default version is too old, then look in the module system for a more recent version.

Build instructions for software on ARCHER2

The ARCHER2 CSE team at EPCC and other contributors provide build configurations ando instructions for a range of research software, software libraries and tools on a variety of HPC systems (including ARCHER2) in a public Github repository. See:

The repository always welcomes contributions from the ARCHER2 user community.

Support for building software on ARCHER2

If you run into issues building software on ARCHER2 or the software you require is not available then please contact the ARCHER2 Service Desk with any questions you have.