wrfrun 0.1.9__py3-none-any.whl → 0.3.0__py3-none-any.whl

wrfrun/model/wrf/scheme.py

@@ -1,9 +1,43 @@
 """
-This file contains function to determine schemes for WRF
+wrfrun.model.wrf.scheme
+#######################
+
+This file contains dataclasses to determine schemes for WRF.
+
+.. autosummary::
+    :toctree: generated/
+
+    SchemeCumulus
+    SchemeLandSurfaceModel
+    SchemeLongWave
+    SchemePBL
+    SchemeShortWave
+    SchemeSurfaceLayer
+    SchemeMicrophysics
+
+How to use
+**********
+
+All dataclasses have class method ``get_scheme_id``, which accepts the name of scheme and return the corresponding index.
+You can also use attributes of dataclasses.
+
+**For example**
+
+.. code-block:: python
+    :caption: main.py
+
+    from wrfrun.model.wrf import SchemeLongWave
+
+    # 1. Use function get_scheme_id.
+    scheme_id = SchemeLongWave.get_scheme_id("rrtmg")
+    # 2. Access attributes.
+    scheme_id = SchemeLongWave.RRTMG
+
 """
+
 from dataclasses import dataclass
 
-from wrfrun.utils import logger
+from wrfrun.log import logger
 
 
 @dataclass()
@@ -11,6 +45,7 @@ class SchemeLongWave:
     """
     Long wave physics schemes.
     """
+
     OFF = 0
     RRTM = 1
     CAM = 3
@@ -18,16 +53,19 @@ class SchemeLongWave:
     NEW_GODDARD = 5
     FLG = 7
     RRTMG_K = 14
-    FAST_RRTMG = 24     # for GPU and MIC
+    FAST_RRTMG = 24  # for GPU and MIC
     HELD_SUAREZ = 31
     GFDL = 99
 
     @classmethod
     def get_scheme_id(cls, key: str = "rrtm"):
-        """Get the corresponding integer label for long wave radiation scheme
+        """
+        Get the corresponding integer label for long wave radiation scheme.
+
+        Reference link: `longwave-radiation-schemes <https://www2.mmm.ucar.edu/wrf/users/wrf_users_guide/build/html/physics.html#longwave-radiation-schemes>`_.
 
-        Args:
-            key (str, optional): Name of long wave radiation scheme. Defaults to "rrtm".
+        :param key: Name of long wave radiation scheme. Defaults to "rrtm".
+        :type key: str
         """
         # Here is the map of scheme name and integer label in WRF
         # Reference link: https://www2.mmm.ucar.edu/wrf/users/wrf_users_guide/build/html/physics.html#longwave-radiation-schemes
@@ -41,14 +79,12 @@ class SchemeLongWave:
             "rrtmg-k": cls.RRTMG_K,
             "fast-rrtmg": cls.FAST_RRTMG,
             "held-suarez": cls.HELD_SUAREZ,
-            "gfdl": cls.GFDL
+            "gfdl": cls.GFDL,
         }
 
         # check if key is in map
         if key not in integer_label_map:
-            logger.error(
-                f"Key error: {key}. Valid key: {list(integer_label_map.keys())}"
-            )
+            logger.error(f"Key error: {key}. Valid key: {list(integer_label_map.keys())}")
             raise KeyError
 
         return integer_label_map[key]
@@ -59,6 +95,7 @@ class SchemeShortWave:
     """
     Short wave physics schemes.
     """
+
     OFF = 0
     DUDHIA = 1
     GODDARD = 2
@@ -73,10 +110,13 @@ class SchemeShortWave:
 
     @classmethod
     def get_scheme_id(cls, key: str = "rrtmg"):
-        """Get corresponding integer label for short wave radiation scheme
+        """
+        Get corresponding integer label for short wave radiation scheme.
 
-        Args:
-            key (str, optional): Name of short wave radiation scheme. Defaults to "rrtmg".
+        Reference link: `shortwave-radiation-schemes <https://www2.mmm.ucar.edu/wrf/users/wrf_users_guide/build/html/physics.html#shortwave-radiation-schemes>`_.
+
+        :param key: Name of short wave radiation scheme. Defaults to "rrtmg".
+        :type key: str
         """
         # Here is the map of scheme name and integer label in WRF
         # Reference link: https://www2.mmm.ucar.edu/wrf/users/wrf_users_guide/build/html/physics.html#shortwave-radiation-schemes
