{"id":39087933,"url":"https://github.com/nedtaylor/athena","last_synced_at":"2026-01-17T18:43:14.220Z","repository":{"id":222990195,"uuid":"758834048","full_name":"nedtaylor/athena","owner":"nedtaylor","description":"A Fortran-based neural network library for physics-based applications. Alongside standard neural network layer types, it also supports graph-based layers and physics informed neural networks.","archived":false,"fork":false,"pushed_at":"2025-12-10T07:33:46.000Z","size":6316,"stargazers_count":29,"open_issues_count":5,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-21T11:45:57.617Z","etag":null,"topics":["automatic-differentiation","cnn","convolution","convolutional-neural-networks","deep-learning","feed-forward-neural-networks","fortran","fortran-package-manager","machine-learning","message-passing-neural-network","neural-network","physics-informed-neural-networks"],"latest_commit_sha":null,"homepage":"","language":"Fortran","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nedtaylor.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-02-17T08:01:57.000Z","updated_at":"2025-12-10T07:33:19.000Z","dependencies_parsed_at":"2024-02-17T14:31:35.260Z","dependency_job_id":"ffb2e0e4-b299-4106-9f12-6e18d2f2b918","html_url":"https://github.com/nedtaylor/athena","commit_stats":null,"previous_names":["nedtaylor/athena"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/nedtaylor/athena","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nedtaylor%2Fathena","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nedtaylor%2Fathena/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nedtaylor%2Fathena/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nedtaylor%2Fathena/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nedtaylor","download_url":"https://codeload.github.com/nedtaylor/athena/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nedtaylor%2Fathena/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28516199,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T18:28:00.501Z","status":"ssl_error","status_checked_at":"2026-01-17T18:28:00.150Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automatic-differentiation","cnn","convolution","convolutional-neural-networks","deep-learning","feed-forward-neural-networks","fortran","fortran-package-manager","machine-learning","message-passing-neural-network","neural-network","physics-informed-neural-networks"],"created_at":"2026-01-17T18:43:14.134Z","updated_at":"2026-01-17T18:43:14.199Z","avatar_url":"https://github.com/nedtaylor.png","language":"Fortran","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![MIT workflow](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/license/mit/ \"View MIT license\")\n[![Latest Release](https://img.shields.io/github/v/release/nedtaylor/athena?sort=semver)](https://github.com/nedtaylor/athena/releases \"View on GitHub\")\n[![status](https://joss.theoj.org/papers/7806cc51a998f872034abfe0bb24bc24/status.svg)](https://joss.theoj.org/papers/7806cc51a998f872034abfe0bb24bc24)\n[![Documentation Status](https://readthedocs.org/projects/athena/badge/?version=latest)](https://athena-fortran.readthedocs.io/en/latest/?badge=latest \"athena ReadTheDocs\")\n[![FPM](https://img.shields.io/badge/fpm-0.12.0-purple)](https://github.com/fortran-lang/fpm \"View Fortran Package Manager\")\n[![CMAKE](https://img.shields.io/badge/cmake-3.17.5-red)](https://github.com/Kitware/CMake/releases/tag/v3.17.5 \"View cmake\")\n[![GCC compatibility](https://img.shields.io/badge/gcc-15.2.0-green)](https://gcc.gnu.org/gcc-13/ \"View GCC\")\n[![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/nedtaylor/fd7c07c046ecc92d92eaf7bdcb78c4b5/raw/test.json)](https://nedtaylor.github.io/athena/ \"View coverage report\")\n\u003c!-- [![Downloads](https://img.shields.io/github/downloads/nedtaylor/athena/total)](https://github.com/nedtaylor/athena/releases \"View on GitHub\") --\u003e\n\n# athena\n\nby Ned Thaddeus Taylor\n\nATHENA (Adaptive Training for High Efficiency Neural network Applications) is a Fortran library for developing and handling neural networks (with a focus on convolutional neural networks).\n\n\u003e **_NOTE:_**\nStarting with version 2.0.0, release tags follow the `vX.Y.Z` convention for consistency across projects such as diffstruc and graphstruc.\nInternal version numbers remain `X.Y.Z`.\n\n## Statement of need\n\nThe athena library leverages Fortran's strong support of array arithmatics, and its compatibility with parallel and high-performance computing resources.\nAdditionally, there exist many improvements made available since Fortran 95, specifically in Fortran 2018 (Reid 2018) (and ones in Fortran 2023), as well as continued development by the Fortran Standards committee.\nAll of this provides a clear incentive to develop further libraries and frameworks focused on providing machine learning capabilities to the Fortran community.\n\nWhile existing Fortran-based libraries, such as neural-fortran (Curcic 2019), address many aspects of neural networks,\nathena provides implementation of some well-known features not currently available within other libraries; these features include batchnormalisation, regularisation layers (such as dropout and dropblock), and average pooling layers.\nAdditionally, the library provides support for 1, 2, and 3D input data for most features currently implemented; this includes 1, 2, and 3D data for convolutional layers.\nThe athena library also supports many convolutional techniques, including various data padding types, and stride.\nBuilding on this, the library also supports strongly physics-focused architectures through providing capabilties of graph neural networks through the inclusion of message passing layers and physics informed neural networks through its use of automatic differentiation.\n\nOne of the primary intended applications of athena is in materials science, which heavily utilises convolutional and graph neural networks for learning based on charge densities and atomic structures.\nGiven the unique data structure of atomic configurations, specifically their graph-based nature, a specialised API must be developed to accommodate these needs.\n\n### References\n- Reid, J. (2018). The new features of fortran 2018. SIGPLAN Fortran Forum, 37(1), 5–43. https://doi.org/10.1145/3206214.3206215\n- 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\n\n\nDocumentation\n-----\n\nathena is distributed with the following directories:\n\n| Directory | Description |\n|---|---|\n|  _docs/_    |  Compilable documentation |\n|  _example/_ |  A set of example programs utilising the athena library |\n|  _src/_ |      Source code  |\n|  _tools/_ |    Additional shell script tools for automating learning  |\n|  _test/_  |    A set of test programs to check functionality of the library works after compilation |\n\n\nTutorials and documentation are provided on the [docs](http://athena-fortran.readthedocs.io/) website.\n\nRefer to the [API Documentation section](#api-documentation) later in this document to see how to access the API-specific documentation.\n\n\u003e **_NOTE:_**\nThe [wiki](https://github.com/nedtaylor/athena/wiki) still exists, but is outdated, no longer being updated, and will be deprecated in the future.\n\nSetup\n-----\n\nThe athena library can be obtained from the git repository. Use the following commands to get started:\n```\n  git clone https://github.com/nedtaylor/athena.git\n  cd athena\n```\n\n### Dependencies\n\nThe library has the following dependencies:\n- A Fortran compiler (compatible with Fortran 2018 or later)\n- [fpm](https://github.com/fortran-lang/fpm), [CMake](https://cmake.org), or [Spack](https://github.com/spack/spack) for building the library\n- The [graphstruc](https://github.com/nedtaylor/graphstruc) Fortran library (for handing graph structures through derived types)\n\nThe library has been developed and tested using the following compilers:\n- gfortran -- gcc 15.2.0\n- ifort -- Intel 2021.10.0.20230609\n- ifx -- IntelLLVM 2025.2.0\n\n\u003e **_NOTE:_**\nathena 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.\n\n#### Tested compilers\nThe library has also been tested with and found to support the following libraries:\n- gfortran -- gcc 14.3\n\n### Building with fpm\n\nThe library is set up to work with the Fortran Package Manager (fpm).\n\nRun the following command in the repository main directory:\n```\n  fpm build --profile release\n```\n\n#### Testing with fpm\n\nTo check whether ATHENA has installed correctly and that the compilation works as expected, the following command can be run:\n```\n  fpm test --profile release\n```\n\nThis runs a set of test programs (found within the test/ directory) to ensure the expected output occurs when layers and networks are set up.\n\n### Building with cmake\n\nRun the following commands in the directory containing _CMakeLists.txt_:\n```\n  mkdir build\n  cd build\n  cmake [-DCMAKE_BUILD_TYPE=\"Release\"] ..\n  make install\n```\nThis will build the library in the build/ directory. All library files will then be found in:\n```\n  ${HOME}/.local/athena\n```\nInside this directory, the following files will be generated:\n```\n  include/athena.mod\n  lib/libathena.a\n```\n\n#### Testing with cmake\n\nTo check whether ATHENA has installed correctly and that the compilation works as expected, the following command can be run:\n```\n  ctest\n```\n\nThis runs a set of test programs (found within the test/ directory) to ensure the expected output occurs when layers and networks are set up.\n\n\n### Building with Spack\n\nThe library can also be installed using the Spack package manager. This can be achieved by running the following commands in the main directory:\n```\nspack repo add .spack\nspack install athena\n```\n\nCurrently, Spack compilation requires manual download of athena.\n\n\u003e **_NOTE:_**\nThere already exists an `athena` package directly on Spack, be aware that these are not related.\n\n\n\nExamples\n-------\nAfter 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:\nhttps://github.com/halimb/MNIST-txt/tree/master\n\nThe link to the original MNIST database is: http://yann.lecun.com/exdb/mnist/\n\n\u003e **_NOTE:_**\nFor the mnist examples, the MNIST dataset must be downloaded. By default, the database is expected to be found in the directory path ``../../DMNIST``. 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:\n\n```\n  dataset_dir = \"../../DMNIST\"\n```\n\n#### Running examples using fpm\n\nUsing fpm, the examples are built alongside the library. To list all available examples, use:\n```\n  fpm run --example --list\n```\n\nTo run a particular example, execute the following command:\n\n```\n  fpm run --example [NAME] --profile release\n```\n\nwhere [_NAME_] is the name of the example found in the list.\n\n\n#### Running examples manually\n\nTo compile and run the examples, run the following commands in the directory containing _CMakeLists.txt_:\n```\n  cd example/mnist\n  make build optim [FC=FORTRAN-COMPILER]\n  ./bin/athena_test -f test_job.in\n```\nAfter the example program is compiled, the following directories will also exist:\n\n| Directory | Description |\n|---|---|\n|  _example/mnist/bin/_  |     Contains binary executable |\n|  _example/mnist/obj/_  |     Contains module/object files (non-linked binary files)|\n\nThe 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_.\n\nIn the tools/ directory, there exist scripts that take utilise the wandb python package (Weights and Biases, a machine learning data tracker). Wandb is a Python module and, as such, a Python interface has been provided to call and run the Fortran example. The Python interface then reads the Fortran output files and logs the results to the wandb project.\n\nExample wandb project link: https://wandb.ai/ntaylor/cnn_mnist_test/overview?workspace=user-ntaylor\n\n\nAPI documentation\n-----------------\n\nAPI documentation can be generated using FORD (Fortran Documenter).\nTo do so, follow the installation guide on the [FORD website](https://forddocs.readthedocs.io/en/stable/) to ensure FORD is installed.\nOnce FORD is installed, run the following command in the root directory of the git repository:\n\n```\n  ford ford.md\n```\n\nHow-to\n-------\nTo call/reference the athena library in a program, include the following use statement at the beginning of the necessary Fortran file:\n\n  use athena\n\nDuring compilation, include the following flags in the compilation (gfortran) command:\n```\n-I${HOME}/.local/athena/include -L${HOME}/.local/athena/lib -lathena\n```\n\n\nDevelopers\n----------\n- Ned Thaddeus Taylor\n\nContributing\n------------\n\nPlease note that this project adheres to the [Contributing Guide](CONTRIBUTING.md). 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](https://github.com/nedtaylor/athena/issues), or contact [Ned Taylor](mailto:n.t.taylor@exeter.ac.uk?subject=ATHENA%20-%20contribution%20request).\n\n\nLicense\n-------\nThis work is licensed under an [MIT license](https://opensource.org/license/mit/).\n\nCode Coverage\n-------------\n\nAutomated reporting on unit test code coverage in the README is achieved through utilising the [cmake-modules](https://github.com/rpavlik/cmake-modules) and [dynamic-badges-action](https://github.com/Schneegans/dynamic-badges-action?tab=readme-ov-file) projects.\n\n## New Repository Location\n\nThis repository has been migrated from the University of Exeter GitLab to GitHub to facilitate community interaction and support.\nThe latest version, updates, and collaboration now take place on this GitHub repository.\n\n**GitLab Repository (Archived):** https://git.exeter.ac.uk/hepplestone/athena\n\n## Why the Migration?\n\nIt 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.\n\n---\n\nFiles\n-----\n\nAll files with the __sub_ suffix are the implementations of interfaces defined within the corresponding filename without the suffix.\n\n|Source file | Description|\n|-----------|------------|\n|_src/athena.f90_                      | the module file that imports all necessary user-accessible procedures  |\n|_src/lib/mod_accuracy.f90_            | accuracy calculation procedures |\n|_src/lib/mod_activation.f90_          | generic node activation (aka transfer) setup  |\n|_src/lib/mod_activation__[_NAME_]_.f90_   | [_NAME_] activation method  |\n|_src/lib/mod_base_layer.f90_          | abstract layer construct type  |\n|_src/lib/mod_clipper.f90_             | gradient clipping procedures |\n|_src/lib/mod_container.f90_           | layer container construct for handling multiple layers in a network  |\n|_src/lib/mod_diffstruc_extd.f90       | extensions of [diffstruc](https://github.com/nedtaylor/diffstruc) providing more automatic differentiation operations |\n|_src/lib/mod__[_NAME_]__layer.f90_    | [_NAME_] layer-type  |\n|_src/lib/mod_initialiser.f90_         | generic kernel (and bias) initialiser setup  |\n|_src/lib/mod_initialiser__[_NAME_]_.f90_  | [_NAME_] kernel initialisation method  |\n|_src/lib/mod_io_utils.f90_            | input/output printing procedures |\n|_src/lib/mod_loss.f90_                | loss and corresponding derivatives calculation procedures |\n|_src/lib/mod_lr_decay.f90_            | learning rate decay procedures |\n|_src/lib/mod_metrics.f90_             | training convergence metric derived type and procedures  |\n|_src/lib/mod_misc_ml.f90_             | miscellaneous machine learning procedures  |\n|_src/lib/mod_misc_types.f90_          | neural network-associated derived types  |\n|_srcs/lib/mod_network.f90_            | neural network derived type and procedures  |\n|_src/lib/mod_normalisation.f90_       | data normalisation procedures  |\n|_src/lib/mod_onnx.f90_                | procedures for interoperability with other neural network libraries |\n|_src/lib/mod_optimiser.f90_           | learning optimisation derived type and procedures  |\n|_src/lib/mod_random.f90_              | random number procedures  |\n|_src/lib/mod_regulariser.f90_         | regularisation procedures  |\n|_src/lib/mod_tools_infile.f90_        | tools to read input files  |\n\n\n\n| Additional file | Description |\n|-----|------|\n|_CHANGELOG_                        | human-readable athena codebase version history |\n|_CMakeLists.txt_                   | the makefile used for compiling the library  |\n|_CONTRIBUTING.md_                  | Guidelines for organisation of athena codebase |\n|_ford.md_                          | [FORD](https://forddocs.readthedocs.io/en/stable/) compilation file |\n|_fpm.toml_                         | [Fortran Package Manager (fpm)](https://github.com/fortran-lang/fpm) compilation file |\n|_LICENSE_                          | licence of athena code |\n|_README.md_                        | a readme file with a brief description of the code and files  |\n|_TODO_                             | todo-list in addition to useful machine learning and fortran references |\n|_cmake/CodeCoverage.cmake_         | [cmake-modules](https://github.com/rpavlik/cmake-modules) file to automate unit test coverage reporting|\n|_example/example_library_          | Utility library shared between the examples |\n|_example/__[_NAME_]__/expected_output.txt_   | expected output from executing [_NAME_] example program  |\n|_example/__[_NAME_]__/test_job.in_           | input file for [_NAME_] example program  |\n|_example/__[_NAME_]__/src_                   | source directory for [_NAME_] example program  |\n|_test/test__[_NAME_]__.f90_           | [_NAME_] test program to check library expected functionality |\n|_tools/coverage_badge.py_          | script to extract code coverage percentage from GitHub Action |\n|_tools/sweep_init.py_              | script to initialise wandb sweep  |\n|_tools/sweep_train.py_             | script to perform training and log learning to wandb  |\n|_tools/template.in_                | input file for program in test/bin/ (once compiled)  |\n|_tools/wandb-metadata.json_        | metadata defining default plots on wandb website  |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnedtaylor%2Fathena","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnedtaylor%2Fathena","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnedtaylor%2Fathena/lists"}