athena

by Ned Thaddeus Taylor

ATHENA (Adaptive Training for High Efficiency Neural network Applications) is a Fortran library for developing, training, and deploying neural networks.

NOTE: Starting with version 2.0.0, release tags follow the vX.Y.Z convention for consistency across projects such as diffstruc and graphstruc. Internal version numbers remain X.Y.Z.

Statement of need

The increasing use of machine learning in scientific computing has created demand for tools that integrate naturally with established simulation codes. While Python-based frameworks dominate the machine learning ecosystem, their use within large-scale Fortran codes typically requires wrappers, inter-language interfaces, or separate training pipelines, adding complexity and maintenance overhead.

Existing Fortran machine learning libraries such as neural-fortran (Curcic, 2019) and Fiats (Rouson, 2025) provide efficient implementations of core neural network functionality for high-performance computing, but are generally focused on standard architectures and offer more limited support for the broader range of models used in scientific machine learning.

athena addresses this by providing a fully extensible framework for building, training, and deploying modern neural networks directly in Fortran. In particular, it supports a range of approaches that are becoming central in scientific applications, including:

• Graph neural networks for atomistic systems and structured data
• Physics-informed neural networks for solving partial differential equations
• Neural operators for learning mappings between functional spaces
• Inverse design methods for optimising inputs to achieve target outputs

The library is designed around abstract interfaces for core components—including layers, activations, optimisers, and loss functions—allowing new functionality to be added via external modules without modifying the core codebase, in line with SOLID design principles. It also provides native support for graph-structured data and integrates automatic differentiation within the framework, enabling flexible definition of custom computational graphs and training procedures without reliance on external tooling.

By enabling end-to-end machine learning workflows in Fortran, athena removes the need for cross-language integration layers and is particularly suited to existing large-scale simulation codes in materials science, plasma physics, and computational fluid dynamics.

References

• Curcic, M. (2019). A parallel fortran framework for neural networks and deep learning. SIGPLAN Fortran Forum, 38(1), 4–21. https://doi.org/10.1145/3323057.3323059
• Rouson et al., (2025). Fiats: Functional inference and training for surrogates. Journal of Open Source Software, 10(116), 8785, https://doi.org/10.21105/joss.08785

Documentation

athena is distributed with the following directories:

Tutorials and documentation are provided on the docs website.

Refer to the API Documentation section later in this document to see how to access the API-specific documentation.

NOTE: The wiki still exists, but is outdated, no longer being updated, and will be deprecated in the future.

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 (>= 0.13.0), CMake, or Spack for building the library - The coreutils Fortran library (basic utilities) - The graphstruc Fortran library (for handing graph structures through derived types) - The diffstruc Fortran library (for automatic differentiation capabilities)

The library has been developed and tested using the following compilers: - gfortran -- gcc 15.2.0 - ifort -- Intel 2021.10.0.20230609 - ifx -- IntelLLVM 2025.2.0 - flang -- Flang 22.1.1

NOTE: athena is known to be incompatible with all versions of the gfortran compiler below 14.3.0 due an error with order of calling of overloaded final procedures of derived types.

Tested compilers

The library has also been tested with and found to support the following libraries: - gfortran -- gcc 14.3

Building with fpm

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

Run the following command in the repository main directory:

fpm build --profile release

To build with the built-in Weights & Biases integration enabled, use the wandb feature:

source tools/setup_wf_env.sh
fpm build --features wandb

Testing with fpm

To check whether ATHENA has installed correctly and that the compilation works as expected, the following command can be run:

fpm test --profile release

This runs a set of test programs (found within the test/ directory) to ensure the expected output occurs when layers and networks are set up.

Building with cmake

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

mkdir build
cd build
cmake [-DCMAKE_BUILD_TYPE="Release"] ..
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

Testing with cmake

To check whether ATHENA has installed correctly and that the compilation works as expected, the following command can be run:

ctest

This runs a set of test programs (found within the test/ directory) to ensure the expected output occurs when layers and networks are set up.

Building with Spack

The library can also be installed using the Spack package manager. This can be achieved by running the following commands in the main directory:

spack repo add .spack
spack install athena-fortran

Currently, Spack compilation requires manual download of athena.

NOTE: There already exists an athena package directly on Spack, be aware that these are not related. This is why the package name for this library on Spack is athena-fortran instead of athena.

Examples

