Running fluvial-particle
Quick Start
Generate a configuration template:
fluvial_particle --init
This creates settings.toml in the current directory.
Edit the configuration file to specify your mesh files, particle settings, and field mappings.
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
--initGenerate a template configuration file in the current directory. Creates
settings.tomlby 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-postprocessDisable the post-processing routine that generates cells.h5 and cell XDMF files.
--versionDisplay version information and exit.
--helpDisplay 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.