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

wrfrun/core/core.py

@@ -0,0 +1,196 @@
+"""
+wrfrun.core.core
+################
+
+.. autosummary::
+    :toctree: generated/
+
+    WRFRUNProxy
+
+Global variable "WRFRUN"
+************************
+
+``WRFRUN`` is an instance of :class:`WRFRUNProxy`.
+It holds the instance of :class:`WRFRunConfig <wrfrun.core._config.WRFRunConfig>`,
+:class:`ExecutableDB <wrfrun.core._exec_db.ExecutableDB>`,
+and :class:`ExecutableRecorder <wrfrun.core._record.ExecutableRecorder>`.
+Through this global variable, other submodules of wrfrun and users can access attributes and methods of these classes.
+"""
+
+from typing import Callable, Literal
+
+from ..log import logger
+from ._config import WRFRunConfig
+from ._exec_db import ExecutableDB
+from ._record import ExecutableRecorder
+from .error import ConfigError
+
+
+class WRFRUNProxy:
+    """
+    Proxy class to access :class:`WRFRunConfig <wrfrun.core._config.WRFRunConfig>`,
+    :class:`ExecutableDB <wrfrun.core._exec_db.ExecutableDB>`,
+    and :class:`ExecutableRecorder <wrfrun.core._record.ExecutableRecorder>`.
+    """
+
+    def __init__(self):
+        """
+        Proxy class to access :class:`WRFRunConfig <wrfrun.core._config.WRFRunConfig>`,
+        :class:`ExecutableDB <wrfrun.core._exec_db.ExecutableDB>`,
+        and :class:`ExecutableRecorder <wrfrun.core._record.ExecutableRecorder>`.
+        """
+        self._config: WRFRunConfig | None = None
+        self._config_initialized = False
+        self._exec_db: ExecutableDB | None = None
+        self._exec_db_initialized = False
+        self._recorder: ExecutableRecorder | None = None
+        self._recorder_initialized = False
+
+        self._config_register_funcs: list[Callable[["WRFRunConfig"], None]] = []
+        self._exec_db_register_funcs: list[Callable[["ExecutableDB"], None]] = []
+
+        self.init_exec_db()
+
+    @property
+    def config(self) -> WRFRunConfig:
+        """
+        Access wrfrun config.
+
+        :return: wrfrun config.
+        :rtype: WRFRunConfig
+        """
+        if self._config is None:
+            logger.error("You haven't initialize `CONFIG` yet.")
+            raise ConfigError("You haven't initialize `CONFIG` yet.")
+        return self._config
+
+    @property
+    def ExecDB(self) -> ExecutableDB:
+        """
+        Access Executable DB.
+
+        :return: Executable DB.
+        :rtype: ExecutableDB
+        """
+        if self._exec_db is None:
+            logger.error("You haven't initialize `ExecDB` yet.")
+            raise ConfigError("You haven't initialize `ExecDB` yet.")
+        return self._exec_db
+
+    @property
+    def record(self) -> ExecutableRecorder:
+        """
+        Access simulation recorder.
+
+        :return: Simulation recorder.
+        :rtype: ExecutableRecorder
+        """
+        if self._recorder is None:
+            logger.error("You haven't initialize simulation recorder yet.")
+            raise ConfigError("You haven't initialize simulation recorder yet.")
+        return self._recorder
+
+    def set_exec_db(self, exec_db: ExecutableDB):
+        """
+        Initialize Executable DB.
+
+        :param exec_db: Executables DB.
+        :type exec_db: ExecutableDB
+        """
+        self._exec_db = exec_db
+        self._exec_db_initialized = True
+
+    def set_config_register_func(self, func: Callable[["WRFRunConfig"], None]):
+        """
+        Set register function which will be called by wrfrun config.
+        This functions should accept a ``WRFRunConfig`` instance.
+
+        If wrfrun config hasn't been initialized, the function will be stored
+        and called in order by the time wrfrun config is initialized.
+
+        :param func: Register functions.
+        :type func: Callable[["WRFRunConfig"], None]
+        """
+        if self._config_initialized:
+            func(self._config)
+
+        else:
+            if func not in self._config_register_funcs:
+                self._config_register_funcs.append(func)
+
+    def set_exec_db_register_func(self, func: Callable[["ExecutableDB"], None]):
+        """
+        Set register function which will be called by executables DB.
+        This function should accept a :class:`WRFRunExecutableRegisterCenter` instance.
+
+        If executables DB hasn't been initialized, the function will be stored
+        and called in order by the time executables DB is initialized.
+
+        :param func: Register functions.
+        :type func: Callable[["WRFRunExecutableRegisterCenter"], None]
+        """
+        if self._exec_db_initialized:
+            func(self._exec_db)
+
+        else:
+            if func not in self._exec_db_register_funcs:
+                self._exec_db_register_funcs.append(func)
+
+    def is_initialized(self, name: Literal["config", "exec_db", "record"]) -> bool:
+        """
+        Check if the config has been initialized.
+
+        :param name: Name of the instance.
+        :type name: str
+        :return: True or False.
+        :rtype: bool
+        """
+        flag = False
+
+        match name:
+            case "config":
+                flag = self._config_initialized
+
+            case "exec_db":
+                flag = self._exec_db_initialized
+
+            case "record":
+                flag = self._recorder_initialized
+
+        return flag
+
+    def init_wrfrun_config(self, config_file: str):
+        """
+        Initialize wrfrun config with the given config file.
+
+        :param config_file: Config file path.
+        :type config_file: str
+        """
+        logger.info(f"Initialize `WRFRUNConfig` with config: {config_file}")
+        self._config = WRFRunConfig.from_config_file(config_file, self._config_register_funcs)
+        self._config_initialized = True
+
+    def init_exec_db(self):
+        """
+        Initialize Executable DB.
+        """
+        self._exec_db = ExecutableDB()
+        self._exec_db.apply_register_func(self._exec_db_register_funcs)
+        self._exec_db_initialized = True
+
+    def init_recorder(self, save_path: str, include_data: bool):
+        """
+        Initialize simulation recorder.
+
+        :param save_path: Save path of the replay file.
+        :type save_path: str
+        :param include_data: If includes data.
+        :type include_data: bool
+        """
+        self._recorder = ExecutableRecorder(self._config, save_path, include_data)
+        self._recorder_initialized = True
+
+
+WRFRUN = WRFRUNProxy()
+
+__all__ = ["WRFRUN", "WRFRUNProxy"]

