pyfuga 0.1.0__py3-none-any.whl

pyfuga/__init__.py

@@ -0,0 +1,20 @@
+import functools
+import inspect
+from importlib.metadata import PackageNotFoundError, version
+
+from . import _fuga
+
+try:
+    __version__ = version("pyfuga")
+except PackageNotFoundError:
+    __version__ = "0+unknown"
+
+__all__ = ["get_luts", "__version__"]
+
+
+@functools.wraps(_fuga.get_luts)
+def get_luts(*args, **kwargs):
+    return _fuga.get_luts(*args, **kwargs)
+
+
+get_luts.__signature__ = inspect.signature(_fuga.get_luts)

pyfuga/_fuga.py

@@ -0,0 +1,230 @@
+"""_fuga.py
+==========
+Main API entry point for PyFuga — generate wake look-up tables.
+
+This module orchestrates the full three-stage PyFuga pipeline:
+
+1. **Preliminary LUTs (preLUTs)** — via :mod:`pyfuga.preluts_generator`
+   Integrates atmospheric boundary layer equations between vertical stations.
+
+2. **Fourier LUTs** — via :mod:`pyfuga.flut`
+   Solves for spectral wake response to all forcing directions.
+
+3. **Physical-space LUTs** — via :mod:`pyfuga.trafalgar`
+   Inverse Fourier transform to obtain wake fields in physical x-y-z space.
+
+The entry point is :func:`get_luts`, which orchestrates all three stages,
+handling file caching and data I/O.
+"""
+
+import os
+from pathlib import Path
+
+import numpy as np
+import xarray as xr
+
+from pyfuga import utils
+from pyfuga.constants import UVW_LT
+from pyfuga.flut import FourierLUTGenerator
+from pyfuga.preluts import PreLUTs
+from pyfuga.trafalgar import Trafalgar
+from pyfuga.utils import ComplexXRDataset, get_beta_lst, get_kz0_lst
+
+
+def get_luts(
+    folder,
+    zeta0,
+    nkz0,
+    nbeta,
+    diameter,
+    zhub,
+    z0,
+    zi,
+    zlow,
+    zhigh,
+    lut_vars=UVW_LT,
+    nx=2048,
+    ny=512,
+    dx=None,
+    dy=None,
+    jit=True,
+    n_cpu=1,
+):  # pragma: no cover
+    """Generate physical-space wake look-up tables via the full PyFuga pipeline.
+
+    This function orchestrates the three-stage PyFuga pipeline:
+        1. Preliminary LUTs (preLUTs) via pyfuga.preluts_generator
+        2. Fourier LUTs via pyfuga.flut
+        3. Physical-space LUTs via pyfuga.trafalgar
+
+    Caches intermediate results (preLUTs and Fourier LUTs) as NetCDF files in
+    the specified folder, skipping recomputation if files exist.
+
+    Parameters
+    ----------
+    folder : str or Path
+        Output folder for all generated files (preLUTs, Fourier LUTs, LUTs).
+    zeta0 : float
+        Monin-Obukhov stability parameter (z0/L). Positive=stable, negative=unstable,
+        zero=neutral.
+    nkz0 : int
+        Spectral density: number of wavenumbers per log decade.
+        Total count = 9*nkz0 - (nkz0-1); typically 8--16.
+    nbeta : int
+        Angular resolution for azimuthal averaging. Total angle count is nbeta + 1.
+    diameter : float
+        Wind turbine rotor diameter (m).
+    zhub : float
+        Wind turbine hub height (m).
+    z0 : float
+        Aerodynamic roughness length (m); defines vertical grid via s = log(z/z0).
+    zi : float
+        Atmospheric inversion height (m); upper domain boundary.
+    zlow : float
+        Lowest output height (m). If zlow == zhigh == zhub, only hub-height solution.
+    zhigh : float
+        Highest output height (m). If zlow == zhigh == zhub, only hub-height solution.
+    lut_vars : sequence of str, optional
+        Variable names to compute. Default is all 8: 'UL', 'UT', 'VL', 'VT', 'WL',
+        'WT', 'PL', 'PT' (L=longitudinal, T=transverse forcing).
+    nx : int, optional
+        Streamwise grid points, default 2048. Turbine at x = nx/4 * dx.
+    ny : int, optional
+        Cross-stream half-grid size, default 512.
+    dx : float or None, optional
+        Streamwise grid spacing (m). If None (default), set to diameter / 4.
+    dy : float or None, optional
+        Cross-stream grid spacing (m). If None (default), set to diameter / 16.
+    jit : bool, optional
+        Enable JIT compilation (Numba). Default is True.
+    n_cpu : int or None, optional
+        CPU cores for parallel computation. None uses all; 1 disables parallelisation.
+
+    Returns
+    -------
+    xarray.Dataset
+        Physical-space wake fields with dimensions (z, x, y).
+
+    See Also
+    --------
+    pyfuga.preluts_generator.PreLUTGenerator.make_prelut : First pipeline stage.
+    pyfuga.flut.FourierLUTGenerator.make_lut : Second pipeline stage.
+    pyfuga.trafalgar.Trafalgar.make_luts : Third pipeline stage.
+    """
+    utils.compile(jit)
+    folder = Path(folder)
+    os.makedirs(folder, exist_ok=True)
+    dx = dx or diameter / 4
+    dy = dy or diameter / 16
+
+    preluts_id = f"Zeta0={zeta0:3.2e}_{nkz0}_{nbeta}"
+
+    L_vars = [v[0] for v in lut_vars if v[1] == "L"]
+    T_vars = [v[0] for v in lut_vars if v[1] == "T"]
+    lut_vars_id = ""
+    if L_vars:
+        lut_vars_id += f"_{''.join(L_vars)}L"
+    if T_vars:
+        lut_vars_id += f"_{''.join(T_vars)}T"
+
+    ds = 0.05
+    if zlow == zhigh == zhub:
+        low_level_out = high_level_out = 9999
+        z_id = f"z{zhub:.1f}"
+    else:
+        low_level_out = int(np.floor(np.log(zlow / z0) / ds))
+        high_level_out = int(np.ceil(np.log(zhigh / z0) / ds))
+        zlow = z0 * np.exp(low_level_out * ds)
+        zhigh = z0 * np.exp(high_level_out * ds)
+        z_id = f"z{zlow:.1f}-{zhigh:.1f}"
+
+    fluts_id = preluts_id + f"_D{diameter}_zhub{zhub}_zi{zi}_z0={z0:.8f}_{z_id}{lut_vars_id}"
+
+    luts_id = fluts_id + f"_nx{nx}_ny{ny}_dx{dx}_dy{dy}"
+
+    luts_path = folder / f"LUTs_{luts_id}.nc"
+    if not luts_path.exists():
+        # LUTs are missing (run Trafalgar)
+        fluts_path = folder / f"fLUTs_{fluts_id}.nc"
+        if not fluts_path.exists():
+            # FourierLUTs are missing (run lut)
+
+            preluts_path = folder / f"preLUTs_{preluts_id}.nc"
+            if not preluts_path.exists():
+                # Preluts are missing (run prelut)
+                preluts = PreLUTs.make_preluts(
+                    zeta0=zeta0,
+                    kz0_lst=get_kz0_lst(nkz0, 1e-9, 1e-1),
+                    beta_lst=get_beta_lst(nbeta),
+                    kzmax=300,
+                    ds=ds,
+                    accgoal=0.0001,
+                    jit=jit,
+                    n_cpu=n_cpu,
+                )
+                preluts.attrs["nkz0"] = nkz0
+                preluts.attrs["nbeta"] = nbeta
+                preluts.save(preluts_path)
+            else:
+                preluts = PreLUTs.from_netcdf(preluts_path)
+
+            # preluts loaded make fourier luts
+            flut_generator = FourierLUTGenerator(preluts, zhub, diameter, zi)
+            if low_level_out == high_level_out == 9999:
+                fluts = flut_generator.make_hubheight_luts(z0, lut_vars, n_cpu=n_cpu)
+            else:
+                fluts = flut_generator.make_lut(z0, low_level_out, high_level_out, lut_vars, n_cpu=n_cpu)
+
+            fluts.save(fluts_path)
+        else:
+            fluts = ComplexXRDataset.from_netcdf(fluts_path)
+
+        # fourier luts loaded make luts
+        luts = Trafalgar(fluts, nx, ny, dx, dy).make_luts(3)
+        luts.to_netcdf(luts_path)
+    else:
+        luts = xr.load_dataset(luts_path)
+    luts.attrs["name"] = luts_path.stem
+    return luts
+
+
+def main():
+    if __name__ == "__main__":  # pragma: no cover
+        luts = get_luts(
+            folder=Path(__file__).parent.parent,
+            zeta0=0,
+            nkz0=16,
+            nbeta=32,
+            diameter=80,
+            zhub=70,
+            z0=0.00001,
+            zi=400,
+            zlow=70,
+            zhigh=70,
+            lut_vars=["UL"],
+        )
+        import matplotlib.pyplot as plt
+
+        luts.UL.sel(z=70)[502:542, :40].plot(x="x")
+        plt.axis("equal")
+        plt.figure()
+        luts = get_luts(
+            folder=Path(__file__).parent.parent,
+            zeta0=0,
+            nkz0=16,
+            nbeta=32,
+            diameter=80,
+            zhub=70,
+            z0=0.00001,
+            zi=400,
+            zlow=30,
+            zhigh=110,
+            lut_vars=["UL"],
+        )
+
+        luts.UL.sel(x=500)[:, :50].plot(x="y")
+        plt.axis("equal")
+        plt.show()
+
+
+main()

