Contents

API Reference

API Reference

FRAGMENT-MNP model

Mechanistic model of Micro and NanoPlastic FRAGMentation in the ENvironmenT.

class fragmentmnp.FragmentMNP(config: dict, data: dict, validate: bool = True)[source]

The class that controls usage of the FRAGMENT-MNP model

Parameters

  • config (dict) – Model configuration options

  • data (dict) – Model input data

  • validate (bool, default=True) – Should config and data be validated? It is strongly recommended to use validation, but this option is provided if you are certain your config and data are correct and wish to speed up model initialisation

mass_to_particle_number(mass)[source]

Convert mass (concentration) to particle number (concentration). Here, particles are assumed to be spherical, but this function can be overloaded to account for different shape particles.

run() → fragmentmnp.output.FMNPOutput[source]

Run the model with the config and data provided at initialisation.

Returns

Notes

Internally the model numerically solves the following differential equation for each size class, to give a time series of mass concentrations c. k is the current size class, i are the daughter size classes.

\[\frac{dc_k}{dt} = -k_{\text{frag},k} c_k + \Sigma_i f_{i,k} k_{\text{frag},i} c_i - k_{\text{diss},k} c_k\]

Here, \(k_{\text{frag},k}\) is the fragmentation rate of size class k, \(f_{i,k}\) is the fraction of daughter fragments produced from a fragmenting particle of size i that are of size k, and \(k_{\text{diss},k}\) is the dissolution rate from size class k.

Mass concentrations are converted to particle number concentrations by assuming spherical particles with the density given in the input data.

static set_fsd(n: int, psd: numpy.ndarray[Any, numpy.dtype[numpy.float64]], beta: float) → numpy.ndarray[Any, numpy.dtype[numpy.float64]][source]

Set the fragment size distribution matrix, assuming that fragmentation events result in a split in mass between daughter fragments that scales proportionally to \(d^\beta\), where \(d\) is the particle diameter and \(\beta\) is an empirical fragment size distribution parameter. For example, if \(\beta\) is negative, then a larger proportion of the fragmenting mass goes to smaller size classes than larger.

For an equal split between daughter size classes, set \(\beta\) to 0.

Parameters

  • n (int) – Number of particle size classes

  • psd (np.ndarray) – Particle size distribution

  • beta (float) – Fragment size distribution empirical parameter

Returns

Matrix of fragment size distributions for all size classes

Return type

np.ndarray

FRAGMENT-MNP Output

Provides functionality for processing and visulalising model output data.

class fragmentmnp.output.FMNPOutput(t: numpy.ndarray[Any, numpy.dtype[numpy._typing._array_like._ScalarType_co]], c: numpy.ndarray[Any, numpy.dtype[numpy._typing._array_like._ScalarType_co]], n: numpy.ndarray[Any, numpy.dtype[numpy._typing._array_like._ScalarType_co]], c_diss: numpy.ndarray[Any, numpy.dtype[numpy._typing._array_like._ScalarType_co]], n_diss: numpy.ndarray[Any, numpy.dtype[numpy._typing._array_like._ScalarType_co]], soln, psd, id=None)[source]

Class that holds output data from the model and provides plotting functionalities.

Parameters

  • t (np.ndarray, shape (n_timesteps,)) – Time series over which the model was run

  • c (np.ndarray, shape (n_size_classes, n_timesteps)) – Mass concentrations for each size class over the time series

  • n (np.ndarray, shape (n_size_classes, n_timesteps)) – Particle number concentrations for each size class over the time series

  • c_diss (np.ndarray, shape (n_size_classes, n_timesteps)) – Mass concentrations of dissolved organics

  • n_diss (np.ndarray, shape (n_size_classes, n_timesteps)) – Particle number concentrations lost from size classes due to dissolution

  • soln (Bunch object from scipy.integrate.solve_ivp return) – The solution to the model ODE, passed directly from the scipy.integrate.solve_ivp method

  • psd (np.ndarray, shape (n_size_classes, )) – Particle size distribution - the average diameters of each of the particle size classes

plot(type: str = 'mass_conc', plot_dissolution: bool = False, log_yaxis=False, units=None, cmap='viridis', show_legend=True, size_classes_to_plot=None)[source]

Plot the output data by choosing from a number of pre-defined plot types.

Parameters

  • type (str, default='mass_conc') – Tells the function what type of plot to produce. Either particle_number_conc or mass_conc.

  • plot_dissolution (bool, default=False) – Should dissolution be plotted on a separate y-axis

  • log_yaxis (bool or str, default=False) – True and “log” plots the y axis on a log scale, “symlog” plots the y axis on a symlog scale (useful if the data contain zeros), and False plots the y axis on a linear scale

  • units (dict or str, default=None) – Units to be used in axis labels. Must either be “SI” to use SI units, “dim” to use dimensional labels (“mass”, “volume”, etc), or a dictionary containing elements for mass, volume and time. E.g. units={‘mass’: ‘kg’, ‘volume’: ‘m3’, ‘time’: ‘s’, ‘length’: ‘nm’}. Note that these units are used purely for axis labelling and are not used to modify the model output data (which is unit agnostic). If None (the default), no units are added to labels.

  • cmap (str, default='viridis') – The colormap to use for the plot. Must be one of the colormaps available in matplotlib <https://matplotlib.org/stable/gallery/color/colormap_reference.html>. Note that these are case-sensitive.

  • show_legend (bool, default=True) – Should size classes be shown on a legend?

  • size_classes_to_plot (list of ints, default=None) – Only plot specific size classes by providing a list of size class indices to plot, where 0 is the index of the smallest size class. By default, all size classes are plotted.

Returns

Matplotlib figure and axes objects for the plot

Return type

(matplotlib.figure.Figure, matplotlib.axes.Axes)

Example config and data (fragmentmnp.examples)

Provides example config and data dictionaries for use in the FRAGMENT-MNP model.

Dictionaries

  • full_config: Config with all variables complete

  • minimal_config: Config with only variables that don’t have defaults

  • full_data: Data with all variables complete

  • mininal_data: Data with only variables that don’t have defaults

Validation of config and data (fragmentmnp.validation)

Provides config and input data validation for the FRAGMENT-MNP model

fragmentmnp.validation.validate_config(config: dict) → dict[source]

Validate the given config dict against required schema

Parameters

config (dict) – Model config options

Returns

Validated config dict

Return type

dict

fragmentmnp.validation.validate_data(data: dict, config: dict) → dict[source]

Validate the given data dict against required schema

Parameters

data (dict) – Model input data

Returns

Validated data dict

Return type

dict

previous

Developing with Conda