Running fluvial-particle

Particle concentration from three different time slices from a simulation on the Kootenai River, Idaho, USA. Flow is from bottom to top and time increases from the left figure to the right.

Quick Start

  1. Generate a configuration template:

fluvial_particle --init

This creates settings.toml in the current directory.

  1. Edit the configuration file to specify your mesh files, particle settings, and field mappings.

  2. Run the simulation:

fluvial_particle settings.toml ./output

Command Line Usage

Serial execution:

fluvial_particle <config_file> <output_directory>

Where <config_file> is the path to a TOML or Python configuration file, and <output_directory> is where output HDF5 and XDMF files will be written.

Parallel execution (MPI):

For an MPI-enabled installation, run in parallel (e.g., with 4 cores):

mpiexec -n 4 fluvial_particle_mpi <config_file> <output_directory>

Command Line Options

--init

Generate a template configuration file in the current directory. Creates settings.toml by default.

--format {toml,python}

Format for the template file (used with --init). Default: toml

# Generate TOML template (default)
fluvial_particle --init

# Generate legacy Python template
fluvial_particle --init --format python
--seed <int>

Specify the random seed for a serial simulation (does not apply to parallel simulations).

--no-postprocess

Disable the post-processing routine that generates cells.h5 and cell XDMF files.

--version

Display version information and exit.

--help

Display help message and exit.

Python API

For programmatic use in scripts or Jupyter notebooks:

from fluvial_particle import run_simulation, get_default_config

# Option 1: Run from config file
results = run_simulation("settings.toml", "./output")

# Option 2: Run from dict config (no file needed)
config = get_default_config()
config["particles"]["count"] = 100
config["grid"]["file_2d"] = "./mesh_2d.vts"
config["grid"]["file_3d"] = "./mesh_3d.vts"
results = run_simulation(config, "./output")

# Access results
positions = results.get_positions(timestep=-1)
df = results.to_dataframe(timestep=-1)

See the Example page for detailed examples.

Network Runs

The 1D river-network solver has its own settings table and entry points. It reads a network hydraulics NetCDF export (from pywatershed) instead of a 2D/3D mesh:

fluvial_particle_network settings.toml -o output
mpiexec -n 4 fluvial_particle_network_mpi settings.toml -o output
fluvial_particle_network --init      # print the [network] settings template

From Python:

from fluvial_particle import run_network_simulation

results = run_network_simulation("settings.toml", "./output", seed=42)
print(results.summary())
arrivals = results.arrival_histogram(outlet=4205, bin_seconds=3600)

See 1D River-Network Particle Tracking for the input schema, the particle convention, sources, output, and post-processing.