Hydraulic Processing

Hydraulic Processing#

This page documents the classes and functions in the hydraulic_processing module of the HydroGenerate package.

class HydraulicDesignParameters(flow, design_flow, head, head_loss, max_headloss_allowed, penstock_headloss_method, penstock_headloss_calculation, penstock_length, penstock_diameter, penstock_material, penstock_frictionfactor, channel_average_velocity)#

Bases: object

Hydraulic design parameter container.

This class stores input values needed for penstock head-loss calculations and provides helper methods for computing Reynolds number and a starting design diameter for iterative sizing.

Parameters:

  • flow (float or array-like) – Flow values (m³/s). This may represent a single value or a time series, depending on the calling context.

  • design_flow (float) – Design flow (m³/s).

  • head (float) – Available (gross) head (m).

  • head_loss (float or numpy.ndarray or None) – Head loss for the provided flow values (m). This may be provided by the user or computed by head-loss calculators in this module.

  • max_headloss_allowed (float or None) – Maximum head loss allowed as a percentage of head (%, 1–100). If None, method-specific defaults may be applied.

  • penstock_headloss_method (str or None) – Name of the head-loss method. Current options in this module include "Darcy-Weisbach" and "Hazen-Williams".

  • penstock_headloss_calculation (bool) – Whether to calculate head loss in the penstock. If net head is already available externally, set to False.

  • penstock_length (float or None) – Penstock length (m). Required for head-loss calculations that depend on length.

  • penstock_diameter (float or None) – Penstock diameter (m). If None, some methods may size diameter to meet the allowed head-loss constraint.

  • penstock_material (str or None) – Penstock material key used for roughness selection. Expected options include: CastIron, Concrete, GalvanizedIron, Plastic, Steel.

  • penstock_frictionfactor (float or None) – Friction parameter for the chosen method: - Darcy–Weisbach: friction factor f (if provided), or roughness epsilon used to compute f. - Hazen–Williams: coefficient C. - Manning: n.

  • channel_average_velocity (float or None) – Average cross-sectional water velocity in the channel (Q/A), if applicable.

Notes

Many algorithms in this module mutate attributes on a shared HydraulicDesignParameters instance (e.g., updating penstock_design_diameter during iterations).

reynoldsnumber_calculator()#

Compute and store the Reynolds number for the design condition.

Notes

This method updates self.penstock_design_diameter (if needed) and writes the resulting Reynolds number to self.Re.

The Reynolds number is computed as:

Re = 4 * Q / (pi * D * nu)

where Q is self.design_flow, D is the (design) diameter, and nu is the kinematic viscosity constant defined in this module.

designdiameter_calculator()#

Initialize penstock_design_diameter for calculations.

Notes

  • If self.penstock_diameter is provided, it becomes the design diameter.

  • Otherwise, the method initializes self.penstock_design_diameter to a small starting value (0.01 m) the first time it is needed.

class RoughnessCoefficients(material, darcyweisbach_epsilon, hazenwiliams_c, mannings_n)#

Bases: object

Roughness coefficient record for a penstock material.

Parameters:

  • material (str) – Material identifier key (e.g., "Steel").

  • darcyweisbach_epsilon (float) – Absolute roughness epsilon for Darcy–Weisbach calculations (m).

  • hazenwiliams_c (float) – Hazen–Williams coefficient C (dimensionless).

  • mannings_n (float) – Manning roughness coefficient n (s/m^(1/3)).

class Values#

Bases: object

Catalog of default roughness values.

This nested class provides a dictionary mapping material keys to RoughnessCoefficients instances. Values are sourced from EPANET documentation as indicated in the original code comments.

add_roughnesscoefficient_values(material, darcyweisbach_epsilon, hazenwiliams_c, mannings_n)#

Add a roughness coefficient record for a material key.

Parameters:

  • material (str) – Material identifier key.

  • darcyweisbach_epsilon (float) – Darcy–Weisbach roughness (m).

  • hazenwiliams_c (float) – Hazen–Williams coefficient.

  • mannings_n (float) – Manning n.

Notes

This method mutates self.roughnesscoefficients in place.

class DW_RoughnessSelector#

Bases: Roughness

Darcy–Weisbach roughness selector.

Selects absolute roughness epsilon (m) based on material.

roughness_selector(material)#

Select Darcy–Weisbach absolute roughness epsilon.

Parameters:

material (str or None) – Material identifier key. Defaults to "Steel" when None.

Returns:

Absolute roughness epsilon (m).

Return type:

float

class HW_RoughnessSelector#

Bases: Roughness

Hazen–Williams roughness selector.

Selects Hazen–Williams coefficient C based on material.

