windrex 0.1.0__py3-none-any.whl

windrex/__init__.py

@@ -0,0 +1,57 @@
+"""
+WindreX — Wind Resource eXchange
+
+A Python library for wind resource assessment, wake modeling, turbine database
+management, and capacity factor computation.
+
+Modules:
+- windrex.core: Weibull, wind rose, shear, temporal, wake, capacity factor
+- windrex.data: Open-Meteo, NASA POWER, ERA5, terrain, LULC, turbine DB
+- windrex.economics: Financial analysis and LCOE sensitivity
+- windrex.analysis: MCDA engine and grid evaluation
+- windrex.regional: Regional analyzer and zone generation
+"""
+
+__version__ = "0.1.0"
+__author__ = "WindreX Development Team"
+
+from .core.weibull import fit_weibull, weibull_pdf, weibull_mean_power_density
+from .core.wind_rose import compute_wind_rose, WindRoseData
+from .core.shear import compute_wind_shear, extrapolate_speed
+from .core.temporal import compute_diurnal_pattern, compute_seasonal_pattern
+from .core.wake import jensen_wake_deficit, compute_array_efficiency, compute_spacing_curve
+
+__all__ = [
+    "__version__",
+    # Weibull
+    "fit_weibull",
+    "weibull_pdf",
+    "weibull_mean_power_density",
+    # Wind rose
+    "compute_wind_rose",
+    "WindRoseData",
+    # Shear
+    "compute_wind_shear",
+    "extrapolate_speed",
+    # Temporal
+    "compute_diurnal_pattern",
+    "compute_seasonal_pattern",
+    # Wake
+    "jensen_wake_deficit",
+    "compute_array_efficiency",
+    "compute_spacing_curve",
+]
+
+
+def __getattr__(name):
+    """Lazy import for heavy modules."""
+    if name == "compute_wind_hourly_cf":
+        from .core.capacity_factor import compute_wind_hourly_cf
+        return compute_wind_hourly_cf
+    if name == "WindAnalyzer":
+        from .regional.analyzer import WindAnalyzer
+        return WindAnalyzer
+    if name == "compute_wind_financials":
+        from .economics.financial import compute_wind_financials
+        return compute_wind_financials
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

windrex/analysis/__init__.py

@@ -0,0 +1,9 @@
+"""Analysis modules for wind resource assessment."""
+
+from .mcda import compute_mcda_scores, entropy_weights, pca_weights
+
+__all__ = [
+    "compute_mcda_scores",
+    "entropy_weights",
+    "pca_weights",
+]

windrex/analysis/grid.py

