Welcome to fluvial-particle

A Python package to efficiently model active- and passive-particle transport in flowing rivers.

Description

This package advects conservative flow tracers (a.k.a. passive particles) with the fluid velocity and displaces them with stochastic diffusion due to fluid turbulence over discrete time steps. It tracks particles under a Lagrangian frame of reference as they move through a curvilinear 2- or 3-D hydrodynamic mesh. Users may customize particle subclasses to implement additional active particle motions, e.g. channel-bed adjacent sinusoidal vertical motion to simulate the preferred swimming patterns of white sturgeon larvae (McDonald and Nelson, 2021).

Efficiently programmed and parallel enabled

As the total simulation duration, the size of the mesh, or the number of particles increases, so too do the computational resources used in the simulation (real-world time, memory, etc.). fluvial-particle uses the efficient array storage and operator methods of NumPy and VTK to update particle positions. Simulation results are written to hierarchical data format (HDF5) files using the h5py package, which allows writing and compression of terabytes of data.

Prohibitively large or long simulation problems can be made tractable with the highly scalable fluvial-particle package. The mpi4py package enables massively-parallel execution mode to simulate millions or billions of particles (or more!). A strong-scaling test simulation of 2²⁷ particles on the Kootenai River over many thousands of CPUs shows that MPI-enabled fluvial-particle scales well, as shown in the figure below.

Features

• Lagrangian particle-tracking in fluvial environments

• parallel computing with MPI using mpi4py

Installation

This package uses poetry for installation and dependency management. It is recommended to use a conda environment.

First, create the fluvial-particle conda environment using the environment.yml file:

conda env create -f environment.yml
conda activate fluvial-particle

Next, use poetry to install the package dependencies and fluvial-particle itself:

poetry install

The success of the installation can be tested with pytest:

pytest tests

Usage

Directions on invoking fluvial-particle from the command line can be found in the docs.

Utilities

• Packaging and dependency management with conda

• Test automation with Nox

• Linting with preccommit and Flake8

• Continuous integration with GitHub Actions or Travis-CI

• Documentation with Sphinx and Read the Docs

• Automated uploads to PyPI and TestPyPI

• Automated release notes with Release Drafter

• Automated dependency updates with Dependabot

• Code formatting with Black and Prettier

• Testing with pytest

• Code coverage with Coverageppy

• Coverage reporting with Codecov

• Command-line interface with Click

• Static type-checking with mypy

• Runtime type-checking with Typeguard

• Security audit with Bandit and Safety

• Check documentation examples with xdoctest

• Generate API documentation with autodoc and napoleon

• Generate command-line reference with sphinxcclick

• Manage project labels with GitHub Labeler

• Manage project versions with Bump2version

• Automatic loading/unloading of conda environment with direnv

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the CCO 1.0 license, Fluvial Particle is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Credits

This project was generated from hillc-usgs’s Pygeoapi Plugin Cookiecutter template.

This package is based on the model described by McDonald & Nelson (2021), A Lagrangian particle-tracking approach to modelling larval drift in rivers, Journal of Ecohydraulics, 6(1) 17-35.