@@ -91,14 +131,12 @@ class SchemeShortWave:
             "rrtmg-k": cls.RRTMG_K,
             "fast-rrtmg": cls.FAST_RRTMG,
             "earth-hs-force": cls.EARTH_HELD_SUAREZ_FORCING,
-            "gfdl": cls.GODDARD
+            "gfdl": cls.GODDARD,
         }
 
         # check if key is in map
         if key not in integer_label_map:
-            logger.error(
-                f"Key error: {key}. Valid key: {list(integer_label_map.keys())}"
-            )
+            logger.error(f"Key error: {key}. Valid key: {list(integer_label_map.keys())}")
             raise KeyError
 
         return integer_label_map[key]
@@ -109,6 +147,7 @@ class SchemeCumulus:
     """
     Cumulus parameterization schemes.
     """
+
     OFF = 0
     KAIN_FRITSCH = 1
     BMJ = 2
@@ -127,10 +166,13 @@ class SchemeCumulus:
 
     @classmethod
     def get_scheme_id(cls, key: str = "kf"):
-        """Get corresponding integer label for cumulus parameterization scheme
+        """
+        Get corresponding integer label for cumulus parameterization scheme.
+
+        Reference link: `cumulus-parameterization <https://www2.mmm.ucar.edu/wrf/users/wrf_users_guide/build/html/physics.html#cumulus-parameterization>`_.
 
-        Args:
-            key (str, optional): Name of cumulus parameterization scheme. Defaults to "kf".
+        :param key: Name of cumulus parameterization scheme. Defaults to "kf".
+        :type key: str
         """
         # Here is the map of scheme name and integer label in WRF
         # Reference link: https://www2.mmm.ucar.edu/wrf/users/wrf_users_guide/build/html/physics.html#cumulus-parameterization
@@ -149,14 +191,12 @@ class SchemeCumulus:
             "nt": cls.NEW_TIEDTKE,
             "gd": cls.GRELL_DEVENYI,
             "nsas": cls.NSAS,
-            "old-kf": cls.OLD_KF
+            "old-kf": cls.OLD_KF,
         }
 
         # check if key is in map
         if key not in integer_label_map:
-            logger.error(
-                f"Key error: {key}. Valid key: {list(integer_label_map.keys())}"
-            )
+            logger.error(f"Key error: {key}. Valid key: {list(integer_label_map.keys())}")
             raise KeyError
 
         return integer_label_map[key]
@@ -167,6 +207,7 @@ class SchemePBL:
     """
     PBL physics schemes.
     """
+
     OFF = 0
     YSU = 1
     MYJ = 2
@@ -185,10 +226,13 @@ class SchemePBL:
 
     @classmethod
     def get_scheme_id(cls, key: str = "ysu"):
-        """Get corresponding integer label for PBL scheme
+        """
+        Get corresponding integer label for PBL scheme.
 
-        Args:
-            key (str, optional): Name of PBL scheme. Defaults to "ysu".
+        Reference link: `pbl-scheme-options <https://www2.mmm.ucar.edu/wrf/users/wrf_users_guide/build/html/physics.html#pbl-scheme-options>`_.
+
+        :param key: Name of PBL scheme. Defaults to "ysu".
+        :type key: str
         """
         # Here is the map of scheme name and integer label in WRF
         # Reference link: https://www2.mmm.ucar.edu/wrf/users/wrf_users_guide/build/html/physics.html#pbl-scheme-options
@@ -207,14 +251,12 @@ class SchemePBL:
             "gbm": cls.GBM,
             "eeps": cls.EEPS,
             "keps": cls.KEPS,
-            "mrf": cls.MRF
+            "mrf": cls.MRF,
         }
 
         # check if key is in map
         if key not in integer_label_map:
-            logger.error(
-                f"Key error: {key}. Valid key: {list(integer_label_map.keys())}"
-            )
+            logger.error(f"Key error: {key}. Valid key: {list(integer_label_map.keys())}")
             raise KeyError
 
         return integer_label_map[key]
@@ -225,6 +267,7 @@ class SchemeLandSurfaceModel:
     """
     Land surface model physics schemes.
     """
+
     OFF = 0
     SLAB = 1
     NOAH = 2
@@ -236,10 +279,13 @@ class SchemeLandSurfaceModel:
 
     @classmethod
     def get_scheme_id(cls, key: str = "noah"):
