Hydropower Potential

Hydropower Potential#

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

class EconomicParameters(resource_category, capacity_factor, electricity_sell_price, n_operation_days)#

Bases: object

Economic input parameter container.

Parameters:

  • resource_category (str or None) – Resource category identifier used by the cost model. Examples include 'Non-PoweredDam' and 'NewStream-reachDevelopment' (exact accepted values depend on the downstream model).

  • capacity_factor (float or None) – Capacity factor as a proportion (0–1) for constant-price energy estimation. When using n_operation_days, this may be inferred.

  • electricity_sell_price (float or None) – Electricity sell price ($/kWh). If None, a default wholesale price is used in revenue calculations.

  • n_operation_days (int or float or None) – Number of operation days per year (0–365). Used when capacity factor is not provided.

calculate_head(rated_flow, rated_power)#

Compute net head from rated flow and rated power.

Parameters:

  • rated_flow (float) – Rated flow (m³/s).

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

Returns:

Head (m), computed as:

head = rated_power / (rho * g * rated_flow)

Return type:

float

Notes

  • rated_power is expected in kW, consistent with the rest of this module.

  • rho and g are module-level constants.

class Units#

Bases: object

Unit conversion helper for HydroGenerate parameter objects.

Notes

These methods assume self is an object with the relevant attributes (e.g., the merged all_params object created by calculate_hp_potential()).

  • us_to_si_conversion converts from US customary units to SI.

  • si_to_us_conversion converts from SI back to US customary units.

The conversion is performed in place by mutating the corresponding attributes.

us_to_si_conversion()#

Convert supported attributes from US customary units to SI.

Notes

This method mutates attributes on self in place when they are present.

Expected unit assumptions (US -> SI): - Flow (cfs) -> m³/s - Head/length (ft) -> m - Velocity (ft/s) -> m/s (implemented via ft_to_m multiplier)

si_to_us_conversion()#

Convert supported attributes from SI to US customary units.

Notes

This method mutates attributes on self in place when they are present.

Expected unit conversions (SI -> US): - Flow (m³/s) -> cfs - Head/length (m) -> ft - Velocity (m/s) -> ft/s

class Hydropower#

Bases: ABC

Abstract base class for hydropower calculation workflows.

abstract hydropower_calculation(hp_params)#

Run a hydropower calculation for a parameter container.

Parameters:

hp_params (object) – Parameter container holding hydropower inputs and outputs.

Notes

Implementations typically mutate hp_params in place by setting fields such as rated_power, power, turbine_efficiency, and net_head.

class Basic#

Bases: Hydropower

Basic hydropower calculation using the standard power equation.

hydropower_calculation(hp_params)#

Compute hydropower (or back-calculate missing variable) for basic projects.

Parameters:

hp_params (object) – Parameter container with attributes including: flow (float), head (float), rated_power (float), system_efficiency (float or None), head_loss (float or None)

Raises:

ValueError – If insufficient inputs are provided (at least two of flow, head, rated power must be known).

Notes

This method mutates hp_params in place. It may update: hp_params.head (if head is computed), hp_params.flow (if flow is computed), hp_params.rated_power (if rated power is computed), hp_params.net_head and hp_params.head (net head accounting for head loss), hp_params.penstock_design_headloss (set to None for unit conversion reuse).

class Diversion#

Bases: Hydropower

Diversion (run-of-river) hydropower workflow including turbine and head-loss modeling.

hydropower_calculation(hp_params)#

Compute diversion hydropower potential for single values or time series flows.

Parameters:

hp_params (object) – Parameter container expected to include: Flow inputs: flow / design_flow, and possibly time series metadata, Turbine settings: turbine_type, generator_efficiency, Head-loss settings: penstock_headloss_calculation, penstock_length, penstock_headloss_method, etc., Flow preprocessing settings: minimum flow, maintenance flags

Raises:

ValueError – If turbine type is not supported, head-loss method is not supported, or required inputs (e.g., penstock length when head-loss calculation is enabled) are missing.

