wrfrun 0.1.7__py3-none-any.whl → 0.1.8__py3-none-any.whl

wrfrun/core/error.py

@@ -1,80 +1,110 @@
+"""
+wrfrun.core.error
+#################
+
+This module defines all exceptions used in ``wrfrun``.
+
+.. autosummary::
+    :toctree: generated/
+
+    WRFRunBasicError
+    ConfigError
+    WRFRunContextError
+    CommandError
+    OutputFileError
+    ResourceURIError
+    InputFileError
+    NamelistError
+    NamelistIDError
+    ExecRegisterError
+    GetExecClassError
+    ModelNameError
+"""
+
+
 class WRFRunBasicError(Exception):
     """
-    Basic error type.
+    Basic exception class of ``wrfrun``. New exception **MUST** inherit this class.
     """
     pass
 
 
 class ConfigError(WRFRunBasicError):
     """
-    Config cannot be used error.
+    Exception indicates the config of ``wrfrun`` or NWP model can't be used.
     """
     pass
 
 
 class WRFRunContextError(WRFRunBasicError):
     """
-    Need to enter wrfrun context.
+    Exception indicates ``wrfrun`` is running out of the ``wrfrun`` context.
     """
     pass
 
 
 class CommandError(WRFRunBasicError):
     """
-    The command is wrong.
+    Exception indicates the command of ``Executable`` can't be executed successfully.
     """
     pass
 
 
-class LoadConfigError(WRFRunBasicError):
+class OutputFileError(WRFRunBasicError):
     """
-    Failed to load config.
+    Exception indicates ``wrfrun`` can't find any output files with the given rules.
     """
     pass
 
 
-class OutputFileError(WRFRunBasicError):
+class ResourceURIError(WRFRunBasicError):
     """
-    No output found.
+    Exception indicates ``wrfrun`` can't parse the URI.
     """
     pass
 
 
-class ResourceURIError(WRFRunBasicError):
+class InputFileError(WRFRunBasicError):
     """
-    Error about resource namespace.
+    Exception indicates ``wrfrun`` can't find specified input files.
     """
     pass
 
 
-class InputFileError(WRFRunBasicError):
+class NamelistError(WRFRunBasicError):
     """
-    Input file error.
+    Exception indicates ``wrfrun`` can't find the namelist user want to use.
     """
     pass
 
 
-class NamelistError(WRFRunBasicError):
+class NamelistIDError(WRFRunBasicError):
     """
-    Error about namelist.
+    Exception indicates ``wrfrun`` can't register the specified namelist id.
     """
     pass
 
 
 class ExecRegisterError(WRFRunBasicError):
+    """
+    Exception indicates ``wrfrun`` can't register the specified ``Executable``.
+    """
     pass
 
 
 class GetExecClassError(WRFRunBasicError):
+    """
+    Exception indicates ``wrfrun`` can't find the specified ``Executable``.
+    """
     pass
 
 
 class ModelNameError(WRFRunBasicError):
     """
-    Name of the model isn't found in the config file.
+    Exception indicates ``wrfrun`` can't find config of the specified NWP model in the config file.
     """
     pass
 
 
-__all__ = ["WRFRunBasicError", "ConfigError", "WRFRunContextError", "CommandError", "LoadConfigError", "OutputFileError", "ResourceURIError", "InputFileError",
-           "NamelistError", "ExecRegisterError", "GetExecClassError", "ModelNameError"]
+__all__ = ["WRFRunBasicError", "ConfigError", "WRFRunContextError", "CommandError", "OutputFileError", "ResourceURIError", "InputFileError",
+           "NamelistError", "ExecRegisterError", "GetExecClassError", "ModelNameError", "NamelistIDError"]

wrfrun/core/replay.py

