pyqihou 0.1.0__tar.gz

pyqihou-0.1.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: pyqihou
+Version: 0.1.0
+Summary: Python Package for Climate Analysis
+Author-email: VVVictorZhou <ahme02147483647a@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/VVVICTORZHOU/
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.19.5
+Requires-Dist: scipy>=1.5.4
+Requires-Dist: windspharm>=1.7.0
+Requires-Dist: xarray>=0.16.2
+
+## How to install the `pyqihou` package:
+
+- Method 1: `npm install pyqihou`
+
+- Method 2: `pip install pyqihou`
+
+
+## Functions in the `pyqihou` package:
+### `water.py`
+
+- `MassIntegrationAlongPressure`: 沿著垂直氣壓層執行大氣變數的質量積分。   
+- `HorizontalMoistureAdvection`: 計算水平水氣平流的熱力學與動力學分解項，並進行氣壓層垂直積分。   
+- `VerticalMoistureAdvection`: 計算垂直水氣平流的熱力學與動力學分解項，並進行氣壓層垂直積分。   
+- `RelativeHumidity`: 依據溫度、比濕與氣壓計算大氣相對濕度百分比。   
+- `VaporPressureDeficit`: 依據溫度、比濕與氣壓計算水氣壓差 (VPD)。   
+
+### `energy.py`
+
+- `MixedLayerHeatBudget`: 計算混合層熱平衡的各項輻射、熱通量與物理分解項。   
+- `NetEnergyInput`: 計算大氣與地表的淨能量輸入 (NEI)。   
+- `EnergyFluxPotential`: 計算能量通量位勢 (EFP) 並自動處理標準網格內插與還原。   
+- `MeridionalMassStreamFunction`: 計算經向質量經流函數 (MSF)。   
+- `ZonalMassStreamFunction`: 計算緯向質量經流函數 (MSF)。  
+- `HorizontalTN01WaveActivityFlux`: 計算幾何校正版的 Takaya-Nakamura (2001) 水平波活動通量與其散度。   
+
+
+
+

pyqihou-0.1.0/README.md

@@ -0,0 +1,28 @@
+## How to install the `pyqihou` package:
+
+- Method 1: `npm install pyqihou`
+
+- Method 2: `pip install pyqihou`
+
+
+## Functions in the `pyqihou` package:
+### `water.py`
+
+- `MassIntegrationAlongPressure`: 沿著垂直氣壓層執行大氣變數的質量積分。   
+- `HorizontalMoistureAdvection`: 計算水平水氣平流的熱力學與動力學分解項，並進行氣壓層垂直積分。   
+- `VerticalMoistureAdvection`: 計算垂直水氣平流的熱力學與動力學分解項，並進行氣壓層垂直積分。   
+- `RelativeHumidity`: 依據溫度、比濕與氣壓計算大氣相對濕度百分比。   
+- `VaporPressureDeficit`: 依據溫度、比濕與氣壓計算水氣壓差 (VPD)。   
+
+### `energy.py`
+
+- `MixedLayerHeatBudget`: 計算混合層熱平衡的各項輻射、熱通量與物理分解項。   
+- `NetEnergyInput`: 計算大氣與地表的淨能量輸入 (NEI)。   
+- `EnergyFluxPotential`: 計算能量通量位勢 (EFP) 並自動處理標準網格內插與還原。   
+- `MeridionalMassStreamFunction`: 計算經向質量經流函數 (MSF)。   
+- `ZonalMassStreamFunction`: 計算緯向質量經流函數 (MSF)。  
+- `HorizontalTN01WaveActivityFlux`: 計算幾何校正版的 Takaya-Nakamura (2001) 水平波活動通量與其散度。   
+
+
+
+

pyqihou-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=61.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyqihou" 
+version = "0.1.0"
+description = "Python Package for Climate Analysis"
+readme = "README.md"
+authors = [
+    { name = "VVVictorZhou", email = "ahme02147483647a@gmail.com" }
+]
+license = { text = "MIT" }
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+requires-python = ">=3.6"
+dependencies = [
+    "numpy>=1.19.5",
+    "scipy>=1.5.4",
+    "windspharm>=1.7.0",
+    "xarray>=0.16.2"
+]
+
+[project.urls]
+Homepage = "https://github.com/VVVICTORZHOU/"

pyqihou-0.1.0/pyqihou/energy.py