After the library has been installed, a set of example programs can be compiled and run to test the capabilities of athena on the MNIST dataset. Some of the examples can be run as-is, and do not require external databases. For those that require the MNIST (a set of 60,000 hand-written numbers for training and 10,000 for testing, 0-9) dataset (i.e. 'example/mnist_' directories ), the dataset must first be downloaded. The example program has been developed to accept a text-based format of the MNIST dataset. The .txt database that these examples have been developed for can be found here: https://github.com/halimb/MNIST-txt/tree/master

The link to the original MNIST database is: http://yann.lecun.com/exdb/mnist/

NOTE: For the mnist examples, the MNIST dataset must be downloaded. By default, the database is expected to be found in the directory path ../MNIST-txt. However, this can be chaned by editing the following line in the example/mnist[_VAR]/test_job.in file to point to the desired path:

  dataset_dir = "../MNIST-txt"

Running examples using fpm

Using fpm, the examples are built alongside the library. To list all available examples, use:

fpm run --example --list

To run a particular example, execute the following command:

fpm run --example [NAME] --profile release

where [NAME] is the name of the example found in the list.

For built-in W&B examples (wandb_sine, wandb_network_sine, wandb_sweep, wandb_pinn_burgers), enable the wandb feature:

source tools/setup_wf_env.sh
fpm run --example wandb_sine --features wandb

Running examples manually

To compile and run the examples, run the following commands in the directory containing CMakeLists.txt:

cd example/mnist
make build optim [FC=FORTRAN-COMPILER]
./bin/athena_test -f test_job.in

After the example program is compiled, the following directories will also exist:

The example will perform a train over the MNIST dataset. Once complete, it will print its weights and biases to file, and test the trained network on the training set. The output from this can then be compared to the file expected_output_COMPILER.txt.

Weights and Biases (wandb) integration

athena provides optional integration with the Weights and Biases (wandb) machine learning platform through a separate library called wandb-fortran.

This integration is opt-in:

• fpm (>=0.13.0): build/run with --features wandb
• cmake: use -DATHENA_WANDB_SUPPORT=ON (or -DATHENA_ENABLE_WANDB=ON)

The network_type derived type in athena has an extended type called wandb_network_type that provides additional procedures for logging to wandb by default inside the train procedure. To use this, simply declare a wandb_network_type variable instead of a network_type variable, and the library will handle the rest.

For more control over the logging, and access to sweeps for hyperparameter optimisation, the wandb-fortran library can be used directly. This library provides a Fortran API for logging to wandb, and can be used in conjunction with the athena library (or any other Fortran library) to log custom metrics, hyperparameters, and more.

Examples of how to use the wandb-fortran library for athena can be found in the following examples:

• example/wandb_network_sine
• example/wandb_sweep
• example/wandb_pinn_burgers

Documentation for the wandb-fortran library can be found on the docs website.

API documentation

API documentation can be generated using FORD (Fortran Documenter). To do so, follow the installation guide on the FORD website to ensure FORD is installed. Once FORD is installed, run the following command in the root directory of the git repository:

ford ford.md

How-to

To call/reference the athena library in a program, include the following use statement at the beginning of the necessary Fortran file:

  use athena

During compilation, include the following flags in the compilation (gfortran) command:

-I${HOME}/.local/athena/include -L${HOME}/.local/athena/lib -lathena

Contributing

Please note that this project adheres to the Contributing Guide. If you want to contribute to this project, please first read through the guide. If you have any questions, please either discuss then in issues, or contact Ned Taylor.

License

This work is licensed under an MIT license.

Code Coverage

Automated reporting on unit test code coverage in the README is achieved through utilising the cmake-modules and dynamic-badges-action projects.

New Repository Location

This repository has been migrated from the University of Exeter GitLab to GitHub to facilitate community interaction and support. The latest version, updates, and collaboration now take place on this GitHub repository.

GitLab Repository (Archived): https://git.exeter.ac.uk/hepplestone/athena

Why the Migration?

It was decided that this project should be migrated to allow for better community support (i.e. allowing community users to raise issues). All information has been ported over where possible. Issues have not been migrated over, these can be found in the old repository. Releases prior to 1.2.0 have not been migrated over, but they can still be found as tags in this repository.

Files

All files with the __sub_ suffix are the implementations of interfaces defined within the corresponding filename without the suffix.

Below is a non-exhaustive list of the files contained within the repository, and their descriptions. For a full list of files, refer to the repository.