Species#

module wntr.msx.elements

class Species[source]#

Bases: VariableBase

Biological or chemical species.

Parameters:

name (str) – Species name
species_type – Species type
units – Units of mass for this species, see units property.
atol (float | None) – Absolute tolerance when solving this species’ equations, by default None
rtol (float | None) – Relative tolerance when solving this species’ equations, by default None
note (str | dict | wntr.epanet.util.ENcomment) – Supplementary information regarding this variable, by default None (see NoteType)
diffusivity – Diffusivity of the species in water, by default None
_vars – Reaction system this species is a part of, by default None
_vals – Initial quality values for this species, by default None

Raises:

KeyExistsError – If the name has already been used
TypeError – If atol and rtol are not the same type
ValueError – If atol or rtol ≤ 0

Notes

EPANET-MSX requires that atol and rtol either both be omitted, or both be provided. In order to enforce this, the arguments passed for atol and rtol must both be None or both be positive values.

__init__(name, species_type, units, atol=None, rtol=None, *, note=None, diffusivity=None, _vars=None, _vals=None)[source]#

Variable ABC init method.

Make sure you call this method from your concrete subclass __init__ method:

super().__init__(name, note=note)

Parameters:

name (str) – Name/symbol for the variable. Must be a valid MSX variable name
note ((str | dict | ENcomment), optional keyword) – Supplementary information regarding this variable, by default None (see-also NoteType)

Raises:

KeyExistsError – Name is already taken
ValueError – Name is a reserved word

clear_tolerances()[source]#: Set both tolerances to None, reverting to the global options value.

get_tolerances()[source]#

Get the custom solver tolerances for this species.

Returns:: (atol, rtol) – Absolute and relative tolerances, respectively, if they are set
Return type:: (float, float) or None

set_tolerances(atol, rtol)[source]#

Set the absolute and relative tolerance for the solvers.

The user must set both values, or neither value (None). Values must be positive.

Parameters:

atol (float) – Absolute tolerance to use
rtol (float) – Relative tolerance to use

Raises:

TypeError – If only one of atol or rtol is a float
ValueError – If atol or rtol ≤ 0

to_dict()[source]#

Dictionary representation of the object

The species dictionary has the following format, as described using a json schema.

{
    "title": "Species",
    "type": "object",
    "properties": {
        "name": {
            "type": "string"
        },
        "species_type": {
            "enum": ["bulk", "wall"]
        },
        "units": {
            "type": "string"
        },
        "atol": {
            "type": "number",
            "exclusiveMinimum": 0
        },
        "rtol": {
            "type": "number",
            "exclusiveMinimum": 0
        },
        "note": {
            "type": "string"
        },
        "diffusivity": {
            "type": "number",
            "minimum": 0
        }
    },
    "required": ["name", "species_type", "units", "pipe_reaction", "tank_reaction"],
    "dependentRequired": {"atol": ["rtol"], "rtol":["atol"]}
}

property atol: float#: Absolute tolerance. Must be set using set_tolerances()

diffusivity: float#: Diffusivity of this species in water, if being used, by default None

property initial_quality: InitialQuality#: Initial quality values for the network

name: str#: Name/ID of this variable, must be a valid EPANET/MSX ID

note: str | dict | ENcomment#: Optional note regarding the variable (see NoteType)

property pipe_reaction: Reaction#: Pipe reaction definition

property rtol: float#: Relative tolerance. Must be set using set_tolerances()

property species_type: SpeciesType#: Type of species, either BULK or WALL

property tank_reaction: Reaction#: Tank reaction definition

units: str#: Units of mass for this species. For bulk species, concentration is this unit divided by liters, for wall species, concentration is this unit divided by the model’s area-unit (see options).

property var_type: VariableType#: Type of variable, SPECIES.

Species#

This Page