wrfrun/core/error.py

@@ -26,6 +26,7 @@ class WRFRunBasicError(Exception):
     """
     Basic exception class of ``wrfrun``. New exception **MUST** inherit this class.
     """
+
     pass
 
 
@@ -33,6 +34,7 @@ class ConfigError(WRFRunBasicError):
     """
     Exception indicates the config of ``wrfrun`` or NWP model can't be used.
     """
+
     pass
 
 
@@ -40,6 +42,7 @@ class WRFRunContextError(WRFRunBasicError):
     """
     Exception indicates ``wrfrun`` is running out of the ``wrfrun`` context.
     """
+
     pass
 
 
@@ -47,6 +50,7 @@ class CommandError(WRFRunBasicError):
     """
     Exception indicates the command of ``Executable`` can't be executed successfully.
     """
+
     pass
 
 
@@ -54,6 +58,7 @@ class OutputFileError(WRFRunBasicError):
     """
     Exception indicates ``wrfrun`` can't find any output files with the given rules.
     """
+
     pass
 
 
@@ -61,6 +66,7 @@ class ResourceURIError(WRFRunBasicError):
     """
     Exception indicates ``wrfrun`` can't parse the URI.
     """
+
     pass
 
 
@@ -68,6 +74,7 @@ class InputFileError(WRFRunBasicError):
     """
     Exception indicates ``wrfrun`` can't find specified input files.
     """
+
     pass
 
 
@@ -75,6 +82,7 @@ class NamelistError(WRFRunBasicError):
     """
     Exception indicates ``wrfrun`` can't find the namelist user want to use.
     """
+
     pass
 
 
@@ -82,6 +90,7 @@ class NamelistIDError(WRFRunBasicError):
     """
     Exception indicates ``wrfrun`` can't register the specified namelist id.
     """
+
     pass
 
 
