A.1 The PotentialHeight repository

All of the main final code is now in the PotentialHeight repository¹, broken down into a set of Python modules. I essentially followed the mono-repo approach (Winters et al. 2020), of creating a set of packages in a single repository so that they were always guaranteed to be compatible with each other. The modules are themselves hopefully not too tightly coupled, leading to adequate separation of concerns. The repository is structured as follows:

• adforce – a module for wrapping the ADCIRC Fortran code in Python. Includes the code to generate the training data for the SurgeNet model (Simon D. A. Thomas 2025d).

• adbo – a module for performing Bayesian optimisation via adforce. It builds upon trieste (Picheny et al. 2023) which is a tensorflow (Abadi et al. 2015) based Bayesian optimization library. It includes the code to create the extreme SurgeNet test data (Simon D. A. Thomas 2025c).

• tcpips – a module for calculating the potential intensity and potential size of tropical cyclones on ERA5 and CMIP6 data. It builds on the TCPyPI package from Gilford (2020).

• w22 – a module for calculating the parts of potential size from (Wang et al. 2022). It includes the new CLE15 implementation in Python (descended from Chavas 2022).

• worst – a module for fitting GEV distributions with or without an assumed upper bound to conduct the statistical simulations in Chapter 3. Also uses tensorflow (Abadi et al. 2015) for flexible gradient-aware optimisation of the likelihood.

• surgenet – a module that just contains the toy experiment from the motivation to Chapter 5, as the SurgeNet model is pytorch based, so it makes more sense to keep it separate from the other tensorflow based modules.

An important aspect of the repository is that it is fairly well unit tested, with doctests in many of the most important functions. All tests are run as a GitHub Action with each push to the repository’s main branch. The documentation is also automatically generated using Sphinx/Read the Docs with each push to the repository’s main branch. The documentation is available at https://worstsurge.readthedocs.io/en/latest/. As all of the tests are doctests, they also form part of the documentation, leading to a less repetitive (more ‘DRY,’ Thomas and Hunt 2019) coding style. Hopefully these practices, inspired by software engineering, will make the code more maintainable and reusable in the future.

In general I also sought to develop the project in an ‘agile’ manner (Thomas and Hunt 2019) with the core product completed (Chapter 3) before the parts of the framework were improved, including the calculation of potential sizes (Chapter 2) and the Bayesian optimisation loop (Chapter 4). There are still many ways to expand the potential height framework (see Chapter 6), but hopefully the design of this repository will make it easier.

A.2 Other repositories

A.2.1 ADCIRC v55.02

A version of ADCIRC-v55 (Pringle et al. 2021) is adapted to compile on ARCHER2, with slight alterations to implement the bug fixes announced in v55.02 etc. It is available at https://github.com/sdat2/adcirc-v55.02. It should be similar to https://github.com/adcirc/adcirc/releases/tag/v55.02

A.2.2 adcirc-emulation

adcirc-emulation is a Python repository that includes all the initial exploration and scoping for the thesis (but not the final work included here) (Simon Donald Alistair Thomas 2025). It includes code for setting up ADCIRC runs with text data input, processing ADCIRC output, and initial Bayesian optimisation experiments. It is available at https://github.com/sdat2/adcirc-emulation.

A.2.3 sithom

sithom is a Python package with a set of general Python utilities used in this project and others (Thomas 2024), which standardizes plotting style and other things. It also has doctest unit tests that run with every push and automatically compiled documentation. It is available at https://github.com/sdat2/sithom. Install by pip install sithom. https://sithom.readthedocs.io/en/latest/MAIN_README.html has the documentation.

A.2.4 mSWE-GNN/sdat2

The code for training the full ADCIRC surrogate models is available at https://github.com/sdat2/mSWE-GNN/tree/sdat2 (Simon D. A. Thomas 2025b). It builds upon pytorch-geometric/pyg (Fey and Lenssen 2019; Fey et al. 2025), which is a pytorch (Paszke et al. 2019) based geometric deep learning library. It has its own doctests that run as a GitHub Action on each push to the sdat2 branch with a CPU only micromamba environment, and it also includes a working environment.yaml specification for GPU training.

References