linstabpy 1.0.0__py3-none-any.whl

linstabpy/__init__.py

@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: GPL-3.0-only
+"""Stability and resolvent analysis of compressible viscous flows.
+
+The linearized Navier-Stokes operator is assembled on a two-dimensional
+structured mesh. Summation-by-parts finite differences cover orders 2 to 8.
+Temporal and adjoint eigenvalue problems, structural sensitivity, and
+resolvent gain use PETSc, SLEPc, and a sparse direct factor (MUMPS by default).
+
+A plain ``import linstabpy`` does not start PETSc or MPI. Public names load
+on first use. The loader caches each name on this module.
+
+Public names
+------------
+build_lnse_system, build_lnse_operator
+    Sparse LNSE operator. State ``q = [rho, u, v, w, T]``.
+compute_chu_norm
+    Chu compressible energy inner product.
+temporal_eigenvalues, adjoint_eigenvalues
+    SLEPc temporal eigenvalue problems.
+wavemaker
+    Structural sensitivity from direct and adjoint modes.
+resolvent_analysis, resolvent_map
+    Leading gain at one frequency, or a frequency walk.
+BaseFlow
+    Mean flow, sponge damping, and viscosity.
+"""
+
+from __future__ import annotations
+
+import importlib
+import re
+from importlib import metadata
+from pathlib import Path
+
+_PYPROJECT = Path(__file__).resolve().parents[2] / "pyproject.toml"
+_VERSION_RE = re.compile(r'^version\s*=\s*"([^"]+)"\s*$', re.MULTILINE)
+
+
+def _package_version() -> str:
+    """Return the version from pyproject.toml, then installed metadata."""
+    if _PYPROJECT.is_file():
+        match = _VERSION_RE.search(_PYPROJECT.read_text(encoding="utf-8"))
+        if match is not None:
+            return match.group(1)
+    try:
+        return metadata.version("linstabpy")
+    except metadata.PackageNotFoundError:
+        return "0.0.0+dev"
+
+
+__version__ = _package_version()
+
+# Each public name maps to (module, attribute). ``temporal_eigenvalues`` is
+# the public alias of ``stability._eigenvalues.eigenvalues``.
+_LAZY_EXPORTS: dict[str, tuple[str, str]] = {
+    "build_lnse_system": ("linstabpy.operators.assembly", "build_lnse_system"),
+    "build_lnse_operator": ("linstabpy.operators.assembly", "build_lnse_operator"),
+    "compute_chu_norm": ("linstabpy.operators.energy_norm", "compute_chu_norm"),
+    "temporal_eigenvalues": ("linstabpy.stability._eigenvalues", "eigenvalues"),
+    "adjoint_eigenvalues": ("linstabpy.stability._eigenvalues", "adjoint_eigenvalues"),
+    "wavemaker": ("linstabpy.stability.sensitivity", "wavemaker"),
+    "resolvent_analysis": ("linstabpy.resolvent.analysis", "resolvent_analysis"),
+    "resolvent_map": ("linstabpy.solvers.router.resolvent_map", "resolvent_map"),
+    "BaseFlow": ("linstabpy.baseflow", "BaseFlow"),
+}
+
+__all__ = sorted(_LAZY_EXPORTS)
+
+
+def __getattr__(name: str) -> object:
+    """Load a public name on first use and cache it on this module."""
+    target = _LAZY_EXPORTS.get(name)
+    if target is None:
+        raise AttributeError(f"module 'linstabpy' has no attribute {name!r}")
+    module_name, attr_name = target
+    attr = getattr(importlib.import_module(module_name), attr_name)
+    globals()[name] = attr
+    return attr
+
+
+def __dir__() -> list[str]:
+    """List bound names and public names that load on first use."""
+    return sorted(set(globals()) | set(_LAZY_EXPORTS))

linstabpy/baseflow/__init__.py

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: GPL-3.0-only
+"""Base-flow object, viscosity, and packed-field loader."""
+
+from .baseflow import BaseFlow
+from .grid_fields import load_case_fields, load_grid_fields, read_grid_fields
+from .preprocess import apply_preprocess
+from .sponge import generate_sponge, load_sponge_aux, sponge_from_config
+from .viscosity import sutherland_air

