sed-plume 0.2.2

A hypopycnal sediment-carrying plume entering the ocean.

plume: A hypopycnal plume model built with landlab

Requirements

plume requires Python 3.

Apart from Python, plume has a number of other requirements, all of which can be obtained through either pip or conda, that will be automatically installed when you install plume.

To see a full listing of the requirements, have a look at the project’s requirements.txt file.

If you are a developer of plume you will also want to install additional dependencies for running plume’s tests to make sure that things are working as they should. These dependencies are listed in requirements-testing.txt.

Installation

To install plume, first create a new environment in which plume will be installed. This, although not necessary, will isolate the installation so that there won’t be conflicts with your base Python installation. This can be done with conda as:

$ conda create -n plume python=3
$ conda activate plume

Stable Release

plume, and its dependencies, can be installed either with pip or conda. Using pip:

$ pip install plume

Using conda:

$ conda install plume -c conda-forge

From Source

Before building plume from source, you will need an installation of the GNU Scientific Library (gsl). There are several ways to install this but the easiest is through conda,

$ mamba install gsl

After downloading the plume source code, run the following from plume’s top-level folder (the one that contains setup.py) to install plume into the current environment:

$ pip install -e .

Input Files

Configuration File

The main plume input file is a yaml-formatted text file that lists constants used by plume. Running the following will print a sample plume configuration file:

$ plume generate plume.toml

This will print something like the following,

[plume]
_version = "0.2.0.dev0"

[plume.grid]
shape = [500, 500]
xy_spacing = [100.0, 100.0]
xy_of_lower_left = [0.0, 0.0]

[plume.river]
filepath = "river.csv"
width = 50.0
depth = 5.0
velocity = 1.5
location = [0.0, 25000.0]
angle = 0.0

[plume.sediment]
removal_rate = 60.0
bulk_density = 1600.0

[plume.ocean]
filepath = "ocean.csv"
along_shore_velocity = 0.1
sediment_concentration = 0.0

[plume.output]
filepath = "plume.nc"

Ocean File

The plume ocean file defines parameters of the ocean for each day of the simulation. This is a csv-formatted text file to day, along-shore velocity, and sediment concentration.

$ plume generate ocean.csv

# version: 0.2.0.dev0
# Time [d], Along-shore velocity [m/s], Sediment Concentration [-]
0.0,0.1,0.0

River File

The plume river file is a csv-formatted text file that gives river parameters for each day of the simulation. Columns are time, river width, river depth, and river velocity.

$ plume generate river.csv

# version: 0.2.0.dev0
# Time [d], Width [m], Depth [m], Velocity [m/s]
0.0,50.0,5.0,1.5

The plume river file defines

Output File

The only output file of plume is a netCDF file that contains sediment concentrations for each day of the simulation.

Examples

To run a simulation using the sample input files described above, you first need to create a set of sample files:

$ mkdir example
$ plume --cd=example setup

You can now run the simulation:

$ plume --cd=example run

Credits

Development Leads

• Eric Hutton

Release Notes

0.2.2 (2023-09-18)

Other Changes and Additions

• Updated the cython code used to calculate the centerline to fix a compile error related to the update to cython v3. (#10)

• Added support for Python 3.11, dropped Python 3.8. (#11)

• Added a nox file for routine project maintenance and continuous integration. (#12)

0.2.1 (2022-06-29)

Bug Fixes

• Fixed an error when trying to get the version from the command line with plume --version`. (#9)

0.2.0 (2022-06-28)

New Features

• Updated the Plume component to be compatible with landlab version 2. This will allow plume to operate with the newest version of landlab and be incorporated into other landlab frameworks such as the Sequence model. (#5)

• Change the plume command-line program to use toml-formatted input files. (#5)

• The plume model now builds and runs on Windows! (#5)

Bug Fixes

• Fixed a bug where the existing deposit thickness was being zeroed-out before the plume was run. The plume now adds sediment to an existing deposit and leaves it up to the user to clear an existing deposit. (#7)

Documentation Enhancements

• Updated the documentation to include installation instructions, usage and examples. (#5)

Other Changes and Additions

• Setup towncrier to manage the changelog. (#5)

• Switch from versioneer to zest.releaser to manage release versions. (#5)

• Set up continuous integration workflows using GitHub Actions. CI tests include testing for code style using black, checking for lint with flake8, testing notebooks and running the test suite. (#5)

• Updated the package metadata and moved static metaddata from setup.py to pyproject.toml. (#5)

• Setup up pre-commit hooks for ensuring style, lack of lint, python 3.8+ syntax, and clean notebooks. (#5)

• Added a citation file that users of plume can use to cite the software. (#6)

• Removed ocean and river time series from the plume command line interface. The plume command now runs just a single plume. (#7)

• Added GitHub Actions workflows for pushing prereleases to TestPyPI and releases to PyPI. (#8)

0.1.0 (2018-06-13)

Features

• Create plume package that simulates 1D (i.e. centerline), and 2D hypopycnal plumes.

Documentation Enhancements

• Added a new Jupyter notebook that demonstrates how to use simulate 2D and 1D plumes using the plume package. (#3)

Other Changes and Additions

• Set up continuous integration testing with Travis-CI. CI builds are run for Linux and Mac. Windows support is not yet available. (#1)

• Added a suite of tests, which use pytest, for testing the plume package. (#2)

• Added versioneer to manage package release versions. (#4)