-        """Get corresponding integer label for land surface scheme
+        """
+        Get corresponding integer label for land surface scheme.
+
+        Reference link: `lsm-scheme-details-and-references <https://www2.mmm.ucar.edu/wrf/users/wrf_users_guide/build/html/physics.html#lsm-scheme-details-and-references>`_.
 
-        Args:
-            key (str, optional): Name of land surface scheme. Defaults to "noah".
+        :param key: Name of land surface scheme. Defaults to "noah".
+        :type key: str
         """
         # Here is the map of scheme name and integer label in WRF
         # Reference link: https://www2.mmm.ucar.edu/wrf/users/wrf_users_guide/build/html/physics.html#lsm-scheme-details-and-references
@@ -251,14 +297,12 @@ class SchemeLandSurfaceModel:
             "noah-mp": cls.NOAH_MP,
             "clm4": cls.CLM4,
             "px": cls.PLEIM_XIU,
-            "ssib": cls.SSIB
+            "ssib": cls.SSIB,
         }
 
         # check if key is in map
         if key not in integer_label_map:
-            logger.error(
-                f"Key error: {key}. Valid key: {list(integer_label_map.keys())}"
-            )
+            logger.error(f"Key error: {key}. Valid key: {list(integer_label_map.keys())}")
             raise KeyError
 
         return integer_label_map[key]
@@ -269,6 +313,7 @@ class SchemeSurfaceLayer:
     """
     Surface layer physics schemes.
     """
+
     OFF = 0
     MM5 = 1
     MONIN_OBUKHOV = 2
@@ -280,10 +325,13 @@ class SchemeSurfaceLayer:
 
     @classmethod
     def get_scheme_id(cls, key: str = "mm5"):
-        """Get corresponding integer label for surface layer scheme
+        """
+        Get corresponding integer label for surface layer scheme.
 
-        Args:
-            key (str, optional): Name of surface layer scheme. Defaults to "mo".
+        Reference link: `sf_sfclay_physics <https://www2.mmm.ucar.edu/wrf/users/wrf_users_guide/build/html/namelist_variables.html#:~:text=this%20Users%E2%80%99%20Guide.-,sf_sfclay_physics,-surface%20layer%20physics>`_.
+
+        :param key: Name of surface layer scheme. Defaults to "mo".
+        :type key: str
         """
         # Here is the map of scheme name and integer label in WRF
         # Reference link: https://www2.mmm.ucar.edu/wrf/users/wrf_users_guide/build/html/namelist_variables.html
@@ -295,14 +343,12 @@ class SchemeSurfaceLayer:
             "mynn": cls.MYNN,
             "px": cls.PLEIM_XIU,
             "temf": cls.TEMF,
-            "old-mm5": cls.OLD_MM5
+            "old-mm5": cls.OLD_MM5,
         }
 
         # check if key is in map
         if key not in integer_label_map:
-            logger.error(
-                f"Key error: {key}. Valid key: {list(integer_label_map.keys())}"
-            )
+            logger.error(f"Key error: {key}. Valid key: {list(integer_label_map.keys())}")
             raise KeyError
 
         return integer_label_map[key]
@@ -313,6 +359,7 @@ class SchemeMicrophysics:
     """
     Microphysics schemes.
     """
+
     OFF = 0
     KESSLER = 1
     PURDUE_LIN = 2
@@ -345,10 +392,13 @@ class SchemeMicrophysics:
 
     @classmethod
     def get_scheme_id(cls, key: str = "lin"):
-        """Get corresponding integer label for microphysics scheme
+        """
+        Get corresponding integer label for microphysics scheme.
+
+        Reference link: `physics <https://www2.mmm.ucar.edu/wrf/users/wrf_users_guide/build/html/namelist_variables.html#physics>`_.
 
