Kestrel

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

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.
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.
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.

jakelangham/kestrel