@@ -89,6 +98,7 @@ class ExecRegisterError(WRFRunBasicError):
     """
     Exception indicates ``wrfrun`` can't register the specified ``Executable``.
     """
+
     pass
 
 
@@ -96,6 +106,7 @@ class GetExecClassError(WRFRunBasicError):
     """
     Exception indicates ``wrfrun`` can't find the specified ``Executable``.
     """
+
     pass
 
 
@@ -103,8 +114,30 @@ class ModelNameError(WRFRunBasicError):
     """
     Exception indicates ``wrfrun`` can't find config of the specified NWP model in the config file.
     """
+
+    pass
+
+
+class RecordError(WRFRunBasicError):
+    """
+    Exception indicates ``wrfrun`` can't record simulations.
+    """
+
     pass
 
 
-__all__ = ["WRFRunBasicError", "ConfigError", "WRFRunContextError", "CommandError", "OutputFileError", "ResourceURIError", "InputFileError",
-           "NamelistError", "ExecRegisterError", "GetExecClassError", "ModelNameError", "NamelistIDError"]
+__all__ = [
+    "WRFRunBasicError",
+    "ConfigError",
+    "WRFRunContextError",
+    "CommandError",
+    "OutputFileError",
+    "ResourceURIError",
+    "InputFileError",
+    "NamelistError",
+    "ExecRegisterError",
+    "GetExecClassError",
+    "ModelNameError",
+    "NamelistIDError",
+    "RecordError",
+]

wrfrun/core/replay.py

@@ -2,115 +2,29 @@
 wrfrun.core.replay
 ##################
 
-This module provides methods to read config from ``.replay`` file and reproduce the simulation.
+This module provides methods to read configs from replay file and reproduce simulations.
 
 .. 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
-from .error import ExecRegisterError, GetExecClassError
-from ..utils import logger
-
-WRFRUN_REPLAY_URI = ":WRFRUN_REPLAY:"
-
-
-class WRFRunExecutableRegisterCenter:
-    """
-    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
-
-    def __init__(self):
-        if self._initialized:
-            return
-
-        self._exec_db = {}
-
-        self._initialized = True
-
-    def __new__(cls, *args, **kwargs):
-        if cls._instance is None:
-            cls._instance = super().__new__(cls)
-
-        return cls._instance
-
-    def register_exec(self, name: str, cls: type):
-        """
-        Register an ``Executable``'s class with a unique ``name``.
-
-        If the ``name`` has been used, :class:`ExecRegisterError` will be raised.
-
-        :param name: ``Executable``'s unique name.
-        :type name: str
-        :param cls: ``Executable``'s class.
-        :type cls: type
-        """
-        if name in self._exec_db:
-            logger.error(f"'{name}' has been registered.")
-            raise ExecRegisterError(f"'{name}' has been registered.")
-
-        self._exec_db[name] = cls
-
-    def is_registered(self, name: str) -> bool:
-        """
-        Check if an ``Executable``'s class has been registered.
-
-        :param name: ``Executable``'s unique name.
-        :type name: str
-        :return: True or False.
-        :rtype: bool
-        """
-        if name in self._exec_db:
-            return True
-        else:
-            return False
-
-    def get_cls(self, name: str) -> type:
-        """
-        Get an ``Executable``'s class with the ``name``.
-
-        If the ``name`` can't be found, :class:`GetExecClassError` will be raised.
-
-        :param name: ``Executable``'s unique name.
-        :type name: str
-        :return: ``Executable``'s class.
-        :rtype: type
-        """
-        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[name]
-
 
-WRFRUNExecDB = WRFRunExecutableRegisterCenter()
+from ..log import logger
+from .base import ExecutableBase
+from .core import WRFRUN
+from .type import ExecutableConfig
 
 
-def replay_config_generator(replay_config_file: str) -> Generator[tuple[str, ExecutableBase], Any, None]:
+def replay_config_generator(replay_config_file: str) -> Generator[tuple[str, ExecutableBase], None, None]:
     """
     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.
+    If this method doesn't find ``config.json`` in the ``.replay`` file, :class:`FileNotFoundError` will be raised.
 
     The ``Executable`` you get from the generator has been initialized so you can execute it directly.
 