@@ -0,0 +1,117 @@
+"""Grid evaluation and zone generation for wind assessment."""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+
+def build_grid(
+    bounds: tuple[float, float, float, float],
+    resolution: float = 0.25,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Build regular lat/lon grid within domain bounds.
+
+    Parameters
+    ----------
+    bounds : tuple
+        (south, west, north, east) in degrees.
+    resolution : float
+        Grid spacing in degrees.
+
+    Returns
+    -------
+    tuple[np.ndarray, np.ndarray]
+        (lats, lons) — 1D arrays of grid coordinates.
+    """
+    south, west, north, east = bounds
+    lats = np.arange(south + resolution / 2, north, resolution)
+    lons = np.arange(west + resolution / 2, east, resolution)
+    if len(lats) == 0:
+        lats = np.array([(south + north) / 2])
+    if len(lons) == 0:
+        lons = np.array([(west + east) / 2])
+    return lats, lons
+
+
+def compute_distance_to_grid(
+    grid_points: list[dict],
+    transmission_lines: list[dict],
+    bounds: tuple[float, float, float, float],
+) -> list[float]:
+    """Compute minimum distance from each grid point to nearest transmission line.
+
+    Parameters
+    ----------
+    grid_points : list[dict]
+        List of dicts with 'lat' and 'lon' keys.
+    transmission_lines : list[dict]
+        List of line dicts with 'coords' key (list of [lat, lon] pairs).
+    bounds : tuple
+        (south, west, north, east) for latitude correction.
+
+    Returns
+    -------
+    list[float]
+        Distance in km per grid point.
+    """
+    n = len(grid_points)
+    if not transmission_lines:
+        return [0.0] * n
+
+    line_coords = []
+    for line in transmission_lines:
+        coords = line.get("coords", [])
+        for coord in coords:
+            line_coords.append((coord[0], coord[1]))
+
+    if not line_coords:
+        return [0.0] * n
+
+    south, west, north, east = bounds
+    lc = np.array(line_coords)
+    km_per_deg_lat = 111.32
+    mid_lat = (south + north) / 2
+    km_per_deg_lon = 111.32 * math.cos(math.radians(mid_lat))
+
+    pt_lats = np.array([pt["lat"] for pt in grid_points])
+    pt_lons = np.array([pt["lon"] for pt in grid_points])
+
+    dy = (pt_lats[:, None] - lc[None, :, 0]) * km_per_deg_lat
+    dx = (pt_lons[:, None] - lc[None, :, 1]) * km_per_deg_lon
+    dist = np.sqrt(dx ** 2 + dy ** 2)
+
+    return np.min(dist, axis=1).tolist()
+
+
+def wind_cf_from_speed(
+    ws_hourly: np.ndarray,
+    pc_wind_speeds: list[float],
+    pc_power_mw: list[float],
+    rated_mw: float,
+) -> float:
+    """Compute mean capacity factor from hourly wind speeds and power curve.
+
+    Parameters
+    ----------
+    ws_hourly : np.ndarray
+        Hourly wind speed at hub height (m/s).
+    pc_wind_speeds : list[float]
+        Power curve wind speeds (m/s).
+    pc_power_mw : list[float]
+        Power curve output (MW).
+    rated_mw : float
+        Turbine rated power (MW).
+
+    Returns
+    -------
+    float
+        Mean capacity factor.
+    """
+    if not pc_wind_speeds or not pc_power_mw or rated_mw <= 0:
+        return 0.0
+
+    ws = np.asarray(ws_hourly, dtype=float)
+    power_out = np.interp(ws, pc_wind_speeds, pc_power_mw, left=0.0, right=0.0)
+    return float(np.nanmean(power_out) / rated_mw)

windrex/analysis/mcda.py

@@ -0,0 +1,143 @@
+"""Multi-Criteria Decision Analysis (MCDA) engine.
+
+Supports three weighting methods:
+- Shannon entropy weights
+- PCA-based weights (first principal component loadings)
+- Manual weights (user-supplied)
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def compute_mcda_scores(
+    grid_points: list[dict],
+    criteria: dict[str, dict],
+    method: str = "entropy",
+) -> tuple[np.ndarray, dict[str, float]]:
+    """Compute MCDA composite scores for grid points.
+
+    Parameters
+    ----------
+    grid_points : list[dict]
+        List of dicts with criterion values as keys.
+    criteria : dict[str, dict]
+        Criteria configuration. Each key maps to a dict with:
+        - 'enabled': bool
+        - 'weight': float (for manual method)
+        - 'direction': 'maximize' or 'minimize'
+    method : str
+        Weighting method: 'entropy', 'pca', or 'manual'.
+
+    Returns
+    -------
+    tuple[np.ndarray, dict[str, float]]
+        (scores, computed_weights) — composite scores per grid point
+        and the weights used.
+    """
+    enabled = {name: c for name, c in criteria.items() if c.get("enabled", True)}
+    criteria_names = list(enabled.keys())
+    n_cells = len(grid_points)
+    n_criteria = len(criteria_names)
+
+    if n_cells == 0 or n_criteria == 0:
+        return np.zeros(n_cells), {}
+
+    # Build raw matrix
+    raw_matrix = np.zeros((n_cells, n_criteria))
+    for j, name in enumerate(criteria_names):
+        for i, pt in enumerate(grid_points):
+            raw_matrix[i, j] = pt.get(name, 0.0)
+
+    # Min-max normalization
+    norm_matrix = np.zeros_like(raw_matrix)
+    for j in range(n_criteria):
+        col = raw_matrix[:, j]
+        col_min, col_max = col.min(), col.max()
+        if col_max - col_min > 1e-10:
+            norm_matrix[:, j] = (col - col_min) / (col_max - col_min)
+        else:
+            norm_matrix[:, j] = 0.5
+
+        # Invert for minimize criteria
+        if enabled[criteria_names[j]].get("direction", "maximize") == "minimize":
+            norm_matrix[:, j] = 1.0 - norm_matrix[:, j]
+
+    # Compute weights
+    if method == "entropy":
+        weights = entropy_weights(norm_matrix)
+    elif method == "pca":
+        weights = pca_weights(norm_matrix)
+    else:
+        raw_w = np.array([enabled[name].get("weight", 1.0) for name in criteria_names])
+        total_w = raw_w.sum()
+        weights = raw_w / total_w if total_w > 0 else np.ones(n_criteria) / n_criteria
+
+    computed = {name: float(weights[j]) for j, name in enumerate(criteria_names)}
+    scores = norm_matrix @ weights
+
+    return scores, computed
+
+
+def entropy_weights(norm_matrix: np.ndarray) -> np.ndarray:
+    """Compute weights using Shannon entropy method.
+
+    Parameters
+    ----------
+    norm_matrix : np.ndarray
+        Normalized decision matrix, shape (n_alternatives, n_criteria).
+
+    Returns
+    -------
+    np.ndarray
+        Weights per criterion.
+    """
+    n, m = norm_matrix.shape
+    if n <= 1:
+        return np.ones(m) / m
+
+    shifted = norm_matrix + 1e-10
+    col_sums = shifted.sum(axis=0)
+    col_sums[col_sums == 0] = 1
+    p = shifted / col_sums
+
+    k = 1.0 / np.log(n)
+    with np.errstate(divide="ignore", invalid="ignore"):
+        H = -k * np.nansum(p * np.log(p + 1e-30), axis=0)
+
+    d = np.maximum(1.0 - H, 0)
+    total = d.sum()
+    if total > 0:
+        return d / total
+    return np.ones(m) / m
+
+
+def pca_weights(norm_matrix: np.ndarray) -> np.ndarray:
+    """Compute weights from first principal component loadings.
+
+    Parameters
+    ----------
+    norm_matrix : np.ndarray
+        Normalized decision matrix.
+
+    Returns
+    -------
+    np.ndarray
+        Weights per criterion.
+    """
+    n, m = norm_matrix.shape
+    if n <= m or m <= 1:
+        return np.ones(m) / m
+
+    std = norm_matrix.std(axis=0)
+    std[std == 0] = 1
+    standardized = (norm_matrix - norm_matrix.mean(axis=0)) / std
+
+    # SVD-based PCA (no sklearn dependency)
+    _, _, Vt = np.linalg.svd(standardized, full_matrices=False)
+    loadings = np.abs(Vt[0])
+    total = loadings.sum()
+    if total > 0:
+        return loadings / total
+    return np.ones(m) / m

windrex/config.py

@@ -0,0 +1,118 @@
+"""Configuration dataclasses for WindreX."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class TurbineSpec:
+    """Technical specification of a wind turbine.
+
+    Parameters
+    ----------
+    key : str
+        Unique identifier (e.g. 'Vestas_V112_3MW').
+    name : str
+        Display name.
+    manufacturer : str
+        Manufacturer name.
+    rated_power_mw : float
+        Rated power in MW.
+    rotor_diameter_m : float
+        Rotor diameter in meters.
+    hub_height_m : float
+        Hub height in meters.
+    source : str
+        Database source ('atlite', 'oedb', 'custom').
+    wind_speeds : list[float]
+        Power curve wind speed bins (m/s).
+    power_curve : list[float]
+        Power curve output values (MW).
+    """
+
+    key: str = ""
+    name: str = ""
+    manufacturer: str = ""
+    rated_power_mw: float = 3.0
+    rotor_diameter_m: float = 112.0
+    hub_height_m: float = 80.0
+    source: str = "custom"
+    wind_speeds: list[float] = field(default_factory=list)
+    power_curve: list[float] = field(default_factory=list)
+
+
+@dataclass
+class CriterionConfig:
+    """Configuration for a single MCDA criterion.
+
+    Parameters
+    ----------
+    name : str
+        Criterion name (e.g. 'mean_speed', 'slope', 'elevation').
+    weight : float
+        Manual weight (0-1). Ignored if using entropy/PCA weights.
+    is_benefit : bool
+        True if higher is better; False if lower is better.
+    enabled : bool
+        Whether this criterion is active.
+    """
+
+    name: str = ""
+    weight: float = 1.0
+    is_benefit: bool = True
+    enabled: bool = True
+
+
+@dataclass
+class MCDAConfig:
+    """Configuration for MCDA site suitability analysis.
+
+    Parameters
+    ----------
+    method : str
+        Weighting method: 'entropy', 'pca', 'manual'.
+    criteria : list[CriterionConfig]
+        List of criterion configurations.
+    n_zones : int
+        Number of development zones to generate.
+    min_zone_area_km2 : float
+        Minimum zone area in km².
+    """
+
+    method: str = "entropy"
+    criteria: list[CriterionConfig] = field(default_factory=list)
+    n_zones: int = 5
+    min_zone_area_km2: float = 1.0
+
+
+@dataclass
+class WindConfig:
+    """Master configuration for wind resource analysis.
+
+    Parameters
+    ----------
+    bounds : tuple[float, float, float, float]
+        Geographic bounds (lat_min, lon_min, lat_max, lon_max).
+    turbine : TurbineSpec
+        Turbine specification.
+    hub_height_m : float
+        Analysis hub height in meters.
+    grid_resolution : float
+        Grid resolution in degrees.
+    data_source : str
+        Wind data source: 'open_meteo', 'nasa_power', 'era5'.
+    year : int
+        Analysis year.
+    mcda : MCDAConfig
+        MCDA configuration.
+    """
+
+    bounds: tuple[float, float, float, float] = (0.0, 0.0, 1.0, 1.0)
+    turbine: TurbineSpec = field(default_factory=TurbineSpec)
+    hub_height_m: float = 80.0
+    grid_resolution: float = 0.25
+    data_source: str = "open_meteo"
+    year: int = 2023
+    mcda: MCDAConfig = field(default_factory=MCDAConfig)

windrex/core/__init__.py

@@ -0,0 +1,15 @@
+"""Core wind resource computation modules."""
+
+from .weibull import fit_weibull, weibull_pdf, weibull_mean_power_density
+from .wind_rose import compute_wind_rose, WindRoseData
+from .shear import compute_wind_shear, extrapolate_speed
+from .temporal import compute_diurnal_pattern, compute_seasonal_pattern
+from .wake import jensen_wake_deficit, compute_array_efficiency, compute_spacing_curve
+
+__all__ = [
+    "fit_weibull", "weibull_pdf", "weibull_mean_power_density",
+    "compute_wind_rose", "WindRoseData",
+    "compute_wind_shear", "extrapolate_speed",
+    "compute_diurnal_pattern", "compute_seasonal_pattern",
+    "jensen_wake_deficit", "compute_array_efficiency", "compute_spacing_curve",
+]

windrex/core/capacity_factor.py

@@ -0,0 +1,144 @@
+"""Wind hourly capacity factor computation.
+
+Computes hourly CF time series from wind speed reanalysis data
+using turbine power curves and hub-height wind speed extrapolation.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+_HOURS_PER_YEAR = 8760
+_FEB29_START = 24 * (31 + 28)
+_FEB29_END = _FEB29_START + 24
+
+# Default turbine: Vestas V112 3.0 MW
+_DEFAULT_WIND_SPEEDS = [
+    0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15,
+    16, 17, 18, 19, 20, 21, 22, 23, 24, 25,
+]
+_DEFAULT_POWER_CURVE_MW = [
+    0, 0, 0, 0.032, 0.16, 0.36, 0.67, 1.08, 1.58, 2.12,
+    2.58, 2.85, 2.98, 3.0, 3.0, 3.0,
+    3.0, 3.0, 3.0, 3.0, 3.0, 3.0, 3.0, 3.0, 3.0, 0,
+]
+_DEFAULT_RATED_MW = 3.0
+
+
+def compute_wind_hourly_cf(
+    lat: float,
+    lon: float,
+    year: int,
+    data_source: str = "open_meteo",
+    wind_speeds: Optional[list[float]] = None,
+    power_curve: Optional[list[float]] = None,
+    rated_power_mw: float = _DEFAULT_RATED_MW,
+    hub_height: int = 80,
+    turbine_key: Optional[str] = None,
+) -> np.ndarray:
+    """Compute hourly wind capacity factor for a single location.
+
+    Parameters
+    ----------
+    lat, lon : float
+        Geographic coordinates (WGS84).
+    year : int
+        Calendar year for weather data.
+    data_source : str
+        One of 'open_meteo', 'nasa_power', 'era5'.
+    wind_speeds : list[float] or None
+        Power curve wind speeds (m/s).
+    power_curve : list[float] or None
+        Power curve output (MW).
+    rated_power_mw : float
+        Turbine rated power (MW).
+    hub_height : int
+        Hub height in meters.
+    turbine_key : str or None
+        Turbine key to look up power curve from database.
+
+    Returns
+    -------
+    np.ndarray
+        Hourly capacity factors, shape (8760,), values in [0, 1].
+    """
+    pc_ws, pc_mw, rated = _resolve_power_curve(
+        wind_speeds, power_curve, rated_power_mw, turbine_key,
+    )
+
+    if data_source == "era5":
+        from windrex.data.era5 import compute_era5_wind_cf
+        return compute_era5_wind_cf(lat, lon, year, turbine_key, hub_height)
+
+    if data_source == "nasa_power":
+        from windrex.data.nasa_power import fetch_nasa_power_wind
+        ws_hourly = fetch_nasa_power_wind(lat, lon, year, hub_height)
+    else:
+        from windrex.data.open_meteo import fetch_open_meteo_wind
+        ws_hourly = fetch_open_meteo_wind(lat, lon, year, hub_height)
+
+    if ws_hourly is None:
+        logger.warning(
+            "Failed to fetch wind data for (%.4f, %.4f) year %d, returning zeros.",
+            lat, lon, year,
+        )
+        return np.zeros(_HOURS_PER_YEAR)
+
+    cf = _wind_speed_to_hourly_cf(ws_hourly, pc_ws, pc_mw, rated)
+    return normalize_to_8760(cf)
+
+
+def _wind_speed_to_hourly_cf(
+    ws_hourly: np.ndarray,
+    pc_wind_speeds: list[float],
+    pc_power_mw: list[float],
+    rated_mw: float,
+) -> np.ndarray:
+    """Convert hourly wind speeds to capacity factors using power curve."""
+    if not pc_wind_speeds or not pc_power_mw or rated_mw <= 0:
+        return np.zeros(len(ws_hourly))
+
+    ws = np.asarray(ws_hourly, dtype=float)
+    power_out = np.interp(ws, pc_wind_speeds, pc_power_mw, left=0.0, right=0.0)
+    cf = power_out / rated_mw
+    return np.clip(cf, 0.0, 1.0)
+
+
+def _resolve_power_curve(
+    wind_speeds: Optional[list[float]],
+    power_curve: Optional[list[float]],
+    rated_power_mw: float,
+    turbine_key: Optional[str],
+) -> tuple[list[float], list[float], float]:
+    """Resolve power curve from explicit values or turbine database."""
+    if wind_speeds and power_curve:
+        return wind_speeds, power_curve, rated_power_mw
+
+    if turbine_key:
+        from windrex.data.turbine_db import load_turbine_database
+        turbines = load_turbine_database()
+        for t in turbines:
+            if t.key == turbine_key:
+                return t.wind_speeds, t.power_curve, t.rated_power_mw
+        logger.warning("Turbine '%s' not found, using default.", turbine_key)
+
+    return _DEFAULT_WIND_SPEEDS, _DEFAULT_POWER_CURVE_MW, _DEFAULT_RATED_MW
+
+
+def normalize_to_8760(cf: np.ndarray) -> np.ndarray:
+    """Ensure output has exactly 8760 hours (remove Feb 29 for leap years)."""
+    n = len(cf)
+    if n == _HOURS_PER_YEAR:
+        return cf
+    if n == 8784:
+        return np.concatenate([cf[:_FEB29_START], cf[_FEB29_END:]])
+    if n > _HOURS_PER_YEAR:
+        return cf[:_HOURS_PER_YEAR]
+    padded = np.zeros(_HOURS_PER_YEAR)
+    padded[:n] = cf
+    return padded

windrex/core/shear.py

@@ -0,0 +1,80 @@
+"""Wind shear (power-law) analysis.
+
+Computes the wind shear exponent from dual-height measurements
+and extrapolates wind speeds to arbitrary heights.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def compute_wind_shear(
+    speeds_low: np.ndarray,
+    speeds_high: np.ndarray,
+    h_low: float,
+    h_high: float,
+) -> float:
+    """Compute power-law wind shear exponent alpha.
+
+    v2/v1 = (h2/h1)^alpha → alpha = ln(v2/v1) / ln(h2/h1)
+
+    Parameters
+    ----------
+    speeds_low : np.ndarray
+        Wind speeds at lower height (m/s).
+    speeds_high : np.ndarray
+        Wind speeds at upper height (m/s).
+    h_low : float
+        Lower measurement height (m).
+    h_high : float
+        Upper measurement height (m).
+
+    Returns
+    -------
+    float
+        Wind shear exponent alpha. Returns IEC default (0.143) if
+        insufficient valid data.
+    """
+    speeds_low = np.asarray(speeds_low, dtype=float)
+    speeds_high = np.asarray(speeds_high, dtype=float)
+
+    mask = (speeds_low > 0.5) & (speeds_high > 0.5)
+    if np.sum(mask) < 5:
+        return 0.143  # IEC default (open terrain)
+
+    ratio = np.mean(speeds_high[mask]) / np.mean(speeds_low[mask])
+    if ratio <= 0:
+        return 0.143
+
+    alpha = np.log(ratio) / np.log(h_high / h_low)
+    return float(np.clip(alpha, 0.0, 0.6))
+
+
+def extrapolate_speed(
+    speed_ref: float,
+    h_ref: float,
+    h_target: float,
+    alpha: float,
+) -> float:
+    """Extrapolate wind speed to a different height using power law.
+
+    v_target = v_ref * (h_target / h_ref) ^ alpha
+
+    Parameters
+    ----------
+    speed_ref : float
+        Reference wind speed (m/s).
+    h_ref : float
+        Reference height (m).
+    h_target : float
+        Target height (m).
+    alpha : float
+        Wind shear exponent.
+
+    Returns
+    -------
+    float
+        Extrapolated wind speed (m/s).
+    """
+    return speed_ref * (h_target / h_ref) ** alpha