/kestrel

Software for simulations of sediment-laden Earth surface flows

Primary LanguageFortranGNU General Public License v3.0GPL-3.0

Kestrel

DOI

Kestrel is a Fortran code for simulating sediment-laden Earth surface flows, such as debris flows, landslides and flash flooding.

Features

The software is designed to be easy to install and use. Simulations approximate solutions to a underlying set of shallow-layer equations that describe a generic flowing mixture of fluid and sediment. A modular design allows a variety of popular closures to be selected at runtime to specialise simulations for particular purposes.

  • Fully conservative well-balanced positivity-preserving finite volume solver.
  • Dynamic erosion and deposition of sediment.
  • Eddy viscosity implementation to ensure well-posedness of morphodynamic flows.
  • User-settable basal drag and morphodynamics parametrisations.
  • Simulation on user-specified topographies: simple geometric surfaces and digital elevation maps (DEMs).
  • Variety of boundary conditions for initiating flows, including from multiple locations.
  • Output via geo-referenced NetCDF or plain-text.

An overview of the physical modelling framework may be found here. For full details, including the numerical implementation, consult our paper [1]. The issue of well-posedness referred to above is explored in detail in refs [1] and [2].

'Very' quick start

Most likely, you will need to refer to the documentation to use Kestrel effectively and in an informed manner. This includes a proper quick start guide aimed towards new users.

For the particularly impatient, here is the basic information needed to get started

  1. Kestrel builds with GNU autotools on Unix-like platforms. The auto-generated configuration scripts are not included in the git repository, so you'll need to make sure you have automake, autoconf (etc) installed and run

    autoreconf -fi

    followed by

    ./configure && make

    which places the Kestrel executable in the src/ directory. You will need an up-to-date GCC (9+), the GDAL, PROJ and (optionally) the NetCDF libraries.

  2. Simulations are conducted by specifying an input file on the command line, i.e.

    /path-to-kestrel [path-to-input-file]

    There are some examples of correctly formatted input files included in this repository in the examples/ directory. These may be adapted to suit different needs.

  3. To conduct simulations on measured topographies, for example via digital elevation models (DEMs), you will need provide this data and tell Kestrel where to look for the appropriate files. See either the example input files, or the user documentation for how to do this.

Testing

The full test suite for Kestrel makes use of the Julia language. If you have this installed, it may be run via make check, or by changing to the ./tests directory and issuing the command

julia runall.jl

This runs a sequential battery of various tests and can take some time. Unless you are modifying the code, or are very keen to check that it's working as expected, you probably do not need to bother with this.

Documentation

More detailed user documentation is available here.

Contributing

Fixes, improvements and suggestions/bug reports are most welcome. The best way to contribute is publically, via the issue tracker, though you may also use the details below to contact us directly. A little guidance on the sorts of contributions that might be valuable is given here.

Contact

Kestrel is developed and maintained by Mark J. Woodhouse (mark.woodhouse@bristol.ac.uk) and Jake Langham (J.Langham@bristol.ac.uk), University of Bristol.

References

  • [1] Langham J, Woodhouse MJ, Hogg AJ, Jenkins LT, Phillips JC. 2023 Simulating shallow morphodynamic flows on evolving topographies. arXiv 2306.16185
  • [2] Langham J, Woodhouse MJ, Hogg AJ, Phillips JC. 2021 Linear stability of shallow morphodynamic flows. J. Fluid Mech. 916.