@@ -0,0 +1,497 @@
+import numpy as np
+import xarray as xr
+from windspharm.tools import prep_data, recover_data
+from windspharm.xarray import VectorWind
+import spharm.spharm
+from scipy.interpolate import RegularGridInterpolator
+
+def MixedLayerHeatBudget(EXP_TS, EXP_FSNS, EXP_FSNSC, EXP_FLNS, EXP_SHFLX, EXP_LHFLX, EXP_U10, EXP_RHREFHT, EXP_TREFHT,
+                        CTL_TS, CTL_LHFLX, CTL_U10, CTL_RHREFHT, CTL_TREFHT):
+    """
+    計算混合層熱平衡（Mixed Layer Heat Budget）各項通量與分解項。
+
+    Parameters
+    ----------
+    EXP_TS : np.ndarray 或 xr.DataArray
+        實驗組地表溫度 (Surface Temperature)，單位：K，維度形狀：(time, lat, lon) 或通用網格。
+    EXP_FSNS : np.ndarray 或 xr.DataArray
+        實驗組表面淨短波輻射 (Surface Net Shortwave Radiation)，單位：W/m^2，維度形狀同上。
+    EXP_FSNSC : np.ndarray 或 xr.DataArray
+        實驗組表面無雲淨短波輻射 (Clear-sky Surface Net Shortwave Radiation)，單位：W/m^2，維度形狀同上。
+    EXP_FLNS : np.ndarray 或 xr.DataArray
+        實驗組表面淨長波輻射 (Surface Net Longwave Radiation)，單位：W/m^2，維度形狀同上。
+    EXP_SHFLX : np.ndarray 或 xr.DataArray
+        實驗組表面感熱通量 (Surface Sensible Heat Flux)，單位：W/m^2，維度形狀同上。
+    EXP_LHFLX : np.ndarray 或 xr.DataArray
+        實驗組表面潛熱通量 (Surface Latent Heat Flux)，單位：W/m^2，維度形狀同上。
+    EXP_U10 : np.ndarray 或 xr.DataArray
+        實驗組 10 公尺風速 (10-meter Wind Speed)，單位：m/s，維度形狀同上。
+    EXP_RHREFHT : np.ndarray 或 xr.DataArray
+        實驗組參考高度相對濕度 (Relative Humidity at Reference Height)，無因次 (0-1)，維度形狀同上。
+    EXP_TREFHT : np.ndarray 或 xr.DataArray
+        實驗組參考高度溫度 (Temperature at Reference Height)，單位：K，維度形狀同上。
+    CTL_TS : np.ndarray 或 xr.DataArray
+        對照組地表溫度，單位：K，維度形狀同上。
+    CTL_LHFLX : np.ndarray 或 xr.DataArray
+        對照組表面潛熱通量，單位：W/m^2，維度形狀同上。
+    CTL_U10 : np.ndarray 或 xr.DataArray
+        對照組 10 公尺風速，單位：m/s，維度形狀同上。
+    CTL_RHREFHT : np.ndarray 或 xr.DataArray
+        對照組參考高度相對濕度，無因次 (0-1)，維度形狀同上。
+    CTL_TREFHT : np.ndarray 或 xr.DataArray
+        對照組參考高度溫度，單位：K，維度形狀同上。
+
+    Returns
+    -------
+    tuple of np.ndarray
+        包含以下各項的計算結果陣列（維度形狀與輸入相同）：
+        - TS_TERM : 地表溫度項
+        - FSNS_TERM : 淨短波輻射項
+        - FSNS_CLR_TERM : 無雲淨短波輻射項
+        - FSNS_CLD_TERM : 雲對短波輻射效應項
+        - FLNS_TERM : 淨長波輻射項
+        - SHFLX_TERM : 感熱通量項
+        - LHFLX_TERM : 潛熱通量項
+        - LHFLX_WIND_TERM : 潛熱通量風速分解項（若缺少參數則為 None）
+        - LHFLX_RH_TERM : 潛熱通量相對濕度分解項（若缺少參數則為 None）
+        - LHFLX_TGRAD_TERM : 潛熱通量溫度梯度分解項（若缺少參數則為 None）
+        - Residual_TERM : 殘差項
+    """
+
+    Alpha = 0.06
+    
+    # Left Hand Side
+    TS_TERM = EXP_TS
+
+    EXP_DeltaT = EXP_TREFHT - EXP_TS
+    CTL_DeltaT = CTL_TREFHT - CTL_TS
+
+    # Right Hand Side
+    FSNS_TERM = EXP_FSNS / (Alpha * CTL_LHFLX)
+    FSNS_CLR_TERM = EXP_FSNSC / (Alpha * CTL_LHFLX)
+    FSNS_CLD_TERM = FSNS_TERM - FSNS_CLR_TERM
+    FLNS_TERM = - EXP_FLNS / (Alpha * CTL_LHFLX)
+    SHFLX_TERM = - EXP_SHFLX / (Alpha * CTL_LHFLX)
+    LHFLX_TERM = - EXP_LHFLX / (Alpha * CTL_LHFLX)
+
+    # Residual Term
+    Residual_TERM = TS_TERM - (FSNS_TERM + FLNS_TERM + SHFLX_TERM + LHFLX_TERM)
+    
+    # Latent Heat Term Decomposition
+    if EXP_RHREFHT is not None and EXP_U10 is not None and EXP_DeltaT is not None:
+        LHFLX_WIND_TERM = - (CTL_LHFLX * EXP_U10) / (CTL_U10 * Alpha * CTL_LHFLX)
+        LHFLX_RH_TERM = (CTL_LHFLX * EXP_RHREFHT) / (Alpha * CTL_LHFLX * (np.exp(- Alpha * CTL_DeltaT) - CTL_RHREFHT))
+        LHFLX_TGRAD_TERM = (Alpha * CTL_LHFLX * CTL_RHREFHT * EXP_DeltaT) / (Alpha * CTL_LHFLX * (np.exp(- Alpha * CTL_DeltaT) - CTL_RHREFHT))
+
+    else:
+        LHFLX_WIND_TERM = None
+        LHFLX_RH_TERM = None
+        LHFLX_TGRAD_TERM = None
+
+    return TS_TERM, FSNS_TERM, FSNS_CLR_TERM, FSNS_CLD_TERM, FLNS_TERM, SHFLX_TERM, LHFLX_TERM, LHFLX_WIND_TERM, LHFLX_RH_TERM, LHFLX_TGRAD_TERM, Residual_TERM
+
+
+def NetEnergyInput(FSNT, FLNT, FSNS, FLNS, LHFLX, SHFLX):
+    """
+    計算大氣與地表的淨能量輸入 (Net Energy Input, NEI)。
+
+    Parameters
+    ----------
+    FSNT : np.ndarray 或 xr.DataArray
+        大氣頂向下淨短波輻射 (TOA Net Shortwave Radiation)，單位：W/m^2，維度形狀：(time, lat, lon) 或 (lat, lon)。
+    FLNT : np.ndarray 或 xr.DataArray
+        大氣頂向上長波輻射 (TOA Net Longwave Radiation)，單位：W/m^2，維度形狀同上。
+    FSNS : np.ndarray 或 xr.DataArray
+        表面向下淨短波輻射 (Surface Net Shortwave Radiation)，單位：W/m^2，維度形狀同上。
+    FLNS : np.ndarray 或 xr.DataArray
+        表面向下淨長波輻射 (Surface Net Longwave Radiation)，單位：W/m^2，維度形狀同上。
+    LHFLX : np.ndarray 或 xr.DataArray
+        表面潛熱通量 (Surface Latent Heat Flux)，單位：W/m^2，維度形狀同上。
+    SHFLX : np.ndarray 或 xr.DataArray
+        表面感熱通量 (Surface Sensible Heat Flux)，單位：W/m^2，維度形狀同上。
+
+    Returns
+    -------
+    NEI : np.ndarray 或 xr.DataArray
+        淨能量輸入，單位：W/m^2，維度形狀與輸入相同。
+    """
+    # Calculate the net energy input
+    NEI = (FSNT - FLNT) - (FSNS - FLNS - LHFLX - SHFLX)
+    return NEI
+
+
+def EnergyFluxPotential(NEI, lat=None, lon=None, rsphere=6.3712e6):
+    """
+    計算能量通量位勢 (Energy Flux Potential, EFP)，並自動內插回與輸入 NEI 相同的網格與座標。
+    
+    Parameters
+    ----------
+    NEI : np.ndarray
+        淨能量輸入，單位：W/m^2，維度形狀：(time, lat, lon)。
+    lat : np.ndarray, optional
+        輸入的 1D 緯度座標，單位：度 (°)，維度形狀：(nlat,)。若為 None 則自動產生。
+    lon : np.ndarray, optional
+        輸入的 1D 經度座標，單位：度 (°)，維度形狀：(nlon,)。若為 None 則自動產生。
+    rsphere : float, optional
+        地球半徑，單位：m，預設值為 6.3712e6。
+        
+    Returns
+    -------
+    efp_out : np.ndarray
+        能量通量位勢 (EFP)，維度形狀與輸入 NEI 相同：(time, lat, lon)。
+    """
+    nt, nlat, nlon = NEI.shape
+    
+    # 1. 自動建立或接收輸入的經緯度座標
+    if lat is None:
+        lat = np.linspace(-90, 90, nlat)
+    if lon is None:
+        lon = np.linspace(0, 360, nlon, endpoint=False)
+        
+    # 2. 建立輸入資料的 xarray.DataArray
+    year_coords = [1] if nt == 1 else list(range(1, nt + 1))
+    nei_da = xr.DataArray(
+        NEI, 
+        coords=[('year', year_coords), ('lat', lat), ('lon', lon)], 
+        name='NEI'
+    )
+    
+    # 3. 核心計算所需的標準網格（spharm 通常需要特定或標準解析度，此處維持 193 點緯度）
+    nlat_calc = 193
+    lat_calc = np.linspace(-90, 90, nlat_calc)
+    lon_calc = lon  # 經度可以保持與輸入一致
+    
+    # 先將輸入內插至計算所需的網格
+    nei_calc = nei_da.interp(lat=lat_calc, lon=lon_calc, method='linear')
+    
+    # 若只有 1 個時間點，仿原程式複製成 3 個 year 以符合計算模組需求
+    is_single_time = (nt == 1)
+    if is_single_time:
+        nei_calc = xr.concat([nei_calc, nei_calc, nei_calc], dim='year')
+        nei_calc['year'] = [1, 2, 3]
+        
+    # 4. 執行頻譜計算 (Spherical harmonic inverse Laplacian)
+    scalar_field, shape_info = prep_data(nei_calc.data, "tyx")
+    vw = VectorWind(nei_calc, nei_calc)
+    S = vw._api.s  # Spharmt instance
+    
+    scalar_field_spec = S.grdtospec(scalar_field)
+    ilap_spec = spharm.spharm._spherepack.invlap(scalar_field_spec, S.rsphere)
+    ilap_grid = S.spectogrd(ilap_spec)
+    efp_calc = recover_data(ilap_grid, shape_info)
+    
+    # 包成計算網格的 DataArray
+    efp_calc_da = xr.DataArray(efp_calc, coords=nei_calc.coords, dims=nei_calc.dims, name='EFP')
+    
+    # 5. 【關鍵簡化】：直接將計算結果內插回使用者「原本輸入的網格」(lat, lon)
+    efp_final_da = efp_calc_da.interp(lat=lat, lon=lon, method='linear')
+    
+    # 6. 恢復原本的時間維度形狀
+    if is_single_time:
+        # 如果原本時間維度只有 1，取第一筆並擴展軸回 (1, lat, lon)
+        efp_out = np.expand_dims(efp_final_da.isel(year=0).values, axis=0)
+    else:
+        efp_out = efp_final_da.isel(year=slice(0, nt)).values
+        
+    return efp_out
+
+
+def MeridionalMassStreamFunction(V, lev, lat):
+    """
+    計算經向質量經流函數 (Meridional Mass Streamfunction, MSF)。
+
+    Parameters
+    ----------
+    V : np.ndarray
+        經向風速 (Meridional Wind Speed)，單位：m/s，維度形狀：(lev, lat)。
+    lev : np.ndarray
+        氣壓高度層 (Pressure Levels)，單位：hPa（程式碼內部會依此計算層厚度 dP），維度形狀：(lev,)。
+    lat : np.ndarray
+        緯度座標，單位：度 (°)，維度形狀：(lat,)。
+
+    Returns
+    -------
+    final_msf : np.ndarray
+        經向質量經流函數，單位：kg/s，維度形狀：(lev, lat)。
+    """
+
+    # 1. 處理 NaN：將地形以下的 NaN 設為 0
+    V_safe = np.nan_to_num(V, nan=0.0)
+    
+    # 2. 計算 dP (單位已轉換: hPa -> Pa)
+    # 假設 lev 是從地面到高空 [1000, 950, ..., 50]
+    # 計算各層厚度，這裡建議使用更精確的層界(bounds)
+    #! only foe evenly spaced levels, for unevenly spaced levels, we should calculate the layer thickness based on the actual level values
+    dP = np.abs(np.gradient(lev)) # 為 Pascal
+    
+    # 3. 質量修正 (V_adj) - 確保垂直積分和為 0
+    total_Vdp = np.sum(V_safe * dP[:, None], axis=0)
+    total_dP = np.sum((~np.isnan(V)) * dP[:, None], axis=0)
+    V_adj = total_Vdp / total_dP
+    
+    # 4. 積分 (從大氣頂部向下累加)
+    # 使用 np.cumsum 會比寫 for loop 快且安全
+    V_corrected = (V_safe - V_adj)
+    # Multiply V and dP first, then flip and cumsum
+    msf = np.cumsum((V_corrected * dP[:, None])[::-1, :], axis=0)[::-1, :]
+    
+    # 5. 物理常數
+    re = 6.371e6 # 地球半徑
+    g = 9.81
+    cos_lat = np.cos(np.deg2rad(lat))
+    
+    final_msf = (2 * np.pi * re * cos_lat / g) * msf
+    return final_msf
+
+def ZonalMassStreamFunction(U_lonmean, lev, lat_bounds=(-10.0, 10.0), re=6.371e6, g=9.81):
+    """
+    計算緯向質量經流函數 (Zonal Mass Streamfunction, MSF) 或稱為 Walker 環流。
+
+    Parameters
+    ----------
+    U_lonmean : np.ndarray
+        經向平均的緯向風速 (Zonal Wind Speed)，單位：m/s，維度形狀：(nlev, nlon)。
+        NaN 值表示地形以下的缺測值。
+    lev : np.ndarray
+        氣壓高度層 (Pressure Levels)，單位：hPa，維度形狀：(nlev,)，遞減 (地面到高空)。
+    lat_bounds : tuple, optional
+        緯度平均的邊界 (南緯, 北緯)，單位：度 (°)，預設為 (-10.0, 10.0)。
+    re : float, optional
+        地球半徑，單位：m，預設值為 6.371e6。
+    g : float, optional
+        重力加速度，單位：m/s^2，預設值為 9.81。
+
+    Returns
+    -------
+    final_msf : np.ndarray
+        緯向質量經流函數 (Zonal Mass Streamfunction)，單位：kg/s，維度形狀：(nlev, nlon)。
+        返回的結果保留原始氣壓層順序，地形以下的層仍為 NaN。
+    """
+    
+
+    U = np.asarray(U_lonmean, dtype=float)
+    p = np.asarray(lev, dtype=float) * 100.0  # hPa -> Pa
+
+    # --------------------------------------------------
+    # 1. Input validation
+    # --------------------------------------------------
+    if U.ndim != 2 or U.shape[0] != len(p):
+        raise ValueError("U_lonmean must have shape (nlev, nlon).")
+
+    if not np.all(np.isfinite(p)):
+        raise ValueError("Pressure levels must be finite.")
+
+    if not np.all(np.diff(p) > 0) and not np.all(np.diff(p) < 0):
+        raise ValueError("Pressure levels must be strictly monotonic.")
+
+    # Sort pressure from top to bottom (increasing pressure)
+    if p[0] > p[-1]:
+        order = np.arange(len(p) - 1, -1, -1)
+    else:
+        order = np.arange(len(p))
+
+    p_sorted = p[order]
+    U_sorted = U[order, :]
+
+    nlev, nlon = U.shape
+
+    # --------------------------------------------------
+    # 2. Meridional width
+    # --------------------------------------------------
+    phi_s, phi_n = np.deg2rad(lat_bounds)
+    delta_phi = phi_n - phi_s
+
+    if delta_phi <= 0:
+        raise ValueError("Invalid latitude boundaries.")
+
+    factor = re * delta_phi / g
+
+    # --------------------------------------------------
+    # 3. Allocate output
+    # --------------------------------------------------
+    psi_sorted = np.full((nlev, nlon), np.nan)
+
+    # --------------------------------------------------
+    # 4. Process individual longitude profiles
+    # --------------------------------------------------
+    for j in range(nlon):
+
+        u_col = U_sorted[:, j]
+
+        # Valid levels
+        valid = np.isfinite(u_col)
+
+        # Find the first missing level (usually terrain)
+        invalid_idx = np.where(~valid)[0]
+
+        if len(invalid_idx) > 0:
+            n_valid = invalid_idx[0]
+
+            # Do not interpolate across internal missing levels
+            if np.any(valid[n_valid:]):
+                raise ValueError(
+                    "Non-contiguous NaNs at longitude index {}."
+                    .format(j)
+                )
+        else:
+            n_valid = nlev
+
+        # At least two valid pressure levels are necessary
+        if n_valid < 2:
+            continue
+
+        # Extract the contiguous atmospheric column
+        p_col = p_sorted[:n_valid]
+        u_col = u_col[:n_valid]
+
+        # Actual pressure thickness between adjacent levels
+        dp = np.diff(p_col)
+
+        # --------------------------------------------------
+        # 5. Pressure-weighted vertical mean wind
+        # --------------------------------------------------
+        total_Udp = np.sum(
+            0.5 * (u_col[:-1] + u_col[1:]) * dp
+        )
+
+        total_dP = p_col[-1] - p_col[0]
+
+        U_adj = total_Udp / total_dP
+
+        # Remove vertically averaged zonal wind
+        U_corrected = u_col - U_adj
+
+        # --------------------------------------------------
+        # 6. Cumulative vertical integration
+        # --------------------------------------------------
+        increments = (
+            0.5 * (U_corrected[:-1] + U_corrected[1:])
+            * dp
+        )
+
+        msf = np.zeros(n_valid)
+
+        msf[1:] = np.cumsum(increments)
+
+        # Enforce exact zero at the lower boundary
+        msf[-1] = 0.0
+
+        # --------------------------------------------------
+        # 7. Convert to mass streamfunction (kg/s)
+        # --------------------------------------------------
+        psi_sorted[:n_valid, j] = factor * msf
+
+    # --------------------------------------------------
+    # 8. Restore original pressure ordering
+    # --------------------------------------------------
+    final_msf = np.empty_like(psi_sorted)
+    final_msf[order, :] = psi_sorted
+
+    return final_msf
+
+
+def HorizontalTN01WaveActivityFlux(CTL_U, CTL_V, EXP_Z, lon=np.linspace(0, 358.75, 288), lat=np.linspace(-90, 90, 192), p_lev=500.0):
+    """
+    幾何校正版：計算 Takaya and Nakamura (JAS, 2001) 水平波活動通量 (HOR-TN01-WAF)。
+    直接在公尺 (meter) 尺度下進行偏微分，解決低緯度/高緯度幾何變形產生的假向量。
+
+    Parameters
+    ----------
+    CTL_U : np.ndarray
+        對照組緯向風速 (Zonal Wind Speed)，單位：m/s，維度形狀：(lat, lon)。
+    CTL_V : np.ndarray
+        對照組經向風速 (Meridional Wind Speed)，單位：m/s，維度形狀：(lat, lon)。
+    EXP_Z : np.ndarray
+        實驗組位勢高度或擾動位勢高度 (Geopotential Height)，單位：m，維度形狀：(lat, lon)。
+    lon : np.ndarray, optional
+        經度座標，單位：度 (°)，預設為 288 個點由 0 到 358.75，維度形狀：(lon,)。
+    lat : np.ndarray, optional
+        緯度座標，單位：度 (°)，預設為 192 個點由 -90 到 90，維度形狀：(lat,)。
+    p_lev : float, optional
+        計算通量時所使用的氣壓高度層，單位：hPa，預設值為 500.0。
+
+    Returns
+    -------
+    px : np.ndarray
+        水平波活動通量的經向/x 分量，單位：m^2/s^2，維度形狀：(lat, lon)。
+    py : np.ndarray
+        水平波活動通量的緯向/y 分量，單位：m^2/s^2，維度形狀：(lat, lon)。
+    psi_p : np.ndarray
+        擾動流函數 (Perturbation Streamfunction)，單位：m^2/s，維度形狀：(lat, lon)。
+    waf_div : np.ndarray
+        波活動通量散度 (WAF Divergence)，單位：s^-1 相關，維度形狀：(lat, lon)。
+    """
+    # 常數設定
+    a = 6.37e6        # 地球半徑 (m)
+    omega = 7.292e-5  # 地球自轉角速度 (rad/s)
+    
+    # 角度轉弧度
+    lon_rad = np.deg2rad(lon)
+    lat_rad = np.deg2rad(lat)
+    
+    # 計算基本的弧度網格距
+    dlon_rad = np.gradient(lon_rad)
+    dlat_rad = np.gradient(lat_rad)
+    
+    # 幾何參數 (2D 廣播化)
+    cos_lat = np.cos(lat_rad)[:, np.newaxis]
+    sin_lat = np.sin(lat_rad)[:, np.newaxis]
+    
+    # 科氏參數 f (2D)，避開赤道無窮大
+    f = 2 * omega * sin_lat
+    f[np.abs(f) < 1e-5] = np.nan 
+    
+    # 1. 計算擾動流函數 psi_p (單位: m^2/s)
+    psi_p = EXP_Z / f
+    
+    # =====================================================================
+    # 核心幾何修正：計算真正對應「公尺」單位的網格距 dx, dy
+    # dy = a * dlat (緯度方向的實際距離，每個地方都一樣)
+    # dx = a * cos(lat) * dlon (經度方向的實際距離，隨緯度增高而縮小)
+    # =====================================================================
+    dy_2d = a * dlat_rad[:, np.newaxis]
+    dx_2d = a * cos_lat * dlon_rad[np.newaxis, :]
+    
+    # 2. 計算流函數對實際距離 (m) 的一階偏微分
+    dpsi_dx = np.gradient(psi_p, axis=1) / dx_2d
+    dpsi_dy = np.gradient(psi_p, axis=0) / dy_2d
+    
+    # 3. 計算實際距離 (m) 的二階偏微分
+    d2psi_dx2 = np.gradient(dpsi_dx, axis=1) / dx_2d
+    d2psi_dy2 = np.gradient(dpsi_dy, axis=0) / dy_2d
+    d2psi_dxdy = np.gradient(dpsi_dy, axis=1) / dx_2d  # 混合偏微分
+    
+    # 4. 計算波活動度矩陣項 (完全回歸標準 Cartesian 物理形式)
+    termxu = dpsi_dx * dpsi_dx - psi_p * d2psi_dx2
+    termxv = dpsi_dx * dpsi_dy - psi_p * d2psi_dxdy
+    termyv = dpsi_dy * dpsi_dy - psi_p * d2psi_dy2
+    
+    # 5. 計算風速基本場
+    magU = np.sqrt(CTL_U**2 + CTL_V**2)
+    magU[magU == 0] = np.nan
+    
+    # T-N01 公式核心係數: p_normalized / (2 * |U|)
+    p_normalized = p_lev / 1000.0
+    coeff = p_normalized / (2 * magU)
+    
+    # 6. 計算 WAF 分量 (單位: m^2/s^2)
+    # 此時公式變得極度乾淨，再也不需要除以額外的 a^2 或 cos_lat
+    px = coeff * (CTL_U * termxu + CTL_V * termxv)
+    py = coeff * (CTL_U * termxv + CTL_V * termyv)
+    
+    # 7. 計算散度 (Divergence)
+    # 既然 px, py 已經是標準米制分量，散度直接用標準的 d(px)/dx + d(py)/dy 即可！
+    dp_dx = np.gradient(px, axis=1) / dx_2d
+    dp_dy = np.gradient(py, axis=0) / dy_2d
+    waf_div = dp_dx + dp_dy
+    
+    # 8. 設定科學合理的邊界遮罩 (Mask)
+    # 準地轉理論在南北緯 10 度以內、以及 80 度以上本身就不適用
+    lat_mask = (np.abs(lat) > 80) | (np.abs(lat) < 15)
+    
+    px[lat_mask, :] = np.nan
+    py[lat_mask, :] = np.nan
+    waf_div[lat_mask, :] = np.nan
+    
+    return px, py, psi_p, waf_div
+