@@ -1,6 +1,29 @@
+"""
+wrfrun.core.replay
+##################
+
+This module provides methods to read config from ``.replay`` file and reproduce the simulation.
+
+.. autosummary::
+    :toctree: generated/
+
+    WRFRunExecutableRegisterCenter
+    replay_config_generator
+
+WRFRUNExecDB
+************
+
+In order to load ``Executable`` correctly based on the stored ``name`` in ``.replay`` files,
+``wrfrun`` uses ``WRFRUNExecDB``, which is the instance of :class:`WRFRunExecutableRegisterCenter`,
+to records all ``Executable`` classes and corresponding ``name``.
+When ``wrfrun`` replays the simulation, it gets the right ``Executable`` from ``WRFRUNExecDB`` and executes it.
+"""
+
+from collections.abc import Generator
 from json import loads
 from os.path import exists
 from shutil import unpack_archive
+from typing import Any
 
 from .base import ExecutableBase, ExecutableConfig
 from .config import WRFRUNConfig
@@ -12,7 +35,8 @@ WRFRUN_REPLAY_URI = ":WRFRUN_REPLAY:"
 
 class WRFRunExecutableRegisterCenter:
     """
-    Record all executable class.
+    This class provides the method to records ``Executable``'s class with a unique ``name``.
+    Later you can get the class with the ``name``.
     """
     _instance = None
     _initialized = False
@@ -31,64 +55,73 @@ class WRFRunExecutableRegisterCenter:
 
         return cls._instance
 
-    def register_exec(self, unique_iq: str, cls: type):
+    def register_exec(self, name: str, cls: type):
         """
-        Register an executable class.
+        Register an ``Executable``'s class with a unique ``name``.
+
+        If the ``name`` has been used, :class:`ExecRegisterError` will be raised.
 
-        :param unique_iq: Unique ID.
-        :type unique_iq: str
-        :param cls: Class.
+        :param name: ``Executable``'s unique name.
+        :type name: str
+        :param cls: ``Executable``'s class.
         :type cls: type
-        :return:
-        :rtype:
         """
-        if unique_iq in self._exec_db:
-            logger.error(f"'{unique_iq}' has been registered.")
-            raise ExecRegisterError(f"'{unique_iq}' has been registered.")
+        if name in self._exec_db:
+            logger.error(f"'{name}' has been registered.")
+            raise ExecRegisterError(f"'{name}' has been registered.")
 
-        self._exec_db[unique_iq] = cls
+        self._exec_db[name] = cls
 
-    def is_registered(self, unique_id: str) -> bool:
+    def is_registered(self, name: str) -> bool:
         """
-        Check if an executable class has been registered.
+        Check if an ``Executable``'s class has been registered.
 
-        :param unique_id: Unique ID.
-        :type unique_id: str
+        :param name: ``Executable``'s unique name.
+        :type name: str
         :return: True or False.
         :rtype: bool
         """
-        if unique_id in self._exec_db:
+        if name in self._exec_db:
             return True
         else:
             return False
 
-    def get_cls(self, unique_id: str) -> type:
+    def get_cls(self, name: str) -> type:
         """
-        Get a registered executable class.
+        Get an ``Executable``'s class with the ``name``.
+
+        If the ``name`` can't be found, :class:`GetExecClassError` will be raised.
 
-        :param unique_id: Unique ID.
-        :type unique_id: str
-        :return: Executable class.
+        :param name: ``Executable``'s unique name.
+        :type name: str
+        :return: ``Executable``'s class.
         :rtype: type
         """
-        if unique_id not in self._exec_db:
-            logger.error(f"Executable class '{unique_id}' not found.")
-            raise GetExecClassError(f"Executable class '{unique_id}' not found.")
+        if name not in self._exec_db:
+            logger.error(f"Executable class '{name}' not found.")
+            raise GetExecClassError(f"Executable class '{name}' not found.")
 
-        return self._exec_db[unique_id]
+        return self._exec_db[name]
 
 
 WRFRUNExecDB = WRFRunExecutableRegisterCenter()
 
 