-        Args:
-            key (str, optional): Name of microphysics scheme. Defaults to "PURDUE_LIN".
+        :param key: Name of microphysics scheme. Defaults to "PURDUE_LIN".
+        :type key: str
         """
         # Here is the map of scheme name and integer label in WRF
         # Reference link: https://www2.mmm.ucar.edu/wrf/users/wrf_users_guide/build/html/namelist_variables.html
@@ -384,12 +434,18 @@ class SchemeMicrophysics:
 
         # check if key is in map
         if key not in integer_label_map:
-            logger.error(
-                f"Key error: {key}. Valid key: {list(integer_label_map.keys())}"
-            )
+            logger.error(f"Key error: {key}. Valid key: {list(integer_label_map.keys())}")
             raise KeyError
 
         return integer_label_map[key]
 
 
-__all__ = ["SchemeCumulus", "SchemeLandSurfaceModel", "SchemeLongWave", "SchemePBL", "SchemeShortWave", "SchemeSurfaceLayer", "SchemeMicrophysics"]
+__all__ = [
+    "SchemeCumulus",
+    "SchemeLandSurfaceModel",
+    "SchemeLongWave",
+    "SchemePBL",
+    "SchemeShortWave",
+    "SchemeSurfaceLayer",
+    "SchemeMicrophysics",
+]

wrfrun/model/wrf/utils.py

@@ -1,21 +1,35 @@
+"""
+wrfrun.model.wrf.utils
+######################
+
+Utility functions used by wrf model part.
+
+.. autosummary::
+    :toctree: generated/
+
+    get_metgrid_levels
+    reconcile_namelist_metgrid
+    process_after_ndown
+"""
+
 from os import listdir
 from os.path import exists
 from typing import Dict
 
 from xarray import open_dataset
 
-from wrfrun import WRFRUNConfig
-from wrfrun.utils import logger
+from wrfrun.core import WRFRUN
+from wrfrun.log import logger
 
 
 def get_metgrid_levels(nc_file: str) -> Dict[str, int]:
-    """Read metgrid output file and get metgrid levels, land cat and metgrid soil levels
-
-    Args:
-        nc_file (str): Output nc file path
+    """
+    Read metgrid output file and get metgrid levels, land cat and metgrid soil levels.
 
-    Returns:
-        Dict[str, int]: {num_metgrid_levels: number, num_land_cat: number, num_metgrid_soil_level: number}
+    :param nc_file: Output nc file path.
+    :type nc_file: str
+    :return: {num_metgrid_levels: number, num_land_cat: number, num_metgrid_soil_level: number}
+    :rtype: Dict[str, int]
     """
     # check file
     if not exists(nc_file):
@@ -30,11 +44,7 @@ def get_metgrid_levels(nc_file: str) -> Dict[str, int]:
     num_land_cat = dataset.attrs["NUM_LAND_CAT"]
     num_metgrid_soil_levels = dataset.attrs["NUM_METGRID_SOIL_LEVELS"]
 
-    return dict(
-        num_metgrid_levels=num_metgrid_levels,
-        num_land_cat=num_land_cat,
-        num_metgrid_soil_levels=num_metgrid_soil_levels
-    )
+    return dict(num_metgrid_levels=num_metgrid_levels, num_land_cat=num_land_cat, num_metgrid_soil_levels=num_metgrid_soil_levels)
 
 
 def reconcile_namelist_metgrid(metgrid_path: str):
@@ -48,7 +58,7 @@ def reconcile_namelist_metgrid(metgrid_path: str):
     :return:
     :rtype:
     """
-    logger.info(f"Checking values in WRF namelist and metgrid output ...")
+    logger.info("Checking values in WRF namelist and metgrid output ...")
     metgrid_output_name = [x for x in listdir(metgrid_path) if x.endswith(".nc")]
     metgrid_output_name.sort()
     metgrid_output_name = metgrid_output_name[0]
@@ -60,23 +70,21 @@ def reconcile_namelist_metgrid(metgrid_path: str):
             "num_metgrid_levels": metgrid_levels["num_metgrid_levels"],
             "num_metgrid_soil_levels": metgrid_levels["num_metgrid_soil_levels"],
         },
-        "physics": {
-            "num_land_cat": metgrid_levels["num_land_cat"]
-        }
+        "physics": {"num_land_cat": metgrid_levels["num_land_cat"]},
     }
 
-    WRFRUNConfig.update_namelist(update_values, "wrf")
+    WRFRUN.config.update_namelist(update_values, "wrf")
 
 
 def process_after_ndown():
     """
     After running ndown.exe, namelist settings are supposed to be changed,
     so WRF can simulate a higher resolution domain according to `WRF User's Guide <https://www2.mmm.ucar.edu/wrf/users/wrf_users_guide/build/html/running_wrf.html#wrf-nesting>`_.
-    `wrfrun` provide this function to help you change these settings which have multiple values for each domain.
-    The first value will be removed to ensure the value of higher resolution domain is the first value.
 