linstabpy/baseflow/baseflow.py

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: GPL-3.0-only
+"""Base flow data container for linear stability analysis."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass
+class BaseFlow:
+    """Base flow fields and parameters for linear stability analysis.
+
+    All flow field arrays have shape ``(ny, nx)`` matching the computational
+    mesh.  :func:`~linstabpy.baseflow.viscosity.sutherland_air` later fills
+    viscosity fields and derived coefficients.
+
+    Parameters
+    ----------
+    Re : float
+        Reynolds number.
+    Ma : float
+        Mach number.
+    Pr : float
+        Prandtl number.
+    kappa : float
+        Heat capacity ratio (gamma).
+    T_0 : float
+        Reference temperature [K].
+    RHO, U, V, W, T : np.ndarray
+        Density, streamwise velocity, wall-normal velocity, spanwise
+        velocity, and temperature fields.
+    """
+
+    # Physical parameters
+    Re: float
+    Ma: float
+    Pr: float
+    kappa: float
+    T_0: float
+
+    # Flow fields -- shape (ny, nx) matching mesh
+    RHO: np.ndarray
+    U: np.ndarray
+    V: np.ndarray
+    W: np.ndarray
+    T: np.ndarray
+
+    # Viscosity fields (populated by sutherland_air)
+    MU: np.ndarray | None = None
+    dmudT: np.ndarray | None = None
+    d2mudT2: np.ndarray | None = None
+
+    # Derived coefficients (populated by sutherland_air)
+    cv: float | None = None
+    c1: float | None = None
+    c2: float | None = None

linstabpy/baseflow/grid_fields.py

@@ -0,0 +1,146 @@
+# SPDX-License-Identifier: GPL-3.0-only
+"""Load a rectilinear primitive field set from a npy directory or one npz."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from .baseflow import BaseFlow
+from .preprocess import apply_preprocess
+
+FIELD_NAMES = ("x", "y", "rho", "u", "v", "w", "T", "sponge")
+
+
+def _as_field(name: str, arr: np.ndarray, source: Path) -> np.ndarray:
+    out = np.asarray(arr, dtype=float)
+    if out.ndim != 2:
+        raise ValueError(f"{source} field {name} must be 2-D, got shape {out.shape}")
+    return out
+
+
+def read_grid_fields(source: str | Path) -> dict[str, np.ndarray]:
+    """Read x, y, rho, u, v, w, T, sponge from an npz file or a npy directory."""
+    root = Path(source)
+    if root.is_file():
+        if root.suffix != ".npz":
+            raise ValueError(f"grid field file must be .npz, got {root}")
+        packed = np.load(root)
+        missing = [name for name in FIELD_NAMES if name not in packed.files]
+        if missing:
+            raise FileNotFoundError(f"{root} is missing fields: {missing}")
+        return {name: _as_field(name, packed[name], root) for name in FIELD_NAMES}
+
+    if not root.is_dir():
+        raise FileNotFoundError(f"grid field source not found: {root}")
+
+    fields: dict[str, np.ndarray] = {}
+    for name in FIELD_NAMES:
+        path = root / f"{name}.npy"
+        if not path.exists():
+            raise FileNotFoundError(f"Missing field file: {path}")
+        fields[name] = _as_field(name, np.load(path), path)
+    return fields
+
+
+def load_case_fields(
+    source: str | Path,
+    *,
+    Re: float,
+    Ma: float,
+    Pr: float,
+    kappa: float,
+    T_0: float,
+    stride_ksi: int = 1,
+    stride_eta: int = 1,
+    transpose_input: bool = False,
+    zero_spanwise: bool = False,
+    refuse_asymmetric_stride: bool = False,
+    preprocess: dict[str, Any] | None = None,
+) -> tuple[np.ndarray, np.ndarray, BaseFlow, np.ndarray, dict[str, Any]]:
+    """Build coordinates, a BaseFlow, and the sponge from a packed field.
+
+    ``source`` is a directory of eight ``.npy`` files or one ``.npz`` with
+    the same keys. After an optional transpose the arrays are ``(ny, nx)``:
+    ``stride_eta`` walks the first index and ``stride_ksi`` walks the second.
+    """
+    fields = read_grid_fields(source)
+    if transpose_input:
+        fields = {name: arr.T for name, arr in fields.items()}
+
+    sx = int(stride_ksi)
+    sy = int(stride_eta)
+    if sx < 1 or sy < 1:
+        raise ValueError("stride_ksi and stride_eta must be >= 1")
+    if refuse_asymmetric_stride and sx != sy:
+        raise ValueError(
+            f"Asymmetric strides are not supported on this mesh (stride_ksi={sx}, stride_eta={sy})."
+        )
+    if sx > 1 or sy > 1:
+        fields = {name: arr[::sy, ::sx] for name, arr in fields.items()}
+
+    shape = fields["x"].shape
+    for name, arr in fields.items():
+        if arr.shape != shape:
+            raise ValueError(f"Field '{name}' shape {arr.shape} does not match x shape {shape}")
+
+    X = fields["x"]
+    Y = fields["y"]
+    rho = fields["rho"]
+    u = fields["u"]
+    v = fields["v"]
+    w = fields["w"]
+    T = fields["T"]
+    sponge = fields["sponge"]
+
+    X, Y, rho, u, v, w, T, sponge, info = apply_preprocess(
+        X, Y, rho, u, v, w, T, sponge, preprocess
+    )
+
+    if zero_spanwise:
+        w = np.zeros_like(u)
+
+    baseflow = BaseFlow(
+        Re=float(Re),
+        Ma=float(Ma),
+        Pr=float(Pr),
+        kappa=float(kappa),
+        T_0=float(T_0),
+        RHO=rho,
+        U=u,
+        V=v,
+        W=w,
+        T=T,
+    )
+    return X, Y, baseflow, sponge, info
+
+
+def load_grid_fields(
+    source: str | Path,
+    *,
+    Re: float,
+    Ma: float,
+    Pr: float,
+    kappa: float,
+    T_0: float,
+    stride_ksi: int = 1,
+    stride_eta: int = 1,
+    transpose_input: bool = False,
+    zero_spanwise: bool = False,
+) -> tuple[np.ndarray, np.ndarray, BaseFlow, np.ndarray]:
+    """Load a packed field and drop the preprocess report."""
+    X, Y, baseflow, sponge, _info = load_case_fields(
+        source,
+        Re=Re,
+        Ma=Ma,
+        Pr=Pr,
+        kappa=kappa,
+        T_0=T_0,
+        stride_ksi=stride_ksi,
+        stride_eta=stride_eta,
+        transpose_input=transpose_input,
+        zero_spanwise=zero_spanwise,
+    )
+    return X, Y, baseflow, sponge