@@ -124,7 +38,7 @@ def replay_config_generator(replay_config_file: str) -> Generator[tuple[str, Exe
     :rtype: Generator
     """
     logger.info(f"Loading replay resources from: {replay_config_file}")
-    work_path = WRFRUNConfig.parse_resource_uri(WRFRUNConfig.WRFRUN_WORKSPACE_REPLAY)
+    work_path = WRFRUN.config.parse_resource_uri(WRFRUN.config.WRFRUN_WORKSPACE_REPLAY)
 
     unpack_archive(replay_config_file, work_path, "zip")
 
@@ -138,9 +52,9 @@ def replay_config_generator(replay_config_file: str) -> Generator[tuple[str, Exe
     for _config in replay_config_list:
         args = _config["class_config"]["class_args"]
         kwargs = _config["class_config"]["class_kwargs"]
-        executable: ExecutableBase = WRFRUNExecDB.get_cls(_config["name"])(*args, **kwargs)
+        executable: ExecutableBase = WRFRUN.ExecDB.get_cls(_config["name"])(*args, **kwargs)
         executable.load_config(_config)
         yield _config["name"], executable
 
 
-__all__ = ["WRFRUNExecDB", "replay_config_generator"]
+__all__ = ["replay_config_generator"]

wrfrun/core/server.py

@@ -2,30 +2,74 @@
 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.
+This module defines the socket server to report simulation progress.
 
 .. autosummary::
     :toctree: generated/
 
+    set_log_parse_func
     WRFRunServer
     WRFRunServerHandler
     stop_server
+
+How does wrfrun get simulation progress?
+****************************************
+
+Currently, wrfrun relies on the log parse function provided by :doc:`model </api/model>`.
+The log parse function should accept one parameter ``datetime``,
+and return an integer represents how many seconds the model has simulated.
+For example, the signature of :func:`get_wrf_simulated_seconds <wrfrun.model.wrf.log.get_wrf_simulated_seconds>` is:
+
+.. code-block:: Python
+
+    def get_wrf_simulated_seconds(start_datetime: datetime) -> int:
+        pass
+
+Socket server API list
+**********************
+
+The socket server accepts a JSON string: ``{"message": "MESSAGE"}``.
+The ``MESSAGE`` can be:
+
+* "stop": Stop the socket server.
+* "debug": Get the start date of the simulation, and the total seconds it will simulate: ``{"start_date": "...", "total_seconds": "..."}``.
+* Any string else: Simulation progress: ``{"usage": "...", "status": "...", "progress": "..."}``.
 """
 
 import socket
 import socketserver
+import threading
 from collections.abc import Callable
 from datetime import datetime
-from json import dumps
+from json import dumps, loads
 from time import time
-from typing import Tuple
+from typing import Any, Tuple
+
+from ..log import logger
+from .core import WRFRUN
+
+
+def _defaut_log_parser(date: datetime) -> int:
+    return -1
+
 
-from .config import WRFRUNConfig
-from ..utils import logger
+SET_LOG_PARSER_LOCK = threading.Lock()
+# default parser returns -1
+LOG_PARSER: Callable[[datetime], int] = _defaut_log_parser
 
-WRFRUN_SERVER_INSTANCE = None
-WRFRUN_SERVER_THREAD = None
+
+def set_log_parse_func(func: Callable[[datetime], int]):
+    """
+    Set log parse function used by socket server.
+
+    :param func: Function used to get simulated seconds from model's log file.
+                 If the function can't parse the simulated seconds, it should return ``-1``.
+    :type func: Callable[[datetime], int]
+    """
+    global SET_LOG_PARSER_LOCK, LOG_PARSER
+
+    with SET_LOG_PARSER_LOCK:
+        LOG_PARSER = func
 
 
 class WRFRunServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
@@ -155,7 +199,8 @@ class WRFRunServerHandler(socketserver.StreamRequestHandler):
     ``status`` represents work status,
     ``progress`` represents simulation progress of the status in percentage.
     """
-    def __init__(self, request, client_address, server: WRFRunServer, log_parse_func: Callable[[datetime], int] | None) -> None:
+
+    def __init__(self, request, client_address, server: WRFRunServer) -> None:
         """
         :class:`WRFRunServer` handler.
 
@@ -165,15 +210,11 @@ class WRFRunServerHandler(socketserver.StreamRequestHandler):
         :type client_address:
         :param server: :class:`WRFRunServer` instance.
         :type server: WRFRunServer
-        :param log_parse_func: Function used to get simulated seconds from model's log file.
-                               If the function can't parse the simulated seconds, it should return ``-1``.
-        :type log_parse_func: Callable[[datetime], int]
         """
         super().__init__(request, client_address, server)
 
         # get server
-        self.server: WRFRunServer = server
-        self.log_parse_func = log_parse_func
+        self._server: WRFRunServer = server
 
     def calculate_time_usage(self) -> int:
         """
@@ -187,7 +228,7 @@ class WRFRunServerHandler(socketserver.StreamRequestHandler):
         current_timestamp = datetime.fromtimestamp(time())
 
         # get delta second
-        seconds_diff = current_timestamp - self.server.get_start_time()
+        seconds_diff = current_timestamp - self._server.get_start_time()
         seconds_diff = seconds_diff.seconds
 
         return seconds_diff
@@ -200,19 +241,17 @@ class WRFRunServerHandler(socketserver.StreamRequestHandler):
                  ``progress`` represents simulation progress of the status in percentage.
         :rtype: tuple[str, int]
         """
-        start_date, simulate_seconds = self.server.get_model_simulate_settings()
+        start_date, simulate_seconds = self._server.get_model_simulate_settings()
 
-        if self.log_parse_func is None:
-            simulated_seconds = -1
-        else:
-            simulated_seconds = self.log_parse_func(start_date)
+        with SET_LOG_PARSER_LOCK:
+            simulated_seconds = LOG_PARSER(start_date)
 
         if simulated_seconds > 0:
             progress = simulated_seconds * 100 // simulate_seconds
         else:
             progress = -1
 
-        status = WRFRUNConfig.WRFRUN_WORK_STATUS
+        status = WRFRUN.config.WRFRUN_WORK_STATUS
 
         if status == "":
             status = "*"
@@ -223,20 +262,20 @@ class WRFRunServerHandler(socketserver.StreamRequestHandler):
         """
         Request handler.
         """
-
         # check if we will to stop server
-        msg = self.rfile.readline().decode().split('\n')[0]
+        request: dict[str, Any] = loads(self.rfile.readline().decode())
+        msg = request["message"]
 
         if msg == "stop":
-            self.server.shutdown()
-            self.wfile.write(f"Server stop\n".encode())
-        
+            self._server.shutdown()
+            self.wfile.write("Server stop\n".encode())
+
         elif msg == "debug":
-            start_date, simulate_seconds = self.server.get_model_simulate_settings()
+            start_date, simulate_seconds = self._server.get_model_simulate_settings()
             start_date = start_date.strftime("%Y-%m-%d %H:%M")
-            
+
             self.wfile.write(dumps({"start_date": start_date, "total_seconds": simulate_seconds}).encode())
-            
+
         else:
             status, progress = self.calculate_progress()
             time_usage = self.calculate_time_usage()
@@ -258,10 +297,13 @@ def stop_server(socket_ip: str, socket_port: int):
         sock.connect((socket_ip, socket_port))
 
         # send msg to server
-        sock.sendall("stop\n".encode())
+        # TODO:
+        #   Need to test the new socket server.
+        msg = dumps({"message": "stop"})
+        sock.sendall(msg.encode())
 
         # receive the message
-        msg = sock.recv(1024).decode().split('\n')[0]
+        msg = sock.recv(1024).decode().split("\n")[0]
 
         logger.info(f"WRFRunServer: {msg}")
 
@@ -269,4 +311,4 @@ def stop_server(socket_ip: str, socket_port: int):
         logger.warning("Fail to stop WRFRunServer, maybe it doesn't start at all.")
 
 
-__all__ = ["WRFRunServer", "WRFRunServerHandler", "stop_server"]
+__all__ = ["WRFRunServer", "WRFRunServerHandler", "stop_server", "set_log_parse_func"]