pyqihou-0.1.0/pyqihou/water.py

@@ -0,0 +1,260 @@
+import numpy as np
+
+
+def MassIntegrationAlongPressure(pressure, variable, pmin=None, pmax=None):
+    """
+    沿著垂直氣壓層進行質量積分（Mass Integration Along Pressure）。
+
+    Parameters
+    ----------
+    pressure : np.ndarray
+        氣壓高度層，單位：hPa，維度形狀：(lev,)。
+    variable : np.ndarray
+        欲積分的大氣變數，單位：W/kg 或對應物理量，維度形狀：(lev, lat, lon)。
+    pmin : float, optional
+        積分的氣壓下限（高空/低壓側），單位：hPa，預設為 None（從最頂層開始）。
+    pmax : float, optional
+        積分的氣壓上限（地表/高壓側），單位：hPa，預設為 None（到最底層結束）。
+
+    Returns
+    -------
+    integrated_variable : np.ndarray
+        經垂直質量積分後的 2D 變數，維度形狀：(lat, lon)。
+    """
+    # 1. 參數驗證
+    if pmin is not None and not isinstance(pmin, (int, float)):
+        raise ValueError("pmin must be a numeric value.")
+    if pmax is not None and not isinstance(pmax, (int, float)):
+        raise ValueError("pmax must be a numeric value.")
+    if pmin is not None and pmax is not None and pmin >= pmax:
+        raise ValueError("pmin must be less than pmax.")
+
+    # 2. 轉換壓力單位為 Pa
+    p_pa = np.asarray(pressure, dtype=float) * 100.0 
+    Pa_to_kg_per_m2 = 0.1  # 1/g 
+
+    # 3. 計算不等間距的 dp 與對應的 dm
+    dp_array = np.abs(np.gradient(p_pa))  # [lev,]
+    dm = dp_array * Pa_to_kg_per_m2       # [lev,]
+
+    # 4. 建立垂直層條件遮罩 (Mask)
+    mask = np.ones(p_pa.shape[0], dtype=bool)
+    pmin_pa = pmin * 100.0 if pmin is not None else None
+    pmax_pa = pmax * 100.0 if pmax is not None else None
+
+    for i, p in enumerate(p_pa):
+        if pmin_pa is not None and p < pmin_pa:
+            mask[i] = False
+        if pmax_pa is not None and p > pmax_pa:
+            mask[i] = False
+
+    # 套用遮罩：不符合範圍的層其 dm 設為 0
+    masked_dm = np.where(mask, dm, 0.0)
+
+    # 5. 處理變數中的 NaN 並進行廣播矩陣乘法
+    var_clean = np.nan_to_num(variable, nan=0.0)
+    
+    # 利用 broadcasting 將 dm [lev] 擴展為 [lev, 1, 1] 與 variable 相乘後在 lev 軸（axis=0）加總
+    integrated_variable = np.sum(var_clean * masked_dm[:, None, None], axis=0)
+
+    return integrated_variable.astype(np.float32)
+
+
+def HorizontalMoistureAdvection(pressure, CTL_u, CTL_v, CTL_q, EXP_u, EXP_v, EXP_q, pmin=None, pmax=None):
+    """
+    計算水平水氣平流項的熱力學分解與動力學分解，並沿氣壓層垂直積分。
+
+    Parameters
+    ----------
+    pressure : np.ndarray
+        氣壓高度層，單位：hPa，維度形狀：(lev,)。
+    CTL_u : np.ndarray
+        對照組緯向風速 (Zonal Wind)，單位：m/s，維度形狀：(lev, lat, lon)。
+    CTL_v : np.ndarray
+        對照組經向風速 (Meridional Wind)，單位：m/s，維度形狀：(lev, lat, lon)。
+    CTL_q : np.ndarray
+        對照組比濕 (Specific Humidity)，單位：kg/kg，維度形狀：(lev, lat, lon)。
+    EXP_u : np.ndarray
+        實驗組緯向風速，單位：m/s，維度形狀：(lev, lat, lon)。
+    EXP_v : np.ndarray
+        實驗組經向風速，單位：m/s，維度形狀：(lev, lat, lon)。
+    EXP_q : np.ndarray
+        實驗組比濕，單位：kg/kg，維度形狀：(lev, lat, lon)。
+    pmin : float, optional
+        垂直積分的氣壓下限，單位：hPa，預設為 None。
+    pmax : float, optional
+        垂直積分的氣壓上限，單位：hPa，預設為 None。
+
+    Returns
+    -------
+    integrated_thermodynamic_term : np.ndarray
+        積分後的水平水氣平流熱力學項，單位：W/m^2 (經潛熱轉換)，維度形狀：(lat, lon)。
+    integrated_dynamic_term : np.ndarray
+        積分後的水平水氣平流動力學項，單位：W/m^2 (經潛熱轉換)，維度形狀：(lat, lon)。
+    """
+    assert CTL_u.shape == CTL_v.shape == CTL_q.shape == EXP_u.shape == EXP_v.shape == EXP_q.shape
+
+    # set up the grid
+    dx, dy = 1.25*110*1000, 180/192*110*1000 # m
+    thermodynamic_term = np.zeros_like(CTL_u)
+    dynamic_term = np.zeros_like(CTL_u)
+
+    # unit conversion for q
+    latent_heat = 2.5e6 # [J/kg]
+    CTL_q_energy = CTL_q * latent_heat
+    EXP_q_energy = EXP_q * latent_heat
+
+    # calculate the gradient of q
+    CTL_dqdx = np.gradient(CTL_q_energy, dx, axis=2)
+    CTL_dqdy = np.gradient(CTL_q_energy, dy, axis=1)
+    EXP_dqdx = np.gradient(EXP_q_energy, dx, axis=2)
+    EXP_dqdy = np.gradient(EXP_q_energy, dy, axis=1)
+
+    # 計算平流項
+    for lev in range(0, CTL_u.shape[0]):
+        thermodynamic_term[lev, :, :] = CTL_u[lev, :, :] * EXP_dqdx[lev, :, :] + CTL_v[lev, :, :] * EXP_dqdy[lev, :, :]
+        dynamic_term[lev, :, :] = CTL_dqdx[lev, :, :] * EXP_u[lev, :, :] + CTL_dqdy[lev, :, :] * EXP_v[lev, :, :]
+
+    # 呼叫積分函數
+    integrated_thermodynamic_term = -MassIntegrationAlongPressure(pressure, thermodynamic_term, pmin=pmin, pmax=pmax)
+    integrated_dynamic_term = -MassIntegrationAlongPressure(pressure, dynamic_term, pmin=pmin, pmax=pmax)
+
+    return integrated_thermodynamic_term, integrated_dynamic_term
+
+
+def VerticalMoistureAdvection(pressure, CTL_omega, CTL_q, EXP_omega, EXP_q, pmin=None, pmax=None):
+    """
+    計算垂直水氣平流項的熱力學分解與動力學分解，並沿氣壓層垂直積分。
+
+    Parameters
+    ----------
+    pressure : np.ndarray
+        氣壓高度層，單位：hPa，維度形狀：(lev,)。
+    CTL_omega : np.ndarray
+        對照組垂直p速度 (Pressure Velocity)，單位：Pa/s，維度形狀：(lev, lat, lon)。
+    CTL_q : np.ndarray
+        對照組比濕，單位：kg/kg，維度形狀：(lev, lat, lon)。
+    EXP_omega : np.ndarray
+        實驗組垂直p速度，單位：Pa/s，維度形狀：(lev, lat, lon)。
+    EXP_q : np.ndarray
+        實驗組比濕，單位：kg/kg，維度形狀：(lev, lat, lon)。
+    pmin : float, optional
+        垂直積分的氣壓下限，單位：hPa，預設為 None。
+    pmax : float, optional
+        垂直積分的氣壓上限，單位：hPa，預設為 None。
+
+    Returns
+    -------
+    integrated_thermodynamic_term : np.ndarray
+        積分後的垂直水氣平流熱力學項，單位：W/m^2 (經潛熱轉換)，維度形狀：(lat, lon)。
+    integrated_dynamic_term : np.ndarray
+        積分後的垂直水氣平流動力學項，單位：W/m^2 (經潛熱轉換)，維度形狀：(lat, lon)。
+    """
+    assert CTL_omega.shape == CTL_q.shape == EXP_omega.shape == EXP_q.shape
+
+    # --- 將 pressure 轉為 Pa 陣列，直接作為 np.gradient 的坐標軸 ---
+    p_pa = pressure * 100.0 
+
+    # unit conversion for q
+    latent_heat = 2.5e6 # [J/kg]
+    CTL_q_energy = CTL_q * latent_heat
+    EXP_q_energy = EXP_q * latent_heat
+
+    # --- 使用非等間距的 p_pa 陣列進行垂直梯度計算 ---
+    # 當 np.gradient 的第二個參數傳入 1D array 時，它會自動依據該坐標計算非等間距差分
+    CTL_dqdp = np.gradient(CTL_q_energy, p_pa, axis=0) 
+    EXP_dqdp = np.gradient(EXP_q_energy, p_pa, axis=0)
+
+    thermodynamic_term = np.zeros_like(CTL_omega)
+    dynamic_term = np.zeros_like(CTL_omega)
+
+    for lev in range(0, CTL_omega.shape[0]):
+        thermodynamic_term[lev, :, :] = CTL_omega[lev, :, :] * EXP_dqdp[lev, :, :]
+        dynamic_term[lev, :, :] = CTL_dqdp[lev, :, :] * EXP_omega[lev, :, :]
+
+    integrated_thermodynamic_term = MassIntegrationAlongPressure(pressure, thermodynamic_term, pmin=pmin, pmax=pmax)
+    integrated_dynamic_term = MassIntegrationAlongPressure(pressure, dynamic_term, pmin=pmin, pmax=pmax)
+
+    return integrated_thermodynamic_term, integrated_dynamic_term
+
+
+def RelativeHumidity(T, Q, P):
+    """
+    利用溫度、比濕與氣壓計算相對濕度 (Relative Humidity, RH)。
+
+    Parameters
+    ----------
+    T : float 或 np.ndarray
+        溫度，單位：Kelvin (K)，維度形狀：與輸入相符（純量或任意陣列）。
+    Q : float 或 np.ndarray
+        比濕 (Specific Humidity)，單位：kg/kg，維度形狀：與輸入相符。
+    P : float 或 np.ndarray
+        氣壓 (Pressure)，單位：Pa，維度形狀：與輸入相符。
+
+    Returns
+    -------
+    rh : np.ndarray
+        相對濕度，單位：百分比 (%)，已被限制在 0-100 之間，維度形狀與輸入相同。
+    """
+    # 1. 轉為攝氏溫度
+    T_c = T - 273.15
+    
+    # 2. 計算飽和蒸氣壓 es (單位: Pa)
+    # 使用 Bolton (1980) 公式，精度高且適合大氣運算
+    es = 611.2 * np.exp((17.67 * T_c) / (T_c + 243.5))
+    
+    # 3. 計算混合比 w (mixing ratio)
+    w = Q / (1.0 - Q)
+    
+    # 4. 計算實際蒸氣壓 e (單位: Pa)
+    # epsilon (水氣與乾空氣分子量比) ≅ 0.622
+    epsilon = 0.622
+    e = (w * P) / (epsilon + w)
+    
+    # 5. 計算 RH
+    rh = (e / es) * 100.0
+    
+    # 限制 RH 在 0-100% 之間
+    rh = np.clip(rh, 0, 100)
+    
+    return rh.astype(np.float32)
+
+
+
+def VaporPressureDeficit(T, Q, P):
+    """
+    利用溫度、比濕與氣壓計算水氣壓差 (Vapor Pressure Deficit, VPD)。
+
+    Parameters
+    ----------
+    T : float 或 np.ndarray
+        溫度，單位：Kelvin (K)，維度形狀：與輸入相符。
+    Q : float 或 np.ndarray
+        比濕 (Specific Humidity)，單位：kg/kg，維度形狀：與輸入相符。
+    P : float 或 np.ndarray
+        氣壓 (Pressure)，單位：Pa，維度形狀：與輸入相符。
+
+    Returns
+    -------
+    vpd : np.ndarray
+        水氣壓差，單位：Pa，已確保不會出現負值，維度形狀與輸入相同。
+    """
+    # 1. 轉為攝氏溫度
+    T_c = T - 273.15
+    
+    # 2. 計算飽和蒸氣壓 es (單位: Pa)
+    # 使用 Bolton (1980) 公式，精度高且適合大氣運算
+    es = 611.2 * np.exp((17.67 * T_c) / (T_c + 243.5))
+    
+    # 3. 計算混合比 w (mixing ratio)
+    w = Q / (1.0 - Q)
+    
+    # 4. 計算實際蒸氣壓 e (單位: Pa)
+    # epsilon (水氣與乾空氣分子量比) ≅ 0.622
+    epsilon = 0.622
+    e = (w * P) / (epsilon + w)
+    
+    # 5. 計算 VPD
+    vpd = np.maximum(0, es - e)  # 確保不會出現負值
+    
+    return vpd.astype(np.float32)