Notes

This method mutates hp_params in place. It updates (as available): Flow range / turbine flow series, Turbine efficiencies and power time series, Rated power and net head, Head loss arrays (when penstock head-loss calculations are enabled)

class Hydrokinetic#

Bases: Hydropower

Hydrokinetic (in-stream) hydropower workflow.

hydropower_calculation(hp_params)#

Compute hydrokinetic power based on velocity and swept area.

Parameters:

hp_params (object) – Parameter container expected to include: system_efficiency (percent, optional; defaults to Betz limit), hk_swept_area (m², optional), channel_average_velocity (m/s), Blade geometry if swept area needs to be computed

Notes

This method mutates hp_params in place by updating: system_efficiency (defaulted to 59% if not provided), hk_swept_area (computed if not provided), rated_power (kW)

class ONRL_BaselineCostModeling_V2#

Bases: Cost

ORNL baseline cost model (HBCM v2) implementation.

Notes

The cost method is annotated in the source as derived from the ORNL report: https://info.ornl.gov/sites/publications/files/Pub58666.pdf

The original source code contains some non-ASCII variable symbols in a few expressions (e.g., 𝑃 / 𝐻). They are preserved here as-is to avoid altering runtime behavior.

cost_calculation(hp_params)#

Estimate initial capital cost (ICC) and annual O&M and update parameters.

Parameters:

hp_params (object) – Parameter container expected to include: rated_power (kW), net_head (m), resource_category (str or None)

Raises:

ValueError – If resource_category is not in the accepted list.

Notes

This method mutates hp_params in place by setting: hp_params.icc (million $2014), hp_params.annual_om (million $2014)

class ConstantEletrictyPrice#

Bases: Revenue

Revenue model using a constant electricity price (non-time-indexed flows).

revenue_calculation(hp_params)#

Compute annual energy and revenue using constant price assumptions.

Parameters:

hp_params (object) – Parameter container expected to include: power (array-like): kW time series or flow-range power, capacity_factor (float or None): proportion (0–1), n_operation_days (int/float or None): 0–365, electricity_sell_price (float or None): $/kWh

Raises:

ValueError – If n_operation_days exceeds 365.

Notes

This method mutates hp_params in place by setting: annual_energy_generated (kWh), annual_revenue (million $), and may update capacity_factor / n_operation_days defaults.

class ConstantEletrictyPrice_pd#

Bases: Revenue

Revenue model for a time-indexed pandas DataFrame flow input.

revenue_calculation(hp_params, flow)#

Compute annual energy, revenue, and summary statistics for time series flows.

Parameters:

  • hp_params (object) – Parameter container expected to include: power (array-like): kW time series aligned with flow.index, turbine_flow (array-like): turbine flow aligned with flow.index, rated_power (float): kW, electricity_sell_price (float or None), turbine_efficiency (array-like): turbine efficiency series

  • flow (pandas.DataFrame) – Original user-provided flow DataFrame with a DatetimeIndex.

Notes

This method mutates hp_params in place by setting: dataframe_output : per-timestep outputs (power, energy, efficiency), annual_dataframe_output : annual aggregates including capacity factor and revenue

calculate_hp_potential(flow=None, head=None, rated_power=None, hydropower_type='BASIC', units='US', penstock_headloss_method='Darcy-Weisbach', design_flow=None, system_efficiency=None, generator_efficiency=None, turbine_type=None, head_loss=None, penstock_headloss_calculation=False, penstock_length=None, penstock_diameter=None, penstock_material=None, penstock_frictionfactor=None, pctime_runfull=None, max_headloss_allowed=None, turbine_Rm=None, pelton_n_jets=None, flow_column=None, channel_average_velocity=None, hk_blade_diameter=None, hk_blade_heigth=None, hk_blade_type=None, hk_swept_area=None, annual_caclulation=False, resource_category=None, electricity_sell_price=None, cost_calculation_method='ORNL_HBCM', capacity_factor=None, n_operation_days=None, minimum_turbineflow=None, minimum_turbineflow_percent=None, annual_maintenance_flag=False, major_maintenance_flag=False)#