pyfuga/common.py

@@ -0,0 +1,81 @@
+r"""common.py
+===========
+Numerical helper functions for atmospheric stability relations in PyFuga.
+
+This module provides JIT-accelerated utilities used by the preLUT and Fourier
+LUT stages.
+
+Key components:
+
+- ``get_cdivkL(zeta0, kz0)``: Stability parameter :math:`c/(kL)`.
+- ``get_phi_inverse(kz, cdivkL)``: Inverse of :math:`\phi_m` for unstable flow.
+- ``get_psi(zeta0, kz, cdivkL)``: Stability correction function :math:`-\psi_m`.
+- ``get_phi(zeta0, kz, cdivkL)``: Stability function :math:`\phi_m`.
+- ``complex_norm(arr)``: Euclidean norm for complex arrays.
+- ``get_new_h2(h, acc, Yerr, Y)``: Adaptive integration step-size update.
+"""
+
+import numpy as np
+
+from pyfuga.utils import jit
+
+from .constants import CM_STABLE, CM_UNSTABLE
+
+
+@jit("double(double,double)")
+def get_cdivkL(zeta0, kz0):
+    """c/(k*L), c is a stability constant: depending on the stability (0, Cm1, Cm2)"""
+    if abs(zeta0) < 1e-10:  # Neutral
+        return 0.0
+    else:
+        if zeta0 < 0:  # Unstable
+            return zeta0 / kz0 * CM_UNSTABLE
+        else:  # Stable
+            return zeta0 / kz0 * CM_STABLE
+
+
+@jit("double(double,double)")
+def get_phi_inverse(kz, cdivkl):
+    """
+    Inverse of stability function phi_m
+    for unstable conditions
+    phi_m=(1+Cm1*z/L)**(1/4)
+    """
+    return (1.0 + cdivkl * kz) ** 0.25
+
+
+@jit("double(double,double,double)")
+def get_psi(zeta0, kz, cdivkl):
+    """Stability function -psi_m"""
+    if zeta0 < 0:
+        # Unstable: -psi_m=-ln(1/8*(1+phi_m**-2)*(1+phi_m**-1)**2)+2*atan(phi_m**-1)-pi/2
+
+        aux = get_phi_inverse(kz, cdivkl)
+        aux2 = (1.0 + aux) ** 2 * (1 + aux**2)
+        return np.log(8.0 / aux2) + 2.0 * np.arctan(cdivkl * kz / aux2)
+    else:  # Stable: -psi_m=Cm2*z/L
+        return cdivkl * kz
+
+
+@jit("double(double,double,double)")
+def get_phi(zeta0, kz, cdivkl):
+    """Stability function phi_m"""
+    if zeta0 < 0:  # Unstable: phi_m=(1+Cm1*z/L)**(-1/4)
+        return (1.0 + cdivkl * kz) ** (-0.25)
+    else:  # Stable: phi_m=1+Cm2*z/L
+        return 1.0 + cdivkl * kz
+
+
+@jit("double[:](complex128[:,:],int32)")
+def complex_norm(arr, axis=0):
+    """Compute the norm of a complex array along the first axis"""
+    return np.sqrt((np.abs(arr) ** 2).sum(0))
+
+
+@jit("double(double,double,complex128[:,:],complex128[:,:])")
+def get_new_h2(h, acc, Yerr, Y):
+    """Get new step size based on error between integration estimates"""
+    err = np.max(complex_norm(Yerr, axis=0) / complex_norm(Y, axis=0))
+    return np.maximum(np.minimum(0.9 * h * (acc / err) ** (1 / 3), 4.0e-1), 1.0e-4)
+
+    # return np.clip(0.9 * h * (acc / err)**(1 / 3), 1.0E-4, 4.0E-1)

