Turbine Calculation

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

class TurbineParameters(turbine_type, flow, design_flow, flow_column, head, rated_power, system_efficiency, generator_efficiency, Rm, pctime_runfull, pelton_n_jets, hk_blade_diameter, hk_blade_heigth, hk_blade_type, hk_swept_area)

Bases: object

Turbine parameter container used by HydroGenerate workflows.

This class stores the turbine-related inputs (head, flow, efficiencies, turbine selection controls) and computed outputs (efficiency curve, runner diameter, turbine-flow array, and optional DataFrame outputs).

Parameters:

• turbine_type (str or None) – Turbine type name. Typical options include: 'Kaplan', 'Francis', 'Pelton', 'Turgo', 'Crossflow', 'Propeller', 'Hydrokinetic'. If None, a turbine type may be selected using turbine_type_selector().

• flow (float, array-like, or pandas.Series) – Flow input (m³/s or cfs depending on upstream unit handling). May be a single value or a time series / array.

• design_flow (float or None) – Design flow for the hydropower system. If None and flow is a series, it can be computed using PercentExceedance.

• flow_column (str or None) – If flow was originally provided as a pandas DataFrame elsewhere in the workflow, this is the name of the column containing flow values.

• head (float or None) – Hydraulic head (m or ft depending on upstream unit handling).

• rated_power (float or None) – Rated power (kW).

• system_efficiency (float or None) – Overall system efficiency (proportion, 0–1) used in some workflows.

• generator_efficiency (float or None) – Generator efficiency (percent or proportion depending on upstream usage). HydroGenerate commonly defaults this to ~98% in the main workflow.

• Rm (float or None) – Turbine manufacture/design coefficient used in peak efficiency formulas. If None, this class sets a default of 4.5.

• pctime_runfull (float or None) – Percent of time the turbine will run full (used for design-flow selection via exceedance logic). If None, a default is used by PercentExceedance.

• pelton_n_jets (int or None) – Number of jets for a Pelton turbine. If None, defaults to 3 in PeltonTurbine.

• hk_blade_diameter (float or None) – Hydrokinetic blade diameter (m).

• hk_blade_heigth (float or None) – Hydrokinetic blade height (m).

• hk_blade_type (str or None) – Hydrokinetic blade type identifier. Typical values: 'ConventionalRotor', 'H-DarrieusRotor', 'DarrieusRotor'.

• hk_swept_area (float or None) – Hydrokinetic swept area (m²). If None, may be computed by Hydrokinetic_Turbine.

This class initializes the calculation of all turbines parameters. Parameter descriptions are provided below:

turbine_type_selector(hp_params)

Select an appropriate turbine type based on head and design flow.

The selection is based on which turbine “region of influence” polygons contain the point (design_flow, head). If multiple regions contain the point, the turbine whose polygon centroid is closest to the point is selected.

Parameters:

hp_params (object) – Parameter container is expected to provide, head (float), hydraulic head (m), design_flow (float): design flow (m³/s).

Raises:

ValueError – If the (head, design_flow) point does not fall within any supported turbine regions.

Notes

This function mutates hp_params in place.

The function updates hp_params.turbine_type (str), hp_params.turbine_type_dict (dict[str, float]) mapping candidates to centroid distances.

class FlowRange

Bases: object

Flow range generation helper.

Notes

This helper is used to expand a single flow value into a flow range for evaluating turbine efficiency curves across operating conditions.

flowrange_calculator(turbine)

Expand a single flow value into a range for turbine evaluation.

If turbine.flow is a scalar number, it is expanded to a range from 50% to max_flow_turbine of the provided value (18 evenly spaced points).

Parameters:

turbine (object) – Parameter container expected to include flow.

Notes

This method mutates turbine.flow in place. The turbine calculators in this file often expect a flow array to compute efficiency curves.

class ReactionTurbines

Bases: object

Sizing utilities for reaction turbines (e.g., Francis, Kaplan, Propeller).

runnersize_calculator(design_flow)

Compute an estimated runner throat diameter for reaction turbines.

Parameters:

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

Returns:

Runner throat diameter (m), computed using a piecewise coefficient.

Return type:

float

Notes

The coefficient k changes for higher flows to avoid a region in the source correlation described as “undefined” in the original comments.

class FrancisTurbine

Bases: Turbine

Francis turbine efficiency curve calculator.