Calculate hydropower potential and related outputs.

This is the primary user-facing entry point for HydroGenerate. It constructs parameter containers, merges them into a single object, performs unit conversions, runs the requested hydropower calculation workflow, and (optionally) runs cost and annual revenue calculations.

Parameters:

  • flow (array-like or pandas.DataFrame or None) – Flow values. If a DataFrame is provided, a DatetimeIndex is expected for annual calculations and flow_column must indicate which column contains flow values.

  • head (float or None) – Gross head. In US units this is in ft; in SI units this is in m.

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

  • hydropower_type (str or None) – Hydropower calculation type. Supported values: 'BASIC': uses the basic power equation, 'DIVERSION': run-of-river workflow (turbines + head losses), 'HYDROKINETIC': in-stream kinetic workflow, If None, hydropower computation is skipped and only cost calculation (when configured) may run.

  • units ({'US', 'SI'}) – Units of the input values.

  • penstock_headloss_method (str) – Penstock head-loss method (e.g., 'Darcy-Weisbach' or 'Hazen-Williams').

  • design_flow (float or None) – Design flow. If not provided for diversion projects, it may be computed from exceedance logic.

  • system_efficiency (float or None) – System efficiency. For BASIC workflow, used directly; for hydrokinetic, treated as a percent.

  • generator_efficiency (float or None) – Generator efficiency (%) for diversion workflow.

  • turbine_type (str or None) – Turbine type identifier.

  • head_loss (float or None) – External head loss (if already computed), in same unit system as head.

  • penstock_headloss_calculation (bool) – If True, penstock head loss is calculated and applied to compute net head.

  • penstock_length (float or None) – Penstock length.

  • penstock_diameter (float or None) – Penstock diameter.

  • penstock_material (str or None) – Penstock material used for roughness defaults.

  • penstock_frictionfactor (float or None) – Friction parameter value (method-dependent).

  • pctime_runfull (float or None) – Turbine parameter: percent time running full (method-specific).

  • max_headloss_allowed (float or None) – Maximum allowable head loss (percent of head) used for sizing.

  • turbine_Rm (float or None) – Turbine parameter used in turbine selection/parameter calculation.

  • pelton_n_jets (int or None) – Pelton turbine number of jets.

  • flow_column (str or None) – Flow column name when flow is a pandas DataFrame.

  • channel_average_velocity (float or None) – Channel average velocity (m/s).

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

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

  • hk_blade_type (str or None) – Hydrokinetic blade type identifier.

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

  • annual_caclulation (bool) – If True, annual energy and revenue are computed.

  • resource_category (str or None) – Cost model resource category.

  • electricity_sell_price (float or None) – Electricity sell price ($/kWh).

  • cost_calculation_method (str) – Cost calculation method identifier (currently supports 'ORNL_HBCM').

  • capacity_factor (float or None) – Capacity factor (0–1) for annual revenue model when not using a time series.

  • n_operation_days (int or float or None) – Operation days per year (0–365) for annual revenue model.

  • minimum_turbineflow (float or None) – Minimum turbine flow threshold (method-dependent units; converted if needed).

  • minimum_turbineflow_percent (float or None) – Minimum turbine flow as a percent of design flow.

  • annual_maintenance_flag (bool) – Whether to apply annual maintenance downtime (DataFrame/time-series only).

  • major_maintenance_flag (bool) – Whether to apply major maintenance downtime (DataFrame/time-series only).

Returns:

A merged parameter object containing inputs and computed outputs. This includes (as available) attributes such as: rated_power (kW), power (kW series), head_loss (m/ft series), net_head (m/ft), cost outputs (icc, annual_om), revenue outputs (annual_energy_generated, annual_revenue), DataFrame summaries when applicable

Return type:

object

Raises:

ValueError – If: units is not 'US' or 'SI', hydropower_type is invalid, required inputs are missing for the chosen workflow

Contents