-def replay_config_generator(replay_config_file: str):
+def replay_config_generator(replay_config_file: str) -> Generator[tuple[str, ExecutableBase], Any, None]:
     """
-    Replay the simulations.
+    This method can read the ``.replay`` file and returns a generator which yields ``Executable`` and their names.
+    If this method doesn't find ``config.json`` in the ``.replay`` file, ``FileNotFoundError`` will be raised.
+
+    The ``Executable`` you get from the generator has been initialized so you can execute it directly.
+
+    >>> replay_file = "./example.replay"
+    >>> for name, _exec in replay_config_generator(replay_file):
+    >>>     _exec.replay()
 
-    :param replay_config_file: Replay file path.
+    :param replay_config_file: Path of the ``.replay`` file.
     :type replay_config_file: str
-    :return:
-    :rtype:
+    :return: A generator that yields: ``(name, Executable)``
+    :rtype: Generator
     """
     logger.info(f"Loading replay resources from: {replay_config_file}")
     work_path = WRFRUNConfig.parse_resource_uri(WRFRUNConfig.WRFRUN_REPLAY_WORK_PATH)

wrfrun/core/server.py

@@ -1,7 +1,24 @@
+"""
+wrfrun.core.server
+##################
+
+Currently, ``wrfrun`` provides the method to reads log file of WRF and calculates simulation progress.
+In order to report the progress to user, ``wrfrun`` provides :class:`WRFRunServer` to set up a socket server.
+
+.. autosummary::
+    :toctree: generated/
+
+    get_wrf_simulated_seconds
+    WRFRunServer
+    WRFRunServerHandler
+    stop_server
+"""
+
 import socket
 import socketserver
 import subprocess
 from datetime import datetime
+from json import dumps
 from time import time
 from typing import Tuple, Optional
 
@@ -14,13 +31,13 @@ WRFRUN_SERVER_THREAD = None
 
 def get_wrf_simulated_seconds(start_datetime: datetime, log_file_path: Optional[str] = None) -> int:
     """
-    Get how many seconds wrf has integrated.
+    Read the latest line of WRF's log file and calculate how many seconds WRF has integrated.
 
     :param start_datetime: WRF start datetime.
     :type start_datetime: datetime
     :param log_file_path: Absolute path of the log file to be parsed.
     :type log_file_path: str
-    :return: Seconds.
+    :return: Integrated seconds. If this method fails to calculate the time, the returned value is ``-1``.
     :rtype: int
     """
     # use linux cmd to get the latest line of wrf log files