pyfuga/constants.py

@@ -0,0 +1,32 @@
+"""constants.py
+==============
+Global constants for atmospheric stability, numerical algorithms, and data structure sizes.
+
+Key constants:
+    - **Stability (MO)**: CM_STABLE, CM_UNSTABLE for Monin-Obukhov relations
+    - **Numerics**: KAPPA (von Kármán), MAX_NODES (max preLUT nodes),
+      Y_NORM_THRESHOLD (threshold to trigger QR decomposition and substations
+      between nodes)
+    - **Data**: N_EQ (number of differential equations), UVW_LT (variable names)
+    - **Coordinate systems**: COORD_T (log profile), COORD_S (kz)
+"""
+
+# PreLUT constants
+CM_STABLE = 5.0  # MO Stability constant in phi_m (stable)
+CM_UNSTABLE = -19.0  # MO Stability constant in phi_m (unstable) Hogstrom (1988)
+N_EQ = 6  # ! Number of equations
+KAPPA = 0.4  # Von Karman constant
+KAPPA_SQUARED = 0.16  # Square of kappa
+P_SCALE = 1  # Pressure normalisation variable
+MAX_NODES = 400
+Y_NORM_THRESHOLD = 100  # Max value of Ynorm before a sublevel is made
+
+# LUT constant
+FIRST_Z_OUTPUT = 1.0  # First height level in output
+
+# Other constants
+UVW_LT = ["UL", "UT", "VL", "VT", "WL", "WT", "PL", "PT"]
+
+# Coordinate system indicators
+COORD_T = 1  # t = u0 * KAPPA
+COORD_S = 2  # s = kz

