Installation

This page details how to install the ATHENA library, how to include it in compilation of a Fortran program, and how to import it in a Fortran program.

Setup

The ATHENA library can be obtained from the git repository. Use the following commands to get started:

  git clone https://github.com/nedtaylor/athena.git
  cd athena

Dependencies

The library has the following dependencies:

• A Fortran compiler (compatible with Fortran 2018 or later)
• fpm or CMake for building the library

The library has been developed and tested using the following compilers:

• gfortran -- gcc 13.2.0
• ifort -- Intel 2021.10.0.20230609
• ifx -- IntelLLVM 2023.2.0

Building with fpm

The library is set up to work with the Fortran Package Manager (fpm).

With gfortran, the following command in the repository main directory:

  fpm build --profile release

Importing athena using fpm

To use athena in a program, it must be set as a dependency. This can either be done locally or using the git weblink.

To include a local version of athena, ensure the following lines are in your fpm.toml file:

[dependencies]
athena = { path = "PATH_TO_ATHENA_REPOSITORY" }

where PATH_TO_ATHENA_REPOSITORY is the relative path to the athena repository from the location of the fpm.toml file.

To include athena directly from the online git repository, include the following lines in the fpm.toml file instead:

[dependencies]
athena = { git = "https://github.com/nedtaylor/athena" }

An example fpm.toml file for a test program would, therefore be:

name = "athena_test"

[dependencies]
athena = { git = "https://github.com/nedtaylor/athena" }

Within the directory containing fpm.toml (and a subdirectory src/ containing the example program file), the following command can then be run to compile and execute the test code.

Building with cmake

Run the following commands in the directory containing CMakeLists.txt:

  mkdir build  
  cd build  
  cmake [-DCMAKE_BUILD_TYPE="optim;mp"] ..  
  make install  

This will build the library in the build/ directory. All library files will then be found in:

  ${HOME}/.local/athena

Inside this directory, the following files will be generated:

  include/athena.mod
  lib/libathena.a

Importing athena using cmake

Once the software has been installed, it can be pointed to during compilation of a Fortran program, which allows its associated procedures and variables to be used within said program. To include it during compilation, the following flags must be used.

  <COMPILER> <OBJECTS> -I${ATHENA_PATH}/include -L${ATHENA_PATH}/lib -o a.out

Here, <COMPILER> refers to the Fortran compiler command in use, <OBJECTS> refers to the Fortran program files, ${ATHENA_PATH} refers to the ATHENA library directory, and a.out is a placeholder name for the output name of the executable. If the Setup steps above were followed, then

${ATHENA_PATH} = ${HOME}/.loca/athena

As an example, for a Fortran program that contains only a main.f90, with the intended executable name of a.out, using the gfortran compiler, the command line would be:

gfortran main.f90 -I${HOME}/.local/athena/include -L${HOME}/.local/athena/lib -o a.out

How to use the library

Once we are confident with how to include the library during compilation, we need to test whether we can actually use the library within a Fortran program. To do so, we need to include a use statement at the beginning of our program (or module). The line to include is:

use athena

Here is a simple example program that imports es ATHENA, but does not actually utilise it in any way:

program main
  use athena
  implicit none
 
  write(*,*) "Hello world"

end program main

This example (saved as main.f90) should compile (using the aforementioned compilation line) and execute without any errors. If this is not the case, please ensure the prior steps have been followed correctly and, if this still occurs, raise an issue or contact support.

Having followed these steps, you should now be ready to follow the guide on how to utilise the ATHENA library within a Fortran program.