pyqihou-0.1.0/pyqihou.egg-info/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: pyqihou
+Version: 0.1.0
+Summary: Python Package for Climate Analysis
+Author-email: VVVictorZhou <ahme02147483647a@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/VVVICTORZHOU/
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.19.5
+Requires-Dist: scipy>=1.5.4
+Requires-Dist: windspharm>=1.7.0
+Requires-Dist: xarray>=0.16.2
+
+## How to install the `pyqihou` package:
+
+- Method 1: `npm install pyqihou`
+
+- Method 2: `pip install pyqihou`
+
+
+## Functions in the `pyqihou` package:
+### `water.py`
+
+- `MassIntegrationAlongPressure`: 沿著垂直氣壓層執行大氣變數的質量積分。   
+- `HorizontalMoistureAdvection`: 計算水平水氣平流的熱力學與動力學分解項，並進行氣壓層垂直積分。   
+- `VerticalMoistureAdvection`: 計算垂直水氣平流的熱力學與動力學分解項，並進行氣壓層垂直積分。   
+- `RelativeHumidity`: 依據溫度、比濕與氣壓計算大氣相對濕度百分比。   
+- `VaporPressureDeficit`: 依據溫度、比濕與氣壓計算水氣壓差 (VPD)。   
+
+### `energy.py`
+
+- `MixedLayerHeatBudget`: 計算混合層熱平衡的各項輻射、熱通量與物理分解項。   
+- `NetEnergyInput`: 計算大氣與地表的淨能量輸入 (NEI)。   
+- `EnergyFluxPotential`: 計算能量通量位勢 (EFP) 並自動處理標準網格內插與還原。   
+- `MeridionalMassStreamFunction`: 計算經向質量經流函數 (MSF)。   
+- `ZonalMassStreamFunction`: 計算緯向質量經流函數 (MSF)。  
+- `HorizontalTN01WaveActivityFlux`: 計算幾何校正版的 Takaya-Nakamura (2001) 水平波活動通量與其散度。   
+
+
+
+

pyqihou-0.1.0/pyqihou.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+pyqihou/__init__.py
+pyqihou/energy.py
+pyqihou/statistic.py
+pyqihou/water.py
+pyqihou.egg-info/PKG-INFO
+pyqihou.egg-info/SOURCES.txt
+pyqihou.egg-info/dependency_links.txt
+pyqihou.egg-info/requires.txt
+pyqihou.egg-info/top_level.txt

pyqihou-0.1.0/pyqihou.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pyqihou-0.1.0/pyqihou.egg-info/requires.txt

@@ -0,0 +1,4 @@
+numpy>=1.19.5
+scipy>=1.5.4
+windspharm>=1.7.0
+xarray>=0.16.2

pyqihou-0.1.0/pyqihou.egg-info/top_level.txt

@@ -0,0 +1 @@
+pyqihou

pyqihou-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+