Advanced Research Computing


Making ALPS Usable and Sustainable - Open Source Software Sustainability Project

Ensuring ALPS has a future: transforming the code into a usable and sustainable open-source software project with funding from the recent UCL Open Source Software Sustainability call.

ALPS software logo

20 November 2023

Background and project goals

The UCL Open Source Software Sustainability Funding project “Making ALPS Usable and Sustainable” was proposed with three goals towards the transformation of the ALPS code into a usable and sustainable open-source software project:

1. Make the ALPS code useable for researchers from all plasma-physics backgrounds.
2. Create a baseline documentation for researchers outside the development team.
3. Make the ALPS code open source and encourage community development.


What we did

With the help of the allocated funding from UCL’s Advanced Research Computing Centre (ARC), we organised two hackathons in London of five days each in which Daniel Verscharen (Project Lead), Kristopher G. Klein (external partner from the University of Arizona), and two ARC Research Software Engineers (David Stansby and Tuomas Koskela) actively participated. We achieved all project goals through the running of these two hackathons. Below, we describe the activities, outputs, and impacts to date of this project.

Hackathon 1: 13-17 February 2023

The focus of our first hackathon was the creation of a software framework that enables useability of the ALPS code for a wide community of researchers. We began the week with an introduction by David Stansby about the activities of UCL’s ARC and with a presentation on best practice in useability and sustainability of modern open-source software projects.

We set up a GitHub repository for the ALPS code (github.com/danielver02/ALPS) and defined Workflows for automated test routines. We defined and implemented a specific test suite for known standard cases that ALPS must pass whenever modifications of the code are undertaken. We developed a common and standardised structure for the ALPS input files (Fortran Namelist format) and added clear comments to help future users in their tailoring of these input files to their needs. In an effort to unify the input across all of ALPS’s code components, we changed the interpolation sub-programme so that it also uses Namelist input files like the other ALPS components. For standardisation purposes, we changed the compilation procedure of the code to a configure/automake procedure following the GNU standard. During this step, we also unified the numerical optimisation scheme during compilation and improved the speed of certain algebraic operations through the linking of the Lapack and Openblas Fortran libraries.

During the first hackathon, we also implemented additional functionality to the ALPS code. For instance, we merged subroutines from the open-source NHDS project (github.com/danielver02/NHDS) that allow for a faster calculation of plasma susceptibilities in cases in which one or more species can be safely assumed as bi-Maxwellian. Another new functionality is the use of pre-defined analytical functions as background distributions (both for the creation of f0-tables and for the fitting during the hybrid-analytic continuation).

By the end of the week, the ALPS code with its new functionalities was successfully tested on HPC systems at the University of Arizona and passed the newly designed test suite.

Hackathon 2: 19-23 June 2023

One of the main tasks for our second hackathon was the documentation of the ALPS code to make it sustainable for future community-driven code development. We began the week with a presentation by Tuomas Koskela on best practice in software documentation and on the effective running of openly developed projects. We then set up a documentation website (danielver02.github.io/ALPS) based on the FORD documentation framework. The FORD framework required the commenting of all ALPS routines to include definitions/descriptions of all functions, subroutines, modules, and (interface) variables. This task was completed during the week, so that the FORD documentation is now comprehensive.

In addition, we set up parameter references on our documentation website with definitions of the ALPS input and output parameters for users with a mere interest in the running of the ALPS code. We also created a tutorial on our website that walks new ALPS users through a few example cases step by step. We changed our README and INSTALL files into Markdown files for better clarity in our new documentation system.

As an additional functionality, we implemented automated checks of user-defined key parameters (quasi-neutrality, zero-current condition, etc.) to support users in their parameter choice. The code now outputs a warning message during runtime if these checks fail. In addition, we implemented routines that calculate and output the eigenfunctions and heating rates from ALPS’s calculation. These functionalities have been successfully tested against the known PLUME and (partially against) NHDS results for bi-Maxwellian reference cases.

We extended the automated test Workflows from Hackathon 1 to include a check of the ALPS output files against expected reference output files. In this way, the Workflow tests are not limited to a purely functional test but also include a test of the accuracy and correctness of the calculation, each time an updated is merged with the ALPS master branch.


Happy software developers! The moment the code is released to the public

At the end of the week, we made our GitHub repository available and thus released a useable, sustainable, and well-documented ALPS code to the public.










Post-workshop activities

After the conclusion of our second hackathon, there was still time available for ARC support. Tom Young joined the team and supported the setting up of an automated Github action that scans the NASA ADS library for scientific publications that use ALPS. This activity will be particularly useful in the future for the purpose of tracking the impact of the code availability.


The impact to date

In the final session of Hackathon 2, we sent a notification via e-mail to 30 colleagues to inform them about the publication of the code. In addition, we submitted a notification to the MIST mailing list to reach out to the UK space-science community, and we posted notifications on Twitter about the availability of the code. After just one week since the completion of Hackathon 2, we have already received over a dozen of messages with positive feedback and expressions of interest in the use of ALPS. During our Friday session, we also discussed suitable conferences and venues for the running of ALPS community workshops (SHINE, ISSI Bern, EPS, DASH, APS, AGU, etc.).

Members of our team have already published one publication that acknowledges this project, one publication is currently under review, and two additional publications are currently in preparation. The release notes of the code include instructions for the acknowledgement and citation of the code in scientific publications.


Open source availability

The ALPS code is now publicly available under https://github.com/danielver02/ALPS. The documentation is available under https://danielver02.github.io/ALPS to which the short URL https://alps.space redirects.


We express our deep gratitude to the ARC for the support of this project. The help of the Research Software Engineers David Stansby and Tuomas Koskela has been invaluable for the success of this work. We would like to encourage UCL and the ARC to continue this funding programme in the future, as the benefits of the fundable activities are clearly worth the investment. It is a truly research-enabling programme with sustainability implications within and beyond the specifically funded projects." - Daniel Verscharen, Project Lead