{"id":37064424,"url":"https://github.com/rmcd-mscb/fluvial-particle","last_synced_at":"2026-01-14T07:31:40.671Z","repository":{"id":304533173,"uuid":"998388322","full_name":"rmcd-mscb/fluvial-particle","owner":"rmcd-mscb","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-12T00:33:02.000Z","size":32819,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-12T03:26:14.059Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rmcd-mscb.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-08T14:04:47.000Z","updated_at":"2026-01-12T00:15:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"e864827f-d540-4254-bb4f-baddf3cd43e8","html_url":"https://github.com/rmcd-mscb/fluvial-particle","commit_stats":null,"previous_names":["rmcd-mscb/fluvial-particle"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/rmcd-mscb/fluvial-particle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rmcd-mscb%2Ffluvial-particle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rmcd-mscb%2Ffluvial-particle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rmcd-mscb%2Ffluvial-particle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rmcd-mscb%2Ffluvial-particle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rmcd-mscb","download_url":"https://codeload.github.com/rmcd-mscb/fluvial-particle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rmcd-mscb%2Ffluvial-particle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28413364,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T05:26:33.345Z","status":"ssl_error","status_checked_at":"2026-01-14T05:21:57.251Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-14T07:31:39.973Z","updated_at":"2026-01-14T07:31:40.650Z","avatar_url":"https://github.com/rmcd-mscb.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Welcome to _fluvial-particle_\n\n[![PyPI](https://img.shields.io/pypi/v/fluvial-particle.svg)](https://pypi.org/project/fluvial-particle/)\n[![Status](https://img.shields.io/pypi/status/fluvial-particle.svg)](https://pypi.org/project/fluvial-particle/)\n[![Python Version](https://img.shields.io/pypi/pyversions/fluvial-particle)](https://pypi.org/project/fluvial-particle/)\n[![License](https://img.shields.io/pypi/l/fluvial-particle)](https://creativecommons.org/publicdomain/zero/1.0/legalcode)\n[![Read the Docs](https://img.shields.io/readthedocs/fluvial-particle/latest.svg?label=Read%20the%20Docs)](https://fluvial-particle.readthedocs.io/)\n\n[![Tests](https://code.usgs.gov/wma/nhgf/fluvparticle/badges/main/pipeline.svg)](https://code.usgs.gov/wma/nhgf/fluvparticle/-/commits/main)\n[![Codecov](https://codecov.io/gh/rmcd-mscb/fluvial-particle/branch/main/graph/badge.svg)](https://codecov.io/gh/rmcd-mscb/fluvial-particle)\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\u0026logoColor=white)](https://github.com/pre-commit/pre-commit)\n[![Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\nA Python package to efficiently model active- and passive-particle transport in flowing rivers.\n\n![An animated image shows a fluvial-particle simulation output in the Kootenai River, Idaho, USA](https://code.usgs.gov/wma/nhgf/fluvparticle/-/raw/main/docs/data/kootenai_2to27_particles_fpc2d_rotate.gif \"KootenaiParticles\")\n\n## Description\n\nThis 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).\n\n## Efficiently programmed and parallel enabled\n\nAs 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.\n\nProhibitively 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\u003csup\u003e27\u003c/sup\u003e particles on the Kootenai River over many thousands of CPUs shows that MPI-enabled fluvial-particle scales well, as shown in the figure below.\n\n![Strong-scaling panel shows the decrease in simulation time and the simulation speed-up as a function of the number of CPUs (from 2^10 to 2^13 CPUs) used in the simulation. The scaling is very close to ideal over this range.](https://code.usgs.gov/wma/nhgf/fluvparticle/-/raw/main/docs/data/strongscalingpanel.png \"Parallel strong scaling\")\n\n## Features\n\n- Lagrangian particle-tracking in fluvial environments\n- parallel computing with MPI using mpi4py\n\n## Installation\n\nThis package uses [uv](https://github.com/astral-sh/uv) for fast dependency installation and [hatchling](https://hatch.pypa.io/) for building. It is recommended to use a conda environment.\n\nFirst, create the fluvial-particle conda environment using the environment.yml file:\n\n```shell\nconda env create -f environment.yml\nconda activate fluvial-particle\n```\n\nNext, install uv if you don't have it already:\n\n```shell\npip install uv\n```\n\nThen use uv to install the package and its dependencies:\n\n```shell\nuv pip install -e .\n```\n\nThe success of the installation can be tested with pytest:\n\n```shell\npytest tests\n```\n\n## Usage\n\nDirections on invoking _fluvial-particle_ from the command line can be found in the [docs](https://fluvial-particle.readthedocs.io/en/latest/usage.html).\n\n## Utilities\n\n- Packaging and dependency management with\n  [conda](https://www.anaconda.com)\n- Test automation with [Nox](https://nox.thea.codes/)\n- Linting with [preccommit](https://pre-commit.com/) and\n  [Flake8](http://flake8.pycqa.org)\n- Continuous integration with [GitHub\n  Actions](https://github.com/features/actions) or\n  [Travis-CI](https://travis-ci.com)\n- Documentation with [Sphinx](http://www.sphinx-doc.org/) and [Read\n  the Docs](https://readthedocs.org/)\n- Automated uploads to [PyPI](https://pypi.org/) and\n  [TestPyPI](https://test.pypi.org/)\n- Automated release notes with [Release\n  Drafter](https://github.com/release-drafter/release-drafter)\n- Automated dependency updates with\n  [Dependabot](https://dependabot.com/)\n- Code formatting with [Black](https://github.com/psf/black) and\n  [Prettier](https://prettier.io/)\n- Testing with [pytest](https://docs.pytest.org/en/latest/)\n- Code coverage with [Coverageppy](https://coverage.readthedocs.io/)\n- Coverage reporting with [Codecov](https://codecov.io/)\n- Command-line interface with\n  [Click](https://click.palletsprojects.com/)\n- Static type-checking with [mypy](http://mypy-lang.org/)\n- Runtime type-checking with\n  [Typeguard](https://github.com/agronholm/typeguard)\n- Security audit with [Bandit](https://github.com/PyCQA/bandit) and\n  [Safety](https://github.com/pyupio/safety)\n- Check documentation examples with\n  [xdoctest](https://github.com/Erotemic/xdoctest)\n- Generate API documentation with\n  [autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html)\n  and\n  [napoleon](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html)\n- Generate command-line reference with\n  [sphinxcclick](https://sphinx-click.readthedocs.io/)\n- Manage project labels with [GitHub\n  Labeler](https://github.com/marketplace/actions/github-labeler)\n- Manage project versions with\n  [Bump2version](https://github.com/c4urself/bump2version)\n- Automatic loading/unloading of [conda](https://www.anaconda.com)\n  environment with [direnv](https://direnv.net/)\n\n## Contributing\n\nContributions are very welcome.\nTo learn more, see the [Contributor Guide](https://fluvial-particle.readthedocs.io/en/latest/contributing.html).\n\n## License\n\nDistributed under the terms of the [CCO 1.0 license](https://creativecommons.org/publicdomain/zero/1.0/legalcode), Fluvial Particle is free and open source software.\n\n## Issues\n\nIf you encounter any problems,\nplease [file an issue](https://code.usgs.gov/wma/nhgf/fluvparticle/-/issues) along with a detailed description.\n\n## Credits\n\nThis project was generated from [hillc-usgs's](https://github.com/hillc-usgs) [Pygeoapi Plugin Cookiecutter](https://code.usgs.gov/wma/nhgf/pygeoapi-plugin-cookiecutter) template.\n\nThis package is based on the model described by [McDonald \\\u0026 Nelson (2021)](https://doi.org/10.1080/24705357.2019.1709102), _A Lagrangian particle-tracking approach to modelling larval drift in rivers_, Journal of Ecohydraulics, 6(1) 17-35.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frmcd-mscb%2Ffluvial-particle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frmcd-mscb%2Ffluvial-particle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frmcd-mscb%2Ffluvial-particle/lists"}