-    :return:
+    ``wrfrun`` provide this function to help you change these settings which have multiple values for each domain.
+    The first value will be removed to ensure the value of higher resolution domain is the first value.
     """
+    WRFRUNConfig = WRFRUN.config
     namelist_data = WRFRUNConfig.get_namelist("wrf")
 
     for section in namelist_data:
@@ -84,11 +92,18 @@ def process_after_ndown():
             continue
 
         for key in namelist_data[section]:
-            if key in ["grid_id", "parent_id", "i_parent_start", "j_parent_start", "parent_grid_ratio", "parent_time_step_ratio", "eta_levels"]:
+            if key in [
+                "grid_id",
+                "parent_id",
+                "i_parent_start",
+                "j_parent_start",
+                "parent_grid_ratio",
+                "parent_time_step_ratio",
+                "eta_levels",
+            ]:
                 continue
 
             if isinstance(namelist_data[section][key], list):
-
                 if len(namelist_data[section][key]) > 1:
                     namelist_data[section][key] = namelist_data[section][key][1:]
 
@@ -99,7 +114,7 @@ def process_after_ndown():
 
     WRFRUNConfig.update_namelist(namelist_data, "wrf")
 
-    logger.info(f"Update namelist after running ndown.exe")
+    logger.info("Update namelist after running ndown.exe")
 
 
 __all__ = ["reconcile_namelist_metgrid", "get_metgrid_levels", "process_after_ndown"]

wrfrun/model/wrf/vtable.py

@@ -1,8 +1,34 @@
-from dataclasses import dataclass
+"""
+wrfrun.model.wrf.vtable
+#######################
+
+Dataclasses to represents VTable files in WRF.
+
+.. autosummary::
+    :toctree: generated/
+
+    VtableFiles
+
+How to use
+**********
+
+Attributes of :class:`VtableFiles` is a ``wrfrun`` URI, parse it will get the real path of VTable files.
+
+**For example**
+
+.. code-block:: python
+    :caption: main.py
 
-from wrfrun.core import WRFRUNConfig
-from wrfrun.workspace.wrf import WORKSPACE_MODEL_WPS
+    from wrfrun.core import WRFRUN
+    from wrfrun.model.wrf import VtableFiles
 
+    vtable_real_file_path = WRFRUN.config.parse_resource_uri(VtableFiles.ERA_PL)
+"""
+
+from dataclasses import dataclass
+
+from wrfrun.core import WRFRUN, WRFRunConfig
+from wrfrun.workspace.wrf import get_wrf_workspace_path
 
 VTABLE_URI = ":WRFRUN_VTABLE:"
 
@@ -11,8 +37,13 @@ VTABLE_URI = ":WRFRUN_VTABLE:"
 class VtableFiles:
     """
     Represent WPS Vtable files (v4.5).
-    With the ":/" we can tell from user custom Vtable files.
+
+    **NOTE**
+
+    This class doesn't have method to check if the VTable file exists.
+    User need to check the VTable file when use it.
     """
+
     AFWAICE = f"{VTABLE_URI}/Vtable.AFWAICE"
     AGRMETSNOW = f"{VTABLE_URI}/Vtable.AGRMETSNOW"
     AGRMETSOIL = f"{VTABLE_URI}/Vtable.AGRMETSOIL"
@@ -58,9 +89,13 @@ class VtableFiles:
     UKMO_NO_HEIGHTS = f"{VTABLE_URI}/Vtable.UKMO_no_heights"
 
 
-# register uri
-if not WRFRUNConfig.check_resource_uri(VTABLE_URI):
-    WRFRUNConfig.register_resource_uri(VTABLE_URI, f"{WORKSPACE_MODEL_WPS}/ungrib/Variable_Tables")
+def _register_vtable_uri(wrfrun_config: WRFRunConfig):
+    # register uri
+    if not wrfrun_config.check_resource_uri(VTABLE_URI):
+        wrfrun_config.register_resource_uri(VTABLE_URI, f"{get_wrf_workspace_path('wps')}/ungrib/Variable_Tables")
+
+
+WRFRUN.set_config_register_func(_register_vtable_uri)
 
 
 __all__ = ["VtableFiles"]

wrfrun/plot/__init__.py

@@ -1 +1,21 @@
+"""
+wrfrun.plot
+###########
+
+Modules to plot model outputs.
+
+Submodules
+**********
+
+========================================= ==========================================
+:doc:`wps </api/plot.wps>`                Functions to plot WPS outputs.
+========================================= ==========================================
+
+.. toctree::
+    :maxdepth: 1
+    :hidden:
+
+    wps <plot.wps>
+"""
+
 from .wps import *