API Reference

This page exposes the package entry points and the main public modules.

Top-Level Package

mogestpy - A water resources modeling library for Python

A water resources modeling library for Python.

The package is divided into two main submodules: - quantity: Contains classes and functions related to water quantity modeling, such as the SMAP model. - quality: Contains classes and functions related to water quality modeling.

Use the import as the examples below to access the different components of the library:

>>> from mogestpy.quantity.hydrological import smap

Check the project repository for examples and documentation on how to use the library effectively at https://github.com/dariohhossoda/MOGESTpy

Quantity Package

Hydrological Models

Mass balance equation for reservoirs

class mogestpy.quantity.hydrological.mass_balance.MassBalance(Qin, Qout, Delta_t, Vin)

Class representing the mass balance of a system.

Attributes:

Qin (list): List of inflow rates. Qout (list): List of outflow rates. Delta_t (float): Time interval. Vin (float): Initial volume.

Volume_out()

Calculates the volume outflow over time.

Returns:

list: List of volume values at each time step.

Muskingum routing method for hydrological flow routing.

This module implements the Muskingum method for hydrological flow routing, including both linear and non-linear routing methods in upstream and downstream directions.

class mogestpy.quantity.hydrological.muskingum.Muskingum

Implementation of the Muskingum method for hydrological flow routing.

This class provides methods for flow routing using the Muskingum method, including linear and non-linear variants for both upstream and downstream routing.

static downstream_fork(k, x, m, dt, inflow)

Non-linear Muskingum model with fourth-order Runge-Kutta method for routing from upstream to downstream.

This method implements the non-linear Muskingum model using a fourth-order Runge-Kutta numerical integration scheme to route flow from upstream to downstream.

Args:

k (float): Muskingum storage coefficient (time) x (float): Muskingum weighting factor (dimensionless, 0 ≤ x ≤ 0.5) m (float): Muskingum exponent for non-linearity dt (float): Time step inflow (list): List of inflow values (upstream hydrograph)

Returns:

list: List of outflow values (downstream hydrograph)

Parameters:

• k (float)

• x (float)

• m (float)

• dt (float)

• inflow (Sequence[float])

Return type:

list[float]

static downstream_routing(upstream, k, x, dt)

Perform downstream routing from upstream to downstream using the linear Muskingum method.

Args:

upstream (list): List of upstream flow values k (float): Muskingum storage coefficient (time) x (float): Muskingum weighting factor (dimensionless, 0 ≤ x ≤ 0.5) dt (float): Time step

Returns:

list: List of downstream flow values

Parameters:

• upstream (Sequence[float])

• k (float)

• x (float)

• dt (float)

Return type:

list[float]

static upstream_fork(k, x, m, dt, outflow)

Non-linear Muskingum model with fourth-order Runge-Kutta method for routing from downstream to upstream.

This method implements the non-linear Muskingum model using a fourth-order Runge-Kutta numerical integration scheme to route flow from downstream to upstream.

Args:

k (float): Muskingum storage coefficient (time) x (float): Muskingum weighting factor (dimensionless, 0 ≤ x ≤ 0.5) m (float): Muskingum exponent for non-linearity dt (float): Time step outflow (list): List of outflow values (downstream hydrograph)

Returns:

list: List of inflow values (upstream hydrograph)

Parameters:

• k (float)

• x (float)

• m (float)

• dt (float)

• outflow (Sequence[float])

Return type:

list[float]

Hydrodynamic Models

Saint-Venant equations for one-dimensional hydrodynamic routing with trapezoidal cross-section.

This module implements the Saint-Venant equations for one-dimensional hydrodynamic flow routing using a trapezoidal cross-section.

class mogestpy.quantity.hydrodynamic.saint_venant.SaintVenant(cross_section, discharge, manning_n, slope, dt, dx, g=9.81)

Saint-Venant equations for one-dimensional hydrodynamic routing.

This class implements the Saint-Venant equations for one-dimensional hydrodynamic flow routing with a trapezoidal cross-section.

Attributes:

cross_section (TrapezoidalCrossSection): Channel cross-section discharge (float): Flow discharge (m³/s) manning_n (float): Manning’s roughness coefficient slope (float): Channel bed slope (m/m) dt (float): Time step (s) dx (float): Space step (m) g (float): Gravitational acceleration (m/s²)

courant()

Calculate the Courant number.

Returns:

float: Courant number (dimensionless)

courant_check()

Check if the Courant condition for numerical stability is satisfied.

Returns:

bool: True if Courant number <= 1, False otherwise

Return type:

bool

friction_slope()

Calculate the friction slope (energy grade line slope).

Returns:

float: Friction slope (m/m)

Return type:

float

quadratic_froude()

Calculate the square of the Froude number.

Returns:

float: Square of the Froude number (dimensionless)

Return type:

float

run_model()

Run the Saint-Venant model.

Raises:

NotImplementedError: Method not yet implemented

update_values()

Update the state based on the time step.

Raises:

NotImplementedError: Method not yet implemented

class mogestpy.quantity.hydrodynamic.saint_venant.TrapezoidalCrossSection(b, y, m)

Trapezoidal cross-section for channel flow calculations.

This class represents a trapezoidal cross-section with methods to calculate geometric properties such as wet area, wet perimeter, and hydraulic radius.

Attributes:

b (float): Bottom width of the channel (m) y (float): Water depth (m) m (float): Side slope (horizontal/vertical) top_width (float): Width at the water surface (m) hydraulic_radius (float): Hydraulic radius (m)

Parameters:

• b (float)

• y (float)

• m (float)

area_depth(area)

Calculate the water depth for a given wet area using Newton-Raphson method.

Args:

area (float): Wet area (m²)

Returns:

float: Water depth (m)

calculate_top_width()

Calculate the width at the water surface.

Returns:

float: Top width of the water surface (m)

Return type:

float

normal_depth(discharge, manning_n, slope)

Calculate the normal depth using the Newton-Raphson method.

Args:

discharge (float): Flow discharge (m³/s) manning_n (float): Manning’s roughness coefficient slope (float): Channel bed slope (m/m)

Returns:

float: Normal depth (m)

Return type:

float

wet_area()

Calculate the wet area of the cross-section.

Returns:

float: Wet area (m²)

Return type:

float

wet_perimeter()

Calculate the wet perimeter of the cross-section.

Returns:

float: Wet perimeter (m)

Return type:

float

mogestpy.quantity.hydrodynamic.saint_venant.average(values_list, index)

Calculate the centered average of values at a given index.

Args:

values_list (list): List of values index (int): Index for which to calculate the centered average

Returns:

float: Centered average of values at index-1 and index+1,

or None if index is out of bounds

mogestpy.quantity.hydrodynamic.saint_venant.lateral_contribution()

Define the lateral contribution to be included in the model.

Raises:

NotImplementedError: Function not yet implemented

Quality Package

class mogestpy.quality.zero_d.ZeroDimensional(volume, Qin, Qout, Cin, As, k, v, timestep)

Classe de Qualidade da Água em Reservatórios - Modelo 0D Zero-Dimensional

class Input(volume, inflow, outflow, concentration_in, contact_area)

Inputs for the 0D model

Volume (V) - list

Inflow (Qin) - list

Outflow (Qout) - list

Concentration at the inflow (Cin) - list

Contact area (As) - list

class Output(size)

Represents the output of a calculation.

Attributes:

ConcentrationOut (list): A list of concentration values.

class Params(k, v)

Parameters of the 0D model

Reaction Coefficient - k Settling Velocity - v

RunModel()