roughness_selector(material)#

Select Hazen–Williams coefficient C.

Parameters:

material (str or None) – Material identifier key. Defaults to "Steel" when None.

Returns:

Hazen–Williams coefficient C.

Return type:

float

class Manning_RoughnessSelector#

Bases: Roughness

Manning roughness selector.

Selects Manning coefficient n based on material.

roughness_selector(material)#

Select Manning roughness coefficient n.

Parameters:

material (str or None) – Material identifier key. Defaults to "Concrete" when None.

Returns:

Manning roughness coefficient n.

Return type:

float

class DW_FrictionFactor#

Bases: object

Darcy–Weisbach friction factor calculator.

Computes a Darcy friction factor using regime-dependent formulas: Swamee–Jain approximation (turbulent), Cubic interpolation (transitional), Laminar expression (laminar),

References are preserved from the original inline comments.

frictionfactor_calculator(hydraulic_parameters)#

Compute Darcy–Weisbach friction factor f.

Parameters:

hydraulic_parameters (HydraulicDesignParameters) – Hydraulic parameters containing: penstock_material (str or None), Re (float), penstock_design_diameter (float)

Returns:

Darcy friction factor f (dimensionless).

Return type:

float

Notes

This method does not mutate hydraulic_parameters; it reads from it.

class DarcyWeisbach#

Bases: HeadLoss

Penstock head-loss calculator using Darcy–Weisbach.

penstock_headloss_calculator(hydraulic_parameters)#

Compute Darcy–Weisbach head loss at design flow and update parameters.

Parameters:

hydraulic_parameters (HydraulicDesignParameters) – Parameter container. This method reads (at minimum) design_flow, head, penstock_length, penstock_diameter and updates working values such as penstock_design_diameter, penstock_design_headloss, and penstock_frictionfactor.

Notes

This method mutates hydraulic_parameters in place.

If hydraulic_parameters.penstock_diameter is None, the method will iteratively increase diameter until the computed head loss is less than or equal to the allowed fraction of head (see diameter_check()).

diameter_check(hydraulic_parameters)#

Iteratively increase diameter until head-loss constraint is met.

Parameters:

hydraulic_parameters (HydraulicDesignParameters) – Parameter container updated in place. The method reads max_headloss_allowed, head, penstock_length and updates penstock_design_diameter, penstock_design_headloss, and finally penstock_diameter.

Notes

This method mutates hydraulic_parameters in place.

  • If max_headloss_allowed is None, a default of 10% is used.

  • If penstock_length is None, the method sets design head loss to head * max_headloss_allowed and skips diameter iteration.

  • Otherwise, the method uses recursion via penstock_headloss_calculator() while incrementing diameter by 0.1 m until the constraint is satisfied.

penstock_headloss_calculator_ts(hydraulic_parameters)#

Compute Darcy–Weisbach head loss for a flow time series.

Parameters:

hydraulic_parameters (HydraulicDesignParameters) – Parameter container with: turbine_flow (array-like): flow values (m³/s), penstock_length (float): required, penstock_design_diameter (float), penstock_frictionfactor (float): Darcy friction factor

Raises:

ValueError – If hydraulic_parameters.penstock_length is None.

Notes

This method mutates hydraulic_parameters.head_loss in place by computing head loss for each time-series flow value.

class HazenWilliamns#

Bases: HeadLoss

Penstock head-loss calculator using Hazen–Williams.

Notes

The class name is kept as in the source (HazenWilliamns), though the standard spelling is “HazenWilliams”.

penstock_headloss_calculator(hydraulic_parameters)#

Compute Hazen–Williams head loss and update parameters.

Parameters:

hydraulic_parameters (HydraulicDesignParameters) – Parameter container. This method reads (at minimum) design_flow, head, penstock_length, penstock_diameter and updates penstock_frictionfactor (as Hazen–Williams C), penstock_design_headloss, and potentially penstock_diameter.

Notes

This method mutates hydraulic_parameters in place.

  • If penstock_diameter is provided, head loss is computed directly.

  • If penstock_diameter is None, diameter is computed to satisfy a head-loss allowance (default 10% of head if not provided).

penstock_headloss_calculator_ts(hydraulic_parameters)#

Compute Hazen–Williams head loss for a flow time series.

Parameters:

hydraulic_parameters (HydraulicDesignParameters) – Parameter container with: turbine_flow (array-like): flow values (m³/s), penstock_length (float or None), penstock_design_diameter (float), penstock_frictionfactor (float): Hazen–Williams C

Notes

This method mutates hydraulic_parameters.head_loss in place.

If penstock_length is None, the method returns immediately without modification.

Contents