@@ -34,7 +51,6 @@ def get_wrf_simulated_seconds(start_datetime: datetime, log_file_path: Optional[
 
     time_string = log_text.split()[1]
 
-    seconds = -1
     try:
         current_datetime = datetime.strptime(time_string, "%Y-%m-%d_%H:%M:%S")
         # remove timezone info so we can calculate.
@@ -44,16 +60,56 @@ def get_wrf_simulated_seconds(start_datetime: datetime, log_file_path: Optional[
     except ValueError:
         seconds = -1
 
-    finally:
-        return seconds
+    return seconds
 
 
 class WRFRunServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
     """
     A socket server to report time usage.
+
+    If you want to use the socket server, you need to give four arguments: ``start_date``,
+    ``wrf_simulate_seconds``, ``socket_address_port`` and ``WRFRunServerHandler``.
+
+    >>> start_date = datetime(2021, 3, 25, 8)
+    >>> simulate_seconds = 60 * 60 * 72
+    >>> socket_address_port = ("0.0.0.0", 54321)
+    >>> _wrfrun_server = WRFRunServer(start_date, simulate_seconds, socket_address_port, WRFRunServerHandler)
+
+    Usually you don't need to create socket server manually, because :class:`WRFRun` will handle this.
+
+    .. py:attribute:: start_timestamp
+        :type: datetime
+
+        The time the socket server start.
+
+    .. py:attribute:: start_date
+        :type: datetime
+
+        The simulation's start date.
+
+    .. py:attribute:: wrf_simulate_seconds
+        :type: int
+
+        The total seconds the simulation will integrate.
+
+    .. py:attribute:: wrf_log_path
+        :type: str
+
+        Path of the log file the server will read.
     """
 
     def __init__(self, start_date: datetime, wrf_simulate_seconds: int, *args, **kwargs) -> None:
+        """
+
+        :param start_date: The simulation's start date.
+        :type start_date: datetime
+        :param wrf_simulate_seconds: The total seconds the simulation will integrate.
+        :type wrf_simulate_seconds: int
+        :param args: Other positional arguments passed to parent class.
+        :type args:
+        :param kwargs: Other keyword arguments passed to parent class.
+        :type kwargs:
+        """
         super().__init__(*args, **kwargs)
 
         # record the time the server starts
@@ -72,7 +128,7 @@ class WRFRunServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
 
     def server_bind(self):
         """
-        Bind address and port.
+        Bind and listen on the address and port.
         """
         # reuse address and port to prevent the error `Address already in use`
         self.socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
@@ -101,7 +157,6 @@ class WRFRunServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
 class WRFRunServerHandler(socketserver.StreamRequestHandler):
     """
     Socket server handler.
-
     """
     def __init__(self, request, client_address, server: WRFRunServer) -> None:
         super().__init__(request, client_address, server)
@@ -110,10 +165,12 @@ class WRFRunServerHandler(socketserver.StreamRequestHandler):
         self.server: WRFRunServer = server
 
     def calculate_time_usage(self) -> str:
-        """Calculate time usage from server start (usually the time to run wrfrun)
+        """
+        Calculate the duration from the server's start time to the present,
+        which represents the time ``wrfrun`` has spent running the NWP model.
 
-        Returns:
-            str: Time usage in `"%H:%M:%S"`
+        :return: A time string in ``%H:%M:%S`` format.
+        :rtype: str
         """
         # get current timestamp
         current_timestamp = datetime.fromtimestamp(time())
@@ -137,10 +194,10 @@ class WRFRunServerHandler(socketserver.StreamRequestHandler):
 
     def calculate_progress(self) -> str:
         """
-        Calculate the simulation progress.
+        Read the log file and calculate the simulation progress.
 
-        :return:
-        :rtype:
+        :return: A JSON string with two keys: ``status`` and ``progress``.
+        :rtype: str
         """
         start_date, simulate_seconds = self.server.get_wrf_simulate_settings()
 
@@ -157,7 +214,7 @@ class WRFRunServerHandler(socketserver.StreamRequestHandler):
         if status == "":
             status = "*"
 
-        return f"{status}: {progress}%"
+        return dumps({"status": status, "progress": progress})
 
     def handle(self) -> None:
         """
@@ -186,11 +243,11 @@ class WRFRunServerHandler(socketserver.StreamRequestHandler):
 
 
 def stop_server(socket_ip: str, socket_port: int):
-    """Try to stop server.
+    """
+    Stop the socket server.
 
-    Args:
-        socket_ip (str): Server IP.
-        socket_port (int): Server Port.
+    :param socket_ip: Server address.
+    :param socket_port: Server port.
     """
     try:
         sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

wrfrun/data.py

@@ -6,12 +6,11 @@ from typing import Union, List, Tuple
 from pandas import date_range
 # from seafog import goos_sst_find_data
 
-import cdsapi
-
 from .core.config import WRFRUNConfig
 from .utils import logger
 
-CDS_CLIENT = cdsapi.Client()
+# lazy initialize
+CDS_CLIENT = None
 
 
 class ERA5CONFIG:
@@ -214,6 +213,8 @@ def find_era5_data(date: Union[List[str], List[datetime]], area: Tuple[int, int,
     Returns: data path
 
     """
+    global CDS_CLIENT
+
     # check variables and datasets
     if not _check_variables_and_datasets(variables, dataset):
         logger.error(
@@ -281,8 +282,12 @@ def find_era5_data(date: Union[List[str], List[datetime]], area: Tuple[int, int,
             exit(1)
 
     # download data
-    logger.info(
-        f"Downloading data to {save_path}, it may take several tens of minutes, please wait...")
+    logger.info(f"Downloading data to {save_path}, it may take several tens of minutes, please wait...")
+
+    if CDS_CLIENT is None:
+        import cdsapi
+        CDS_CLIENT = cdsapi.Client()
+
     CDS_CLIENT.retrieve(dataset, params_dict, save_path)
 
     return save_path

wrfrun/extension/__init__.py

@@ -1 +1,29 @@
+"""
+wrfrun.extension
+################
+
+Through extensions, developers can add more functionality to ``wrfrun``.
+``wrfrun`` now has the following extensions:
+
+========================================= ==========================================
+:doc:`goos_sst </api/extension.goos_sst>` Process NEAR-GOOS SST data.
+:doc:`littler </api/extension.littler>`   Process LITTLE_R observation data.
+========================================= ==========================================
+
+Other Submodules
+****************
+
+=================================== ==========================================
+:doc:`utils </api/extension.utils>` Utility methods can be used by extensions.
+=================================== ==========================================
+
+.. toctree::
+    :maxdepth: 1
+    :hidden:
+
+    goos_sst <extension.goos_sst>
+    littler <extension.littler>
+    utils <extension.utils>
+"""
+
 from .utils import *

wrfrun/extension/goos_sst/__init__.py

@@ -0,0 +1,67 @@
+"""
+wrfrun.extension.goos_sst
+#########################
+
+This extension can help you create a GRIB file from ERA5 skin temperature (SKT) data and NEAR-GOOS sea surface temperature (SST) data.
+
+================================================== =============================================
+:doc:`goos_sst </api/extension.goos_sst.goos_sst>` Core functionality submodule.
+:doc:`res </api/extension.goos_sst.res>`           Resource files provided by this extension.
+:doc:`utils </api/extension.goos_sst.utils>`       Utility submodule used by the core submodule.
+================================================== =============================================
+
+Important Note
+**************
+
+This extension relies on ``cfgrib`` package to create GRIB file.
+While GRIB write support is experimental in ``cfgrib``,
+this extension may **FAIL TO CREATE GRIB FILE**.
+
+How This Extension Works
+************************
+
+This extension provides a method which merges ERA5 reanalysis skin temperature (SKT) data and NEAR-GOOS SST data,
+and write new data to a GRIB file.
+
+How To Use This Extension
+*************************
+
+Prerequisite
+============
+
+You need to have the following packages installed, because they are not included in ``wrfrun``'s dependency:
+
+* cfgrib: Provide the method to create GRIB file.
+* seafog: Provide the method to download and read NEAR-GOOS SST data.
+
+And you also have downloaded an ERA5 reanalysis data (GRIB format) which contains SKT data.
+
+How To Use
+==========
+
+The code snap below shows you how to use this extension.
+
+.. code-block:: Python
+    :caption: main.py
+
+    from wrfrun.extension.goos_sst import merge_era5_goos_sst_grib
+
+
+    if __name__ == '__main__':
+        era5_data_path = "data/ear5-reanalysis-data.grib"
+        merge_era5_goos_sst_grib(era5_data_path, "data/near-goos-data.grib")
+        
+Please check :func:`core.merge_era5_goos_sst_grib` for more information.
+
+.. toctree::
+    :maxdepth: 1
+    :hidden:
+
+    core <extension.goos_sst.core>
+    res <extension.goos_sst.res>
+    utils <extension.goos_sst.utils>
+"""
+
+from .core import *
+from .res import *
+from .utils import *