FV-AED

In partnership with BMT TUFLOW development team, the AED developers maintian a compatible version of the AED model that works with TUFLOW-FV - a full-featured 3D finite-volume hydrodynamic model. The TUFLOW FV host hydrodynamic model is developed and distributed separately by BMT and is not part of this repository; refer to the TUFLOW wesbite download and wiki pages for further information.

FV-AED is a packaged version of the AED water quality modelling library, compiled as an external plugin for linking with the 3D finite-volume hydrodynamic model TUFLOW FV. This repository houses the plugin source code, the AED libraries it depends on, and binaries (ready-to-use compiled plugins).

Release status

Repository organisation

The repository includes:

• binaries : pre-compiled plugins for Linux and Windows.
• fv-source : plugin source code, including the required AED libraries as linked sub-modules.
• fv-examples : example simulations for running TUFLOW FV + AED, including all required input files.
• .github/workflows : GitHub Actions workflow (compile.yml) for automated compilation and testing.

The source bundle in fv-source is assembled from the following sub-modules (dependent repositories):

Sub-module	Repository	Role
libaed-fv	libaed-fv	Coupling layer between TUFLOW FV and AED
libaed-api	libaed-api	AED standard coupling interface
libaed-water	libaed-water	AED water column modules
libaed-benthic	libaed-benthic	AED benthic modules
libaed-demo	libaed-demo	AED demonstration modules

Getting the latest plugin

For users who only need the compiled plugin (not the full source code), it can be downloaded without cloning the repository. Navigate to the folder for your platform under binaries, then download the file:

• Linux — binaries/ubuntu, by Ubuntu release (20.04, 24.04, 26.04)
• Windows — binaries/windows, as versioned .zip archives

On Ubuntu the current build is supplied two ways: as a libaed-tfv_<version>-0_amd64.deb package for system installation, and as a libaed_fv_latest directory holding the same libraries unpacked. Older builds remain as versioned .tar.gz archives.

The plugin set comprises three shared libraries, which TUFLOW FV loads through its external-module interface:

Library	Provides
libtuflowfv_external_wq	Water quality — the AED modules
libtuflowfv_external_turb	Turbulence closure
libtuflowfv_external_wave	Wave calculations

The binaries/ubuntu/20.04 folder is retained for legacy use and is no longer refreshed; 24.04 and 26.04 are built by CI on every push to main.

Cloning the repo with all sub-module code

To access the full repository the code must be cloned or downloaded in full. Note that a basic clone will not include the code/files in the linked sub-modules, so an extra argument is needed: --recurse-submodules

Cloning the latest code

git clone --recurse-submodules https://github.com/AquaticEcoDynamics/fv-aed.git

Cloning a particular tag

git clone --recurse-submodules -b v2.2.5 https://github.com/AquaticEcoDynamics/fv-aed.git

Building from source

The build is driven by a single script in fv-source, which compiles the AED libraries and links the plugin:

cd fv-source
./build_aed-fv.sh

On Windows, use build_aed-fv.bat. An Intel Fortran compiler is required; pass --ifx to use the newer ifx compiler in place of ifort, which is what CI does. Run ./build_aed-fv.sh --help for the full option list — the most useful are --debug (build with debugging symbols) and --with-checks (add array-bounds checking).

Version lineage

Line	Coupling library	Status
AED 3.x	libaed-fv	Active development — pre-release
AED 2.x	libfvaed2	Legacy, no longer developed

Current FV-AED builds track the AED 3.x line through libaed-fv and the libaed-api coupling interface. They are not compatible with the older libfvaed2 library, which uses the earlier AED interface.

Citing this code

Users may need to cite the AED model in general, or a specific model code package/bundle/version.

Citing a specific code bundle, please use the appropriate DOI, eg.:

Hipsey, M.R., Boon, C., Paraska, D., Bruce, L. and Huang, P., (2022). AquaticEcoDynamics/fv-aed: v2.2.1 (v2.2.1). Zenodo. https://doi.org/10.5281/zenodo.7047676.

Note that a DOI for the 3.0.0 bundle will be minted when that release is tagged; until then, cite the v2.2.1 bundle and state the commit or binary version you actually used.

Citing the AED model:

Hipsey, M.R., ed. (2022) Modelling Aquatic Eco-Dynamics: Overview of the AED modular simulation platform. Zenodo. https://doi.org/10.5281/zenodo.6516222.

Getting FV-AED+ (also termed AED+)

The AED+ version of AED adds further modules which are within:

• libaed-dev — modules under active development,
• libaed-riparian — riparian modules,
• libaed-light — light and optics modules.

AED+ is available to members of the AED community. AED+ builds of this plugin are distinguished by a + in the artefact name (for example tuflowfv_external_wq+_3.0.0.zip) and are not published in this repository.

If you are a researcher or practitioner who would like to work with the AED+ modules, get in touch with the AED group via aquatic.science.uwa.edu.au.

Contributing

Contributions are welcome, and not only in the form of code. There are three main routes.

Example and benchmark cases. These are managed here, in fv-examples. Each case is a self-contained directory holding the TUFLOW FV control file, the AED control and database files, the required input files, and a short readme.md describing the site. New cases are added by pull request. Benchmark cases that exercise a particular process or module are as useful as whole-system applications.

Code development. Minor developments are welcome here — a bug fix or a small improvement can be raised as an issue or a pull request against this repository. Note though that fv-source is a bundle of sub-modules pinned to fixed commits, so it is a snapshot of the source rather than a place to develop against. Anyone doing sustained work on the AED libraries or the coupling layer is encouraged to work through AED_Tools, the AED Developer Toolkit, which fetches the source repositories directly and builds them from live development branches. That work is what feeds into this bundle when the sub-module pins are updated for a release.

Documentation and discussion. The AED science manual documents the modules themselves, and improvements to it, and to the documentation carried in the source, are valuable. This repository's own Wiki is currently a placeholder — setup notes for getting a TUFLOW FV + AED simulation running would be a good place to start. The AquaticEcoDynamics discussions board is the place for questions, configuration advice and proposals.

Getting hold of older versions

Releases from 2022 onward are available in the releases section, and older binaries remain in the binaries tree. For users seeking older bundles of the code (e.g., for compatibility with prior TUFLOW FV versions), please visit the AED releases repository.

Additional information

For the science behind the modules, their parameters and their configuration, see the AED science manual.

For the host model — licensing, installation and the external-module interface — see TUFLOW FV.