pyfuga/file_readers.py

@@ -0,0 +1,141 @@
+"""file_readers.py
+================
+Read Fortran binary output files from the original FUGA code.
+
+This module provides readers for legacy .bin output files containing
+parameters, case data, and preLUT tables saved by the Fortran FUGA implementation.
+Used for initialising preLUTs from existing FUGA runs and for compatibility
+with legacy simulation data.
+"""
+
+import os
+import struct
+from pathlib import Path
+
+import numpy as np
+import xarray as xr
+from numpy import newaxis as na
+
+
+class BinaryReader:
+    def s(self, n):
+        return self.fid.read(n).decode().strip()
+
+    def i(self):
+        return struct.unpack("i", self.fid.read(4))[0]
+
+    def d(self):
+        return struct.unpack("d", self.fid.read(8))[0]
+
+
+class Parameters(BinaryReader):
+    def __init__(self, folder):
+        i, d, s = self.i, self.d, self.s
+        with open(Path(folder) / "parameters.bin", "rb") as self.fid:
+            self.prelutname = s(127)
+            self.closure = i()
+            self.kz0min = d()
+            self.kz0max = d()
+            self.nkz0 = i()
+            self.jmin = i()
+            self.jmax = i()
+            self.nbeta = i()
+            self.mbeta = i()
+            self.dummy2 = d()
+            self.ds = d()
+            self.kzmax = d()
+            self.accgoal = d()
+            self.beta_lst = np.fromfile(self.fid, float, self.nbeta + self.mbeta + 1)
+            self.kz0_lst = np.fromfile(self.fid, float, self.jmax - self.jmin + 1)
+
+
+class CaseData(BinaryReader):
+    def __init__(self, folder):
+        i, d, s = self.i, self.d, self.s
+
+        with open(Path(folder) / "CaseData.bin", "rb") as self.fid:
+            self.case_name = s(127)
+            self.radius = d()
+            self.zhub = d()
+            self.low_level_out = i()
+            self.high_level_out = i()
+            self.z0 = d()
+            self.zi = d()
+            self.ds = d()
+            self.closure = i()
+
+
+def eof(fid):
+    fid.seek(-1, 2)  # go to the file end.
+    eof = fid.tell() + 1  # get the end of file location
+    fid.seek(0, 0)  # go back to file beginning
+    return eof
+
+
+def read_prelut_list(folder, dict=True):
+
+    folder = Path(folder)
+    with open(folder / "prelut_list.lst", "rb") as fid:
+        fid.seek(18)
+        n = 24 if fid.read(6) == b"\x00\x00\x00\x00\x00\x00" else 18
+
+        N = eof(fid) // (n + 48)
+
+        # list of filename (18 or 18+6xNull), ds, smaxx, kz0, beta, kzmax, accgoal
+        if dict:
+            return {fid.read(n)[:18].decode(): struct.unpack("d" * 6, fid.read(8 * 6)) for _ in range(N)}
+
+        else:
+            return [(fid.read(n)[:18].decode(),) + struct.unpack("d" * 6, fid.read(8 * 6)) for _ in range(N)]
+
+
+def read_pre_file(filename):
+    with open(filename, "rb") as fid:
+        d = np.fromfile(fid, float, -1).reshape((-1, 291))
+        Yleft, Rleft, Rright, dy = np.moveaxis((d[:, :288:2] + d[:, 1:288:2] * 1j).reshape((-1, 4, 6, 6)), 1, 0)
+        sleft, sright = d[:, 288:290].T
+        fid.seek(0, 0)
+        level = np.fromfile(fid, np.int32, -1).reshape((-1, 291 * 2))[:, -2]
+    return {
+        "Yleft": (["i", "j", "k"], Yleft),
+        "Rleft": (["i", "j", "k"], Rleft),
+        "Rright": (["i", "j", "k"], Rright),
+        "dyxu0": (["i", "j"], dy[:, 0]),
+        "dyxu1": (["i", "j"], dy[:, 1]),
+        "dyxv0": (["i", "j"], dy[:, 2]),
+        "dyxv1": (["i", "j"], dy[:, 3]),
+        "dyxw0": (["i", "j"], dy[:, 4]),
+        "dyxw1": (["i", "j"], dy[:, 5]),
+        "sleft": (["i"], sleft),
+        "sright": (["i"], sright),
+        "level": (["i"], level),
+    }
+
+
+def read_lut_file(filename, prelut_folder):
+    parameters = Parameters(prelut_folder)
+    casedata = CaseData(os.path.dirname(filename))
+    var = os.path.basename(filename)[:2]
+    level = int(filename[-8:-4])
+    z = casedata.zhub if level == 9999 else casedata.z0 * np.exp(casedata.ds * level)
+
+    lut = np.fromfile(filename, complex, -1).reshape((len(parameters.kz0_lst) + 1, len(parameters.beta_lst)))
+    lut = lut[1:].T
+    return xr.Dataset(
+        {
+            var: (("beta", "kz0", "level"), lut[:, :, na]),
+            "z": (("level"), [z]),
+            "diameter": casedata.radius * 2,
+            "hubheight": casedata.zhub,
+            "z0": casedata.z0,
+        },
+        coords={"kz0": parameters.kz0_lst, "beta": parameters.beta_lst, "level": [level]},
+    )
+
+
+def read_lut_dat_file(filename, nx, ny, dx, dy):
+    dat = np.fromfile(filename, np.dtype("<f"), -1).astype(float).reshape((ny // 2, nx))
+    x_lst = np.arange(-nx // 4, nx * 3 / 4) * dx  # rotor is located 1/4 downstream
+
+    y_lst = np.arange(ny // 2) * dy
+    return xr.DataArray(dat, dims=("y", "x"), coords={"x": x_lst, "y": y_lst})