turbine_calculator(turbine)

Compute Francis turbine efficiency across a flow range.

Parameters:

turbine (object) – Container expected to include: design_flow (float), head (float), Rm (float), flow (float or array-like)

Notes

This method mutates turbine in place. It computes: turbine.turbine_efficiency (numpy.ndarray), turbine.runner_diameter (float)

The efficiency formulation follows correlations cited in the original comments (CANMET Energy Technology Center, 2004).

class KaplanTurbine

Bases: Turbine

Kaplan turbine efficiency curve calculator.

turbine_calculator(turbine)

Compute Kaplan turbine efficiency across a flow range.

Parameters:

turbine (object) – Container expected to include: design_flow (float), head (float), Rm (float), flow (float or array-like)

Notes

This method mutates turbine in place by setting: turbine.turbine_flow (array-like), turbine.turbine_efficiency (numpy.ndarray), turbine.runner_diameter (float)

class PropellerTurbine

Bases: Turbine

Propeller turbine efficiency curve calculator.

turbine_calculator(turbine)

Compute Propeller turbine efficiency across a flow range.

Parameters:

turbine (object) – Container expected to include: design_flow (float), head (float), Rm (float), flow (float or array-like)

Notes

This method mutates turbine in place by setting: turbine.turbine_flow (array-like), turbine.turbine_efficiency (numpy.ndarray), turbine.runner_diameter (float)

class PeltonTurbine

Bases: Turbine

Pelton turbine efficiency curve calculator.

turbine_calculator(turbine)

Compute Pelton turbine efficiency across a flow range.

Parameters:

turbine (object) – Container expected to include: head (float), design_flow (float), pelton_n_jets (int or None), flow (float or array-like)

Notes

This method mutates turbine in place by setting: turbine.turbine_flow (array-like), turbine.turbine_efficiency (numpy.ndarray), turbine.runner_diameter (float)

If turbine.pelton_n_jets is None, a default of 3 is used.

class TurgoTurbine

Bases: Turbine

Turgo turbine efficiency curve calculator (derived from Pelton).

turbine_calculator(turbine)

Compute Turgo turbine efficiency across a flow range.

Parameters:

turbine (object) – Container compatible with PeltonTurbine.

Notes

This method mutates turbine in place. It first computes Pelton efficiency and then subtracts 0.03, clipping negative values to zero.

class CrossFlowTurbine

Bases: Turbine

Crossflow turbine efficiency curve calculator.

turbine_calculator(turbine)

Compute Crossflow turbine efficiency across a flow range.

Parameters:

turbine (object) – Container expected to include: design_flow (float), flow (float or array-like)

Notes

This method mutates turbine in place by setting: turbine.turbine_flow (array-like), turbine.turbine_efficiency (numpy.ndarray)

class Hydrokinetic_Turbine

Bases: Turbine

Hydrokinetic turbine swept-area calculator.

This calculator derives the swept area for hydrokinetic turbines based on rotor diameter and (for Darrieus-type rotors) blade height.

turbine_calculator(turbine)

Compute hydrokinetic swept area and update the container.

Parameters:

turbine (object) – Container expected to include hydrokinetic attributes: hk_blade_type (str or None), hk_blade_diameter (float or None), hk_blade_heigth (float or None)

Notes

This method mutates turbine in place by setting: hk_blade_type, hk_blade_diameter (default 1 m if missing), hk_blade_heigth (default 1 m if missing for Darrieus-type), hk_swept_area (m²)

class PercentExceedance

Bases: DesignFlow

Design-flow selection using a specified percent exceedance.

This method computes a flow duration curve (FDC) from a flow series and selects the design flow as the flow value exceeded pctime_runfull percent of the time.

designflow_calculator(turbine)

Compute and set design flow based on percent exceedance.

Parameters:

turbine (object) – Container expected to include: flow (float or array-like), pctime_runfull (float or None)

Raises:

ValueError – If a flow series is provided and no percentile value exists for the computed exceedance percentage.

Notes

This method mutates turbine in place by setting: turbine.design_flow (float), turbine.pctime_runfull (rounded percent exceedance), turbine.flowduration_curve (pandas.DataFrame) when using series input

Defaults

If turbine.pctime_runfull is None, a default of 30 is used. If turbine.flow is a scalar, the scalar is treated as the design flow.