diffstruc

by Ned Thaddeus Taylor

diffstruc is a Fortran library that provides automatic differentiation capabilities through use of an array derived type.

The library has implemented both forward and reverse mode automatic differentiation. Through repetitive use of the forward mode differentiation procedure, any higher order partial differentiation is achievable (note, memory usage will increase for higher order differentials) and has been tested up to third order.

---

diffstruc is distributed with the following directories:

Directory	Description
docs/	Compilable documentation
src/	Source code
test/	A set of unit test programs to check functionality of the library works after compilation

Documentation

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.

Setup

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

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

Dependencies

The library has the following dependencies

• A Fortran compiler (compatible with Fortran 2018 or later)
• fpm

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

• gfortran -- gcc 14.3.0, 15.2.0
• ifx -- ifx 2025.2.0
• flang -- flang 22.1.1

NOTE: diffstruc is known to be incompatible with all versions of the gfortran compiler below 14.3.0 due to issues with the calling of the final procedure of array_type.

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

Testing with fpm

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

  fpm test

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.

Known issues

Compiler note: bracketed expressions and temporaries

WARNING: When chaining overloaded operators on array_type, expressions that use brackets to group intermediate results may cause compiler-generated temporaries to be created. For example:

y => (w * x)**2

This pattern works correctly with gfortran, but can behave incorrectly with flang because the temporary result produced by (w * x) may not propagate the is_temporary flag correctly through the chained operator call, leading to incorrect gradient computation or memory issues.

The recommended safe pattern is to store intermediate results explicitly:

tmp => w * x
y => tmp**2

This avoids reliance on compiler-specific handling of temporaries in operator-overloaded expressions and is the portable approach across all supported compilers.

API documentation

API documentation can be generated using FORD (Fortran Documenter). The library has a compilable documentation this can be accessed with the FORD (FORtran Documenter) tool. The documentation can be compiled using the following terminal command in the root directory of the repository:

  ford ford.md

This will generate the docs/html directory, inside which, you will find index.html. By opening this file in a browser window, you will be able to view a nagivable documentation.

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.

License

This work is licensed under an MIT license.