diff --git a/.github/workflows/draft-joss-paper.yml b/.github/workflows/draft-joss-paper.yml new file mode 100644 index 0000000..442f7f6 --- /dev/null +++ b/.github/workflows/draft-joss-paper.yml @@ -0,0 +1,40 @@ +name: Draft JOSS paper + +on: + push: + branches: [ "main" ] + pull_request: + branches: [ "main" ] + +jobs: + paper: + runs-on: ubuntu-latest + name: Paper Draft + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + repository: ${{ github.event.pull_request.head.repo.full_name }} + ref: ${{ github.event.pull_request.head.ref }} + + - name: Build draft PDF + uses: openjournals/openjournals-draft-action@master + with: + journal: joss + # This should be the path to the paper within your repo. + paper-path: paper/paper.md + + - name: Upload PDF + uses: actions/upload-artifact@v4 + with: + name: paper + # This is the output path where Pandoc will write the compiled + # PDF. Note, this should be the same directory as the input + # paper.md + path: paper/paper.pdf + + - name: Commit PDF to repository + uses: EndBug/add-and-commit@v9 + with: + message: '(auto) paper draft' + add: 'paper/paper.pdf' diff --git a/compilation.sh b/compilation.sh new file mode 100755 index 0000000..2875fe1 --- /dev/null +++ b/compilation.sh @@ -0,0 +1,7 @@ +#!/bin/bash +sudo docker run --rm \ + --volume $PWD/paper:/data \ + --user $(id -u):$(id -g) \ + --env JOURNAL=joss \ + openjournals/inara + diff --git a/paper/paper.bib b/paper/paper.bib new file mode 100644 index 0000000..5d99bd0 --- /dev/null +++ b/paper/paper.bib @@ -0,0 +1,71 @@ +@article{tapenade, + title = {{The Tapenade automatic differentiation tool: principles, model, and specification}}, + author = {Hasco{\"e}t, Laurent and Pascual, Val{\'e}rie}, + journal = {ACM Transactions on Mathematical Software (TOMS)}, + volume = {39}, + number = {3}, + pages = {1--43}, + year = {2013}, + doi = {10.1145/2450153.2450158}, + publisher = {ACM New York, NY, USA} +} + +@book{griewank2008, + title = {Evaluating derivatives: principles and techniques of algorithmic differentiation}, + author = {Griewank, Andreas and Walther, Andrea}, + year = {2008}, + doi = {10.1137/1.9780898717761}, + publisher = {SIAM} +} + +@article{HFBTHO, +title = {{HFBTHO-AD: Differentiation of a nuclear energy density functional code}}, +author = {Laurent Hasco{\"e}t and Matt Menickelly and Sri Hari Krishna Narayanan and Jared O’Neal and Nicolas Schunck and Stefan M. Wild}, +journal = {Computer Physics Communications}, +volume = {320}, +pages = {109955}, +year = {2026}, +doi = {10.1016/j.cpc.2025.109955}, +} + +@article{ADOLC, +title = {{Algorithm 755: ADOL-C: a package for the automatic differentiation of algorithms written in C/C++}}, +author = {Griewank, Andreas and Juedes, David and Utke, Jean}, +journal = {ACM Transactions on Mathematical Software (TOMS)}, +volume = {22}, +number = {2}, +pages = {131--167}, +year = {1996}, +doi = {10.1145/229473.229474}, +publisher = {Association for Computing Machinery}, +} + +@article{jonasson2020, + title = {{Algorithm 1005: Fortran subroutines for reverse mode algorithmic differentiation of blas matrix operations}}, + author = {Jonasson, Kristjan and Sigurdsson, Sven and Yngvason, Hordur Freyr and Ragnarsson, Petur Orri and Melsted, Pall}, + journal = {ACM Transactions on Mathematical Software (TOMS)}, + volume = {46}, + number = {1}, + pages = {1--20}, + year = {2020}, + doi = {10.1145/3382191}, + publisher = {ACM New York, NY, USA} +} + +@article{giles2008, + title = {An extended collection of matrix derivative results for forward and reverse mode automatic differentiation}, + author = {Giles, Mike}, + year = {2008}, +} + +@inproceedings{TAF, + title = {{Applying TAF to generate efficient derivative code of Fortran 77-95 programs}}, + author = {Giering, Ralf and Kaminski, Thomas}, + booktitle = {{PAMM: Proceedings in Applied Mathematics and Mechanics}}, + volume = {2}, + number = {1}, + pages = {54--57}, + year = {2003}, + doi = {10.1002/pamm.200310014}, + organization = {Wiley Online Library} +} diff --git a/paper/paper.md b/paper/paper.md new file mode 100644 index 0000000..b677228 --- /dev/null +++ b/paper/paper.md @@ -0,0 +1,73 @@ +--- +title: 'diffblas: algorithmically differentiated BLAS routines' +tags: + - BLAS + - automatic differentiation + - numerical linear algebra + - scientific computing +authors: + - name: Sri Hari Krishna Narayanan^[corresponding author] + orcid: 0000-0003-0388-5943 + affiliation: 1 + - name: Alexis Montoison + orcid: 0000-0002-3403-5450 + affiliation: 1 + - name: Jean-Luc Bouchot + orcid: 0000-0003-4523-3986 + affiliation: 2 +affiliations: + - name: Mathematics and Computer Science Division, Argonne National Laboratory, USA + index: 1 + - name: Inria de Saclay, Palaiseau, France + index: 2 +date: 25 February 2026 +bibliography: paper.bib + +--- + +# Summary + +`diffblas` is a library that provides BLAS routines algorithmically differentiated using algorithmic differentiation principles [@griewank2008] from their reference implementations in [LAPACK](https://github.com/Reference-LAPACK/lapack) on GitHub using the automatic differentiation tool Tapenade [@tapenade]. +It supports four modes: tangent (`_d`), vector tangent (`_dv`), adjoint (`_b`), and vector adjoint (`_bv`). + +In addition to differentiating the standard Fortran-style `BLAS` interface, `diffblas` also provides differentiated `CBLAS` routines, facilitating interoperability with C and other languages. +Its API mirrors BLAS / CBLAS, with additional arguments specifying differentiation variables, making integration into existing workflows straightforward. + +`diffblas` relies on the underlying standard BLAS implementation and is agnostic to the backend (OpenBLAS, BLIS, MKL, Apple Accelerate, or libblastrampoline), ensuring both high performance and portability. +Precompiled artifacts are available on GitHub, simplifying installation and use across different programming environments. + +By providing efficient and accurate derivatives of linear algebra operations, `diffblas` facilitates gradient-based optimization, sensitivity analysis, and derivative-based workflows in scientific computing. + +# Statement of need + +Linear algebra routines such as those in LAPACK are widely used in scientific computing, optimization, and machine learning. However, they do not provide derivatives, which are often required for gradient-based algorithms. + +`diffblas` addresses this gap by providing algorithmically differentiated BLAS routines directly from reference LAPACK implementations and following relevant differntiation rules [@giles2008]. + +# State of the field + +Automatic source-to-source differentiation tools, such as Tapenade [@tapenade], ADOL-C [@ADOLC], or TAF [@TAF], provide general mechanisms to compute derivatives of code. + +[@jonasson2020] derives scalar reverse mode derivative formulae for BLAS routines and provides their Fortran code. Such an approach is generally more efficient that differentiating through the BLAS routines using an AD tool [@jonasson2020]. They do not however consider the forward mode or vector modes. + +Derivatives of linear algebra routines are available in Python packages such as JAX [@jax] and PyTorch [@pytorch]. These implementations are not available outside these frameworks. Enzyme and Enzyme.jl perform optimized BLAS and CuBLAS differentiation at the MLIR level[@Enzyme] but the derivative code is not available externally. +... + +# Research impact statement + +This work was inspired in part by a need to differentiate a Fortran code [@HFBTHO] that uses BLAS and LAPACK routines, and to use the differentiated application for gradient-based optimization. We were able to to differentiate HFBTHO using Tapenade by providing the source code for the BLAS routines used by HFBTHO and their dependencies to Tapenade [@HFBTHOAD]. We handcoded the derivatives for the LAPACK routine `DSYEVR`. + +Providing both the standard and CBLAS interfaces ensures that diffblas can be adopted across different programming environments, facilitating derivative computations in diverse scientific computing projects. +Precompiled artifacts on GitHub further simplify integration, enabling rapid deployment in multiple languages and scientific computing projects. + +# Acknowledgements + +This work was supported in part by the Applied Mathematics activity within the U.S. Department of Energy, Office of Science, Office +of Advanced Scientific Computing Research Applied Mathematics, and Office of Nuclear Physics SciDAC program under Contract No. DE-AC02-06CH11357. This work was supported in part by NSF CSSI grant 2104068. + +# AI usage disclosure + +Generative AI was used to ... +ChatGPT was used to check spelling, grammar, and clarity of the English text in this paper. + +# References diff --git a/paper/paper.pdf b/paper/paper.pdf new file mode 100644 index 0000000..48d772d Binary files /dev/null and b/paper/paper.pdf differ