linstabpy/baseflow/preprocess.py

@@ -0,0 +1,250 @@
+# SPDX-License-Identifier: GPL-3.0-only
+"""Optional field filter, boundary sponge, and shock cleanup."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from .shock_cleanup import apply_optional_shock_cleanup
+
+
+def _binomial5_filter(arr: np.ndarray, axis: int) -> np.ndarray:
+    """Apply a 5-point binomial filter along one axis."""
+    if arr.ndim != 2:
+        raise ValueError(f"Expected 2-D array for filtering, got shape {arr.shape}")
+    if axis not in (0, 1):
+        raise ValueError(f"axis must be 0 or 1, got {axis}")
+
+    pad = [(0, 0), (0, 0)]
+    pad[axis] = (2, 2)
+    padded = np.pad(arr, pad, mode="edge")
+    if axis == 0:
+        return (
+            padded[:-4, :]
+            + 4.0 * padded[1:-3, :]
+            + 6.0 * padded[2:-2, :]
+            + 4.0 * padded[3:-1, :]
+            + padded[4:, :]
+        ) / 16.0
+    return (
+        padded[:, :-4]
+        + 4.0 * padded[:, 1:-3]
+        + 6.0 * padded[:, 2:-2]
+        + 4.0 * padded[:, 3:-1]
+        + padded[:, 4:]
+    ) / 16.0
+
+
+def _as_four_numbers(values: Any, *, cast, name: str) -> tuple[Any, Any, Any, Any]:
+    if values is None:
+        values = [0, 0, 0, 0]
+    if not isinstance(values, (list, tuple)) or len(values) != 4:
+        raise ValueError(f"{name} must be a list of four values [top, right, bottom, left]")
+    return tuple(cast(v) for v in values)
+
+
+def _generate_boundary_sponge(
+    shape: tuple[int, int],
+    *,
+    points: tuple[int, int, int, int],
+    amplitudes: tuple[float, float, float, float],
+) -> np.ndarray:
+    """Build a boundary sponge with quadratic ramps [top, right, bottom, left]."""
+    ny, nx = shape
+    sponge = np.zeros(shape, dtype=float)
+
+    def _ramp(count: int) -> np.ndarray:
+        if count <= 0:
+            return np.empty((0,), dtype=float)
+        return (np.arange(1, count + 1, dtype=float) / float(count)) ** 2
+
+    top_n, right_n, bottom_n, left_n = points
+    top_amp, right_amp, bottom_amp, left_amp = amplitudes
+
+    if top_n > 0:
+        ramp = top_amp * _ramp(top_n)
+        sponge[-top_n:, :] += ramp[:, None]
+    if bottom_n > 0:
+        ramp = bottom_amp * _ramp(bottom_n)[::-1]
+        sponge[:bottom_n, :] += ramp[:, None]
+    if right_n > 0:
+        ramp = right_amp * _ramp(right_n)
+        sponge[:, -right_n:] += ramp[None, :]
+    if left_n > 0:
+        ramp = left_amp * _ramp(left_n)[::-1]
+        sponge[:, :left_n:] += ramp[None, :]
+
+    return sponge
+
+
+def apply_preprocess(
+    X: np.ndarray,
+    Y: np.ndarray,
+    rho: np.ndarray,
+    u: np.ndarray,
+    v: np.ndarray,
+    w: np.ndarray,
+    T: np.ndarray,
+    sponge: np.ndarray,
+    preprocess_cfg: dict[str, Any] | None,
+) -> tuple[
+    np.ndarray,
+    np.ndarray,
+    np.ndarray,
+    np.ndarray,
+    np.ndarray,
+    np.ndarray,
+    np.ndarray,
+    np.ndarray,
+    dict[str, Any],
+]:
+    """Apply optional filter, boundary sponge, and shock cleanup."""
+    info: dict[str, Any] = {
+        "enabled": False,
+        "applied": [],
+        "filter": {"enabled": False, "passes": 0, "fields": []},
+        "sponge": {"scale": 1.0, "boundary": {"enabled": False}},
+    }
+
+    if preprocess_cfg is None:
+        info["summary"] = "disabled"
+        return X, Y, rho, u, v, w, T, sponge, info
+    if not isinstance(preprocess_cfg, dict):
+        raise TypeError("preprocess must be a mapping when provided")
+
+    enabled = bool(preprocess_cfg.get("enabled", False))
+    info["enabled"] = enabled
+    if not enabled:
+        info["summary"] = "disabled"
+        return X, Y, rho, u, v, w, T, sponge, info
+
+    shock_cfg = preprocess_cfg.get("shock", {})
+    if isinstance(shock_cfg, dict) and bool(shock_cfg.get("enabled", False)):
+        rho, u, v, w, T, sponge, shock_info = apply_optional_shock_cleanup(
+            X, Y, rho, u, v, w, T, sponge, shock_cfg
+        )
+        info["applied"].append("shock_cleanup")
+        info["shock"] = shock_info
+
+    sponge_cfg = preprocess_cfg.get("sponge", {})
+    if sponge_cfg is None:
+        sponge_cfg = {}
+    if not isinstance(sponge_cfg, dict):
+        raise TypeError("preprocess.sponge must be a mapping when provided")
+
+    sponge_scale = float(sponge_cfg.get("scale", 1.0))
+    info["sponge"]["scale"] = sponge_scale
+    if sponge_scale != 1.0:
+        sponge = sponge * sponge_scale
+        info["applied"].append(f"sponge_scale={sponge_scale:.6g}")
+
+    boundary_cfg = sponge_cfg.get("boundary", {})
+    if boundary_cfg is None:
+        boundary_cfg = {}
+    if not isinstance(boundary_cfg, dict):
+        raise TypeError("preprocess.sponge.boundary must be a mapping when provided")
+
+    boundary_enabled = bool(boundary_cfg.get("enabled", False))
+    info["sponge"]["boundary"] = {"enabled": boundary_enabled}
+    if boundary_enabled:
+        points = _as_four_numbers(
+            boundary_cfg.get("points"), cast=int, name="boundary sponge points"
+        )
+        amplitudes = _as_four_numbers(
+            boundary_cfg.get("amplitudes"), cast=float, name="boundary sponge amplitudes"
+        )
+        mode = str(boundary_cfg.get("mode", "add")).strip().lower()
+        generated = _generate_boundary_sponge(sponge.shape, points=points, amplitudes=amplitudes)
+        if mode == "replace":
+            sponge = generated
+        elif mode == "max":
+            sponge = np.maximum(sponge, generated)
+        elif mode == "add":
+            sponge = sponge + generated
+        else:
+            raise ValueError("boundary sponge mode must be one of: add, max, replace")
+        info["sponge"]["boundary"] = {
+            "enabled": True,
+            "mode": mode,
+            "points": list(points),
+            "amplitudes": list(amplitudes),
+            "generated_max": float(np.max(generated)) if generated.size else 0.0,
+        }
+        info["applied"].append(
+            "boundary_sponge="
+            f"mode:{mode},points:{list(points)},amplitudes:{[float(a) for a in amplitudes]}"
+        )
+
+    filter_cfg = preprocess_cfg.get("filter", {})
+    if filter_cfg is None:
+        filter_cfg = {}
+    if not isinstance(filter_cfg, dict):
+        raise TypeError("preprocess.filter must be a mapping when provided")
+
+    filter_enabled = bool(filter_cfg.get("enabled", False))
+    passes = int(filter_cfg.get("passes", 0))
+    fields = [str(name) for name in filter_cfg.get("fields", ["rho", "u", "v", "T"])]
+    directions_raw = filter_cfg.get("directions", ["x", "y"])
+    if not isinstance(directions_raw, (list, tuple)) or not directions_raw:
+        raise ValueError("preprocess.filter.directions must be a non-empty list")
+    direction_map = {"x": 1, "y": 0}
+    directions: list[str] = []
+    axes: list[int] = []
+    for item in directions_raw:
+        name = str(item).strip().lower()
+        if name not in direction_map:
+            raise ValueError("filter directions must contain only 'x' and/or 'y'")
+        if name not in directions:
+            directions.append(name)
+            axes.append(direction_map[name])
+
+    eta_min = int(filter_cfg.get("eta_min_index", 0))
+    eta_max_raw = filter_cfg.get("eta_max_index")
+    eta_max = rho.shape[0] if eta_max_raw is None else int(eta_max_raw)
+    eta_min = max(0, min(rho.shape[0], eta_min))
+    eta_max = max(eta_min, min(rho.shape[0], eta_max))
+
+    info["filter"] = {
+        "enabled": filter_enabled,
+        "passes": passes,
+        "fields": fields,
+        "directions": directions,
+        "eta_min_index": eta_min,
+        "eta_max_index": None if eta_max_raw is None else eta_max,
+    }
+
+    if filter_enabled and passes > 0 and eta_min < eta_max:
+        # Filter copies: the caller's arrays stay untouched, as in shock_cleanup.
+        field_map = {
+            name: np.array(arr, copy=True)
+            for name, arr in {"rho": rho, "u": u, "v": v, "w": w, "T": T}.items()
+        }
+        invalid = [name for name in fields if name not in field_map]
+        if invalid:
+            raise ValueError(f"Unsupported filter field names: {invalid}")
+
+        change_norms: dict[str, float] = {}
+        region = (slice(eta_min, eta_max), slice(None))
+        for name in fields:
+            original = np.array(field_map[name], copy=True)
+            filtered_region = np.array(field_map[name][region], copy=True)
+            for _ in range(passes):
+                for axis in axes:
+                    filtered_region = _binomial5_filter(filtered_region, axis=axis)
+            field_map[name][region] = filtered_region
+            denom = float(np.linalg.norm(original))
+            delta = float(np.linalg.norm(field_map[name] - original))
+            change_norms[name] = 0.0 if denom == 0.0 else delta / denom
+
+        rho, u, v, w, T = (field_map[name] for name in ("rho", "u", "v", "w", "T"))
+        info["filter"]["relative_l2_change"] = change_norms
+        info["applied"].append(
+            "explicit_filter="
+            f"passes:{passes},fields:{fields},directions:{directions},eta:[{eta_min},{eta_max})"
+        )
+
+    info["sponge"]["max"] = float(np.max(sponge)) if sponge.size else 0.0
+    info["summary"] = "; ".join(info["applied"]) if info["applied"] else "enabled(no-op)"
+    return X, Y, rho, u, v, w, T, sponge, info