dynbem 0.1.0__py3-none-any.whl

dynbem/__init__.py

@@ -0,0 +1,212 @@
+"""Aerodynamic interfaces and factory hooks."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+import numpy as np
+
+from .rotor_state import PittPetersRotorState, QuasiStaticRotorState, RotorState
+from .polar import AirfoilPolar, LinearPolar
+
+
+@dataclass
+class AeroResult:
+    """Return type for compute_forces().
+
+    Fields
+    ------
+    F_world   [3] Net aerodynamic force on the rotor in world (NED) frame, N.
+              Equal to ``-T_total * hub_axis_ned``; for a level rotor with
+              positive thrust, ``F_world[2] < 0`` (upward = −Z).
+    M_orbital [3] In-plane hub moments from non-axisymmetric thrust, world
+              frame. Accumulated per-element as ``r · dT · [sin ψ, cos ψ, 0]``
+              in hub frame and rotated via ``R_hub``. Non-zero in forward
+              flight (advancing/retreating velocity asymmetry) and under
+              cyclic input. Zero in axisymmetric hover. See CLAUDE.md.
+    Q_spin    Shaft drag torque magnitude, N·m. Positive in powered hover
+              (aero drag opposes rotor motion). Drives the rotor speed ODE
+              via ``d_omega = (-Q_spin + motor_torque) / I_ode``.
+    M_spin    [3] Reaction torque on the airframe from the rotor system
+              (shaft + motor stator), world frame. For our CCW-from-above
+              convention this is ``+Q_spin * hub_axis_ned`` — airframe is
+              pushed to spin CW from above (American helicopter yaw-right
+              tendency without tail rotor).
+    """
+    F_world:   np.ndarray   # [3]
+    M_orbital: np.ndarray   # [3]
+    Q_spin:    float
+    M_spin:    np.ndarray   # [3]
+
+
+@dataclass
+class RotorInputs:
+    """External driving conditions imposed on the rotor each timestep.
+
+    These are quantities the vehicle or environment sets — nothing here
+    has a derivative owned by the aero model. Rotor mechanical and inflow
+    states (omega, spin_angle, lambda) live in RotorState instead.
+
+    Fields
+    ------
+    collective_rad   collective pitch angle, rad
+    tilt_lon         longitudinal swashplate tilt, rad. Helicopter-standard
+                     sign: positive → nose-down (forward stick). Mapped to
+                     blade pitch via dynbem.cyclic.cyclic_coeffs() using the
+                     rotor's ControlProperties (gain, phase). With default
+                     gain=1, phase=0 (control=None) this acts as the
+                     direct θ_1c blade-pitch amplitude with helicopter signs.
+    tilt_lat         lateral swashplate tilt, rad. Helicopter-standard sign:
+                     positive → roll right.
+    R_hub            [3x3] rotation matrix, hub frame to world frame
+    v_hub_world      [3] hub velocity in world frame, m/s
+    wind_world       [3] wind velocity in world frame, m/s
+    t                simulation time, s
+    rho_kg_m3        air density, kg/m³ (default ISA sea level)
+    motor_torque_Nm  shaft torque applied by motor/generator, N·m
+                     positive = driving rotor, negative = braking
+                     zero (default) = pure autorotation
+    """
+
+    collective_rad:  float
+    tilt_lon:        float
+    tilt_lat:        float
+    R_hub:           np.ndarray
+    v_hub_world:     np.ndarray
+    wind_world:      np.ndarray
+    t:               float
+    rho_kg_m3:       float = field(default=1.225)
+    motor_torque_Nm: float = field(default=0.0)
+
+
+class AeroBase(ABC):
+    """Abstract interface for aero models."""
+
+    def initial_rotor_state(self) -> RotorState:
+        """Return the zero rotor state for this model.
+
+        Override in subclasses that use dynamic inflow (e.g. return
+        PittPetersRotorState() for a Pitt-Peters model).  The integrator
+        calls this once at initialisation to allocate the right state type.
+        """
+        return QuasiStaticRotorState()
+
+    @abstractmethod
+    def compute_forces(
+        self,
+        inputs: RotorInputs,
+        state:  RotorState,
+    ) -> "tuple[AeroResult, RotorState]":
+        """Compute aerodynamic forces and rotor state derivatives.
+
+        Parameters
+        ----------
+        inputs  External driving conditions for this timestep.
+        state   Current rotor state (inflow + omega + spin_angle).
+
+        Returns
+        -------
+        result      Forces and moments.
+        derivative  dstate/dt as a RotorState — the caller integrates.
+        """
+        ...
+
+    def inflow_taus(
+        self,
+        inputs: RotorInputs,
+        state:  RotorState,
+    ) -> np.ndarray:
+        """Time constants per state component for semi-implicit integration.
+
+        Returns an array of the same length as ``state.to_array()``.  Each
+        element is the time constant τ of that state's first-order lag
+        (used by the envelope integrator's semi-implicit damping
+        ``damp = 1/(1 + dt/τ)``).  Use ``np.inf`` for states that should
+        be integrated as plain explicit Euler (mechanical ω, ψ, and any
+        quasi-static states with no dynamics).
+
+        Default implementation: all-infinity (plain explicit Euler for
+        every state).  Models with stiff dynamic inflow override this so
+        the envelope can damp the explicit step.
+        """
+        return np.full(state.to_array().shape, np.inf)
+
+
+
+from . import rotor_definition  # noqa: F401, E402
+from .bem import (  # noqa: F401, E402
+    BEMModel,
+    prandtl_hub_loss,
+    prandtl_tip_loss,
+    solve_bem_element,
+)
+from .pitt_peters import PittPetersModel, vrs_lambda1  # noqa: F401, E402
+from .oye import OyeBEMModel  # noqa: F401, E402
+from .rotor_state import OyeRotorState  # noqa: F401, E402
+from .trim import TrimResult, relax_inflow, solve_trim_cyclic  # noqa: F401, E402
+from .rotor_definition import (  # noqa: F401, E402
+    AirfoilProperties,
+    AutorotationProperties,
+    BladeGeometry,
+    ControlProperties,
+    InertiaProperties,
+    KamanFlap,
+    RotorDefinition,
+    ValidationIssue,
+)
+
+__all__ = [
+    "AeroResult",
+    "AeroBase",
+    "BEMModel",
+    "PittPetersModel",
+    "OyeBEMModel",
+    "vrs_lambda1",
+    "RotorInputs",
+    "RotorState",
+    "PittPetersRotorState",
+    "OyeRotorState",
+    "QuasiStaticRotorState",
+    "AirfoilPolar",
+    "LinearPolar",
+    "create_aero",
+    "rotor_definition",
+    "AirfoilProperties",
+    "AutorotationProperties",
+    "BladeGeometry",
+    "ControlProperties",
+    "InertiaProperties",
+    "RotorDefinition",
+    "KamanFlap",
+    "ValidationIssue",
+    "TrimResult",
+    "solve_trim_cyclic",
+    "relax_inflow",
+]
+
+
+def create_aero(defn: "RotorDefinition", model: str = "pitt_peters_jit") -> AeroBase:
+    """Factory for the aero models in this package.
+
+    model
+      "bem"               BEMModel (Level 1, quasi-static inflow)
+      "pitt_peters"       PittPetersModel (Level 2, Pitt-Peters L-matrix, numpy)
+      "pitt_peters_jit"   PittPetersModelJIT (Level 2, JIT-compiled — default)
+      "oye"               OyeBEMModel (Level 2, Øye 2-stage annular inflow,
+                          JIT-compiled).  Stable alternative to Pitt-Peters
+                          at high advance ratios / descent + edgewise wind.
+    """
+    if model == "bem":
+        from .bem import BEMModel
+        return BEMModel(defn=defn)
+    if model in ("pitt_peters", "pitt_peters_numpy"):
+        from .pitt_peters import PittPetersModel
+        return PittPetersModel(defn=defn)
+    if model in ("pitt_peters_jit", "jit"):
+        from .pitt_peters_jit import PittPetersModelJIT
+        return PittPetersModelJIT(defn=defn)
+    if model in ("oye", "oye_bem"):
+        from .oye import OyeBEMModel
+        return OyeBEMModel(defn=defn)
+    raise ValueError(
+        f"Unknown aero model {model!r}. "
+        f"Choose 'bem', 'pitt_peters', 'pitt_peters_jit', or 'oye'."
+    )

dynbem/_bem_common.py

@@ -0,0 +1,143 @@
+"""Shared infrastructure for the Level-2 dynamic-inflow BEM models.
+
+Holds the pieces that ``PittPetersModel(JIT)`` and ``OyeBEMModel`` would
+otherwise duplicate or cross-import:
+
+  * ``vrs_lambda1``  — Leishman VRS empirical polynomial
+  * ``_interp_polar`` — JIT polar (cl, cd) lookup
+  * ``build_polar_arrays`` — one-time sampling of any AirfoilPolar onto
+    contiguous numba arrays
+  * ``radial_grid`` — one-time radial geometry caching
+
+Hot-path kinematics and result-assembly are deliberately *not* here —
+they're a few cheap numpy ops and live inline in each model's
+``compute_forces`` to avoid the Python function-call overhead.
+
+Lets the two models stay as peers (Øye no longer imports from
+Pitt-Peters) and the ψ-loop kernels stay model-specific (each has its
+own ``lam_local(r, ψ)`` formula and can't share a numba-compiled body
+cleanly — closures don't compose under ``@njit``).
+"""
+from __future__ import annotations
+
+import math
+from typing import TYPE_CHECKING
+
+import numpy as np
+from numba import njit
+
+from .polar import AirfoilPolar, TabulatedPolar
+
+if TYPE_CHECKING:
+    from .rotor_definition import BladeGeometry
+
+
+# ---------------------------------------------------------------------------
+# VRS empirical polynomial (Leishman 2000, §12.7)
+# ---------------------------------------------------------------------------
+# λ_1/V_h = 1 + C[0]·λ₂ + C[1]·λ₂² + C[2]·λ₂³ + C[3]·λ₂⁴
+# where λ₂ = V_descent / V_h > 0.  Valid for 0 ≤ λ₂ ≤ 2.
+# Fit to Castles-Gray (NACA TN-2474) and Coleman (1945) measured data.
+_VRS_C = (1.125, -1.372, 1.718, -0.655)
+
+
+def vrs_lambda1(lambda2: float) -> float:
+    """Normalised induced velocity λ₁ = v_i/V_h from Leishman VRS polynomial.
+
+    lambda2  V_descent / V_h, must be in [0, 2].
+    Returns  v_i / V_h  (= 1.0 at λ₂=0 hover; ≈1.0 at λ₂=2 WBS boundary).
+    """
+    k = lambda2
+    return 1.0 + _VRS_C[0]*k + _VRS_C[1]*k**2 + _VRS_C[2]*k**3 + _VRS_C[3]*k**4
+
+
+# ---------------------------------------------------------------------------
+# JIT polar interpolator (cl, cd at angle α)
+# ---------------------------------------------------------------------------
+
+@njit(cache=True, fastmath=True)
+def _interp_polar(alpha, alpha_tab, cl_tab, cd_tab):
+    """Linear-interp (cl, cd) at angle alpha (rad).  Binary-search lookup;
+    clamps to endpoints outside the tabulated range.  Matches np.interp.
+    """
+    n = alpha_tab.shape[0]
+    if alpha <= alpha_tab[0]:
+        return cl_tab[0], cd_tab[0]
+    if alpha >= alpha_tab[n - 1]:
+        return cl_tab[n - 1], cd_tab[n - 1]
+    lo = 0
+    hi = n - 1
+    while hi - lo > 1:
+        mid = (lo + hi) >> 1
+        if alpha_tab[mid] <= alpha:
+            lo = mid
+        else:
+            hi = mid
+    a_lo = alpha_tab[lo]
+    a_hi = alpha_tab[hi]
+    t = (alpha - a_lo) / (a_hi - a_lo)
+    return (
+        cl_tab[lo] + t * (cl_tab[hi] - cl_tab[lo]),
+        cd_tab[lo] + t * (cd_tab[hi] - cd_tab[lo]),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Polar tabulation for the JIT kernels
+# ---------------------------------------------------------------------------
+
+def build_polar_arrays(polar: AirfoilPolar
+                       ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Sample any AirfoilPolar onto contiguous numba arrays for _interp_polar.
+
+    TabulatedPolar passes through its existing arrays; analytical polars
+    (LinearPolar etc.) are sampled to 4001 points over [−π/2, π/2].
+    """
+    if isinstance(polar, TabulatedPolar):
+        return (
+            np.ascontiguousarray(polar._alpha),
+            np.ascontiguousarray(polar._cl),
+            np.ascontiguousarray(polar._cd),
+        )
+    n = 4001
+    a  = np.linspace(-math.pi / 2, math.pi / 2, n)
+    cl = np.empty(n)
+    cd = np.empty(n)
+    for i in range(n):
+        cl_i, cd_i = polar.cl_cd(float(a[i]))
+        cl[i] = cl_i
+        cd[i] = cd_i
+    return (
+        np.ascontiguousarray(a),
+        np.ascontiguousarray(cl),
+        np.ascontiguousarray(cd),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Radial grid caching
+# ---------------------------------------------------------------------------
+
+def radial_grid(blade: "BladeGeometry"
+                ) -> tuple[float, np.ndarray, np.ndarray, float, float]:
+    """Cache the fixed radial geometry for a JIT BEM kernel.
+
+    Returns
+    -------
+    dr          width of each radial element (m)
+    r_mid       (n,) midpoint radius per element (m), contiguous
+    x_mid       (n,) midpoint r/R, contiguous
+    x_hub       root-cutout/R (dimensionless)
+    twist_rad   uniform twist (rad).  Per-section twist not yet supported.
+    """
+    R  = blade.radius_m
+    n  = blade.n_elements
+    r0 = blade.root_cutout_m
+    dr = (R - r0) / n
+    r_mid = np.ascontiguousarray(
+        np.linspace(r0 + 0.5 * dr, R - 0.5 * dr, n)
+    )
+    x_mid     = np.ascontiguousarray(r_mid / R)
+    x_hub     = float(r0 / R) if R > 0.0 else 0.0
+    twist_rad = math.radians(blade.twist_deg)
+    return dr, r_mid, x_mid, x_hub, twist_rad