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

wrfrun/core/_constant.py

@@ -0,0 +1,236 @@
+"""
+wrfrun.core._constant
+#####################
+
+.. autosummary::
+    :toctree: generated/
+
+    ConstantMixIn
+
+ConstantMixIn
+*************
+
+This class provides methods to manage runtime constants of ``wrfrun``.
+"""
+
+from os import environ
+from os.path import abspath
+from sys import platform
+
+from ..log import logger
+from .error import WRFRunContextError
+
+
+class ConstantMixIn:
+    """
+    Define all variables that will be used by other components.
+    """
+
+    def __init__(self, work_dir: str, *args, **kwargs):
+        """
+        Define all variables that will be used by other components.
+
+        These variables are related to ``wrfrun`` installation environments, configuration files and more.
+        They are defined either directly or mapped using URIs to ensure consistent access across all components.
+
+        :param work_dir: ``wrfrun`` work directory path.
+        :type work_dir: str
+        """
+        # check system
+        if platform != "linux":
+            logger.debug("Not Linux system!")
+
+        if work_dir != "" or platform != "linux":
+            # set temporary dir path
+            self._WRFRUN_TEMP_PATH = abspath(f"{work_dir}/tmp")
+            self._WRFRUN_HOME_PATH = abspath(work_dir)
+
+        else:
+            # the path we may need to store temp files,
+            # don't worry, it will be deleted once the system reboots
+            self._WRFRUN_TEMP_PATH = "/tmp/wrfrun"
+            user_home_path = f"{environ['HOME']}"
+
+            # WRF may need a large disk space to store output, we can't run wrf in /tmp,
+            # so we will create a folder in $HOME/.config to run wrf.
+            # we need to check if we're running as a root user
+            if user_home_path in ["/", "/root", ""]:
+                logger.warning(
+                    f"User's home path is '{user_home_path}', which means you are running this program as a root user"
+                )
+                logger.warning("It's not recommended to use wrfrun as a root user")
+                logger.warning("Set user_home_path as /root")
+                user_home_path = "/root"
+
+            self._WRFRUN_HOME_PATH = f"{user_home_path}/.config/wrfrun"
+
+        # workspace root path
+        self._WRFRUN_WORKSPACE_ROOT = f"{self._WRFRUN_HOME_PATH}/workspace"
+        self._WRFRUN_WORKSPACE_MODEL = f"{self._WRFRUN_WORKSPACE_ROOT}/model"
+        self._WRFRUN_WORKSPACE_REPLAY = f"{self._WRFRUN_WORKSPACE_ROOT}/replay"
+
+        # record WRF progress status
+        self._WRFRUN_WORK_STATUS = ""
+
+        # record context status
+        self._WRFRUN_CONTEXT_STATUS = False
+
+        self._WRFRUN_OUTPUT_PATH = ":WRFRUN_OUTPUT_PATH:"
+        self._WRFRUN_RESOURCE_PATH = ":WRFRUN_RESOURCE_PATH:"
+
+        self.IS_IN_REPLAY: bool = False
+
+        self.IS_RECORDING: bool = False
+
+        # in this mode, wrfrun will do all things except call the numerical model.
+        # all output rules will also not be executed.
+        self.FAKE_SIMULATION_MODE = False
+
+        super().__init__(*args, **kwargs)
+
+    def _get_uri_map(self) -> dict[str, str]:
+        """
+        Return URIs and their values.
+        ``wrfrun`` will use this to register uri when initialize config.
+
+        :return: A dict in which URIs are keys and their values are dictionary values.
+        :rtype: dict
+        """
+        return {
+            self.WRFRUN_TEMP_PATH: self._WRFRUN_TEMP_PATH,
+            self.WRFRUN_HOME_PATH: self._WRFRUN_HOME_PATH,
+            self.WRFRUN_WORKSPACE_ROOT: self._WRFRUN_WORKSPACE_ROOT,
+            self.WRFRUN_WORKSPACE_MODEL: self._WRFRUN_WORKSPACE_MODEL,
+            self.WRFRUN_WORKSPACE_REPLAY: self._WRFRUN_WORKSPACE_REPLAY,
+        }
+
+    @property
+    def WRFRUN_WORKSPACE_REPLAY(self) -> str:
+        """
+        Path (URI) to store related files of ``wrfrun`` replay functionality.
+
+        :return: URI.
+        :rtype: str
+        """
+        return ":WRFRUN_WORKSPACE_REPLAY:"
+
+    @property
+    def WRFRUN_TEMP_PATH(self) -> str:
+        """
+        Path to store ``wrfrun`` temporary files.
+
+        :return: URI
+        :rtype: str
+        """
+        return ":WRFRUN_TEMP_PATH:"
+
+    @property
+    def WRFRUN_HOME_PATH(self) -> str:
+        """
+        Root path of all others directories. .
+
+        :return: URI
+        :rtype: str
+        """
+        return ":WRFRUN_HOME_PATH:"
+
+    @property
+    def WRFRUN_WORKSPACE_ROOT(self) -> str:
+        """
+        Path of the root workspace.
+
+        :return: URI
+        :rtype: str
+        """
+        return ":WRFRUN_WORKSPACE_ROOT:"
+
+    @property
+    def WRFRUN_WORKSPACE_MODEL(self) -> str:
+        """
+        Path of the model workspace, in which ``wrfrun`` runs numerical models.
+
+        :return: URI
+        :rtype: str
+        """
+        return ":WRFRUN_WORKSPACE_MODEL:"
+
+    @property
+    def WRFRUN_WORK_STATUS(self) -> str:
+        """
+        ``wrfrun`` work status.
+
+        This attribute can be changed by ``Executable`` to reflect the current work progress of ``wrfrun``.
+        The returned string is the name of ``Executable``.
+
+        :return: A string reflect the current work progress.
+        :rtype: str
+        """
+        return self._WRFRUN_WORK_STATUS
+
+    @WRFRUN_WORK_STATUS.setter
+    def WRFRUN_WORK_STATUS(self, value: str):
+        """
+        Set ``wrfrun`` work status.
+
+        ``wrfrun`` recommends ``Executable`` set the status string with their name,
+        so to avoid the possible conflicts with other ``Executable``,
+        and the user can easily understand the current work progress.
+
+        :param value: A string represents the work status.
+        :type value: str
+        """
+        self._WRFRUN_WORK_STATUS = value
+
+    @property
+    def WRFRUN_OUTPUT_PATH(self) -> str:
+        """
+        The root path to store all outputs of the ``wrfrun`` and NWP model.
+
+        :return: URI
+        :rtype: str
+        """
+        return self._WRFRUN_OUTPUT_PATH
+
+    @property
+    def WRFRUN_RESOURCE_PATH(self) -> str:
+        """
+        The root path of all ``wrfrun`` resource files.
+
+        :return: URI
+        :rtype: str
+        """
+        return self._WRFRUN_RESOURCE_PATH
+
+    def check_wrfrun_context(self, error=False) -> bool:
+        """
+        Check if in WRFRun context or not.
+
+        :param error: An exception :class:`WRFRunContextError` will be raised
+                      if ``error==True`` when we are not in WRFRun context.
+        :type error: bool
+        :return: True or False.
+        :rtype: bool
+        """
+        if self._WRFRUN_CONTEXT_STATUS:
+            return self._WRFRUN_CONTEXT_STATUS
+
+        if not error:
+            logger.warning(
+                "You are using wrfrun without entering `WRFRun` context, which may cause some functions don't work."
+            )
+            return self._WRFRUN_CONTEXT_STATUS
+
+        logger.error("You need to enter `WRFRun` context to use wrfrun.")
+        raise WRFRunContextError("You need to enter `WRFRun` context to use wrfrun.")
+
+    def set_wrfrun_context(self, status: bool):
+        """
+        Change ``WRFRun`` context status to True or False.
+
+        :param status: ``True`` or ``False``.
+        :type status: bool
+        """
+        self._WRFRUN_CONTEXT_STATUS = status
+
+
+__all__ = ["ConstantMixIn"]

wrfrun/core/_exec_db.py

@@ -0,0 +1,105 @@
+"""
+wrfrun.core._exec_db
+####################
+
+.. autosummary::
+    :toctree: generated/
+
+    ExecutableDB
+
+ExecutableDB
+************
+
+To be able to replay simulations, ``wrfrun`` use this class to store ``Executable`` information.
+When replaying simulations, ``wrfrun`` gets the corresponding ``Executable`` and calls it with its name.
+"""
+
+from typing import Callable
+
+from ..log import logger
+from .error import ExecRegisterError, GetExecClassError
+
+
+class ExecutableDB:
+    """
+    This class provides the method to records ``Executable`` class with a unique ``name``.
+    Later you can get the class with the ``name``.
+    """
+
+    def __init__(self):
+        self._exec_db = {}
+
+    def apply_register_func(self, func_list: list[Callable[["ExecutableDB"], None]]):
+        """
+        Call register function provided by other submodules.
+
+        This method allows other submodules register ``Executable`` even after the whole wrfrun has been initialized.
+
+        :param func_list: A list contains register functions.
+        :type func_list: list[Callable[["WRFRunExecutableRegisterCenter"], None]]
+        """
+        while len(func_list) != 0:
+            _func = func_list.pop(0)
+            _func(self)
+
+    def register_exec(self, name: str, cls: type):
+        """
+        Register an ``Executable`` with a unique ``name``.
+
+        If the ``name`` has been used, :class:`ExecRegisterError <wrfrun.core.error.ExecRegisterError>` will be raised.
+
+        :param name: Unique name.
+        :type name: str
+        :param cls: ``Executable`` 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 unregister_exec(self, name: str):
+        """
+        Unregister an ``Executable``.
+
+        :param name: Unique name.
+        :type name: str
+        """
+        if name in self._exec_db:
+            logger.debug(f"Unregister Executable: '{name}'.")
+            self._exec_db.pop(name)
+
+    def is_registered(self, name: str) -> bool:
+        """
+        Check if an ``Executable`` has been registered.
+
+        :param name: 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`` class with the ``name``.
+
+        If the ``name`` can't be found, :class:`ExecRegisterError <wrfrun.core.error.ExecRegisterError>` will be raised.
+
+        :param name: Unique name.
+        :type name: str
+        :return: ``Executable`` 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]
+
+
+__all__ = ["ExecutableDB"]

wrfrun/core/_namelist.py

@@ -0,0 +1,287 @@
+"""
+wrfrun.core._namelist
+#####################
+
+.. autosummary::
+    :toctree: generated/
+
+    NamelistMixIn
+
+NamelistMixIn
+*************
+
+This class provides methods to manage namelist settings of NWP models.
+It can read namelist files, change namelist values or write values to a namelist file.
+
+Namelist values are stored with a unique ``namelist_id``,
+which enables wrfrun to manage multiple namelist settings simultaneously.
+
+**Read namelist file**
+
+.. code-block:: Python
+    :caption: main.py
+
+    namelist = NamelistMixIn()
+    namelist_file_path = "./namelist.wps"
+    namelist_id = "wps"
+
+    # remember to check namelist id first
+    if not namelist.check_namelist_id(namelist_id):
+        namelist.register_namelist_id(namelist_id)
+
+    # read namelist file
+    namelist.read_namelist(namelist_file_path, namelist_id)
+
+**Write namelist file**
+
+.. code-block:: Python
+    :caption: main.py
+
+    namelist_file_path = "./namelist.wps"
+    namelist_id = "wps"
+
+    # will overwrite existing file by default.
+    namelist.write_namelist(namelist_file_path, namelist_id)
+    # doesn't overwrite existing file
+    namelist.write_namelist(namelist_file_path, namelist_id, overwrite=False)
+
+**Update namelist values**
+
+1. You can provide a whole namelist file
+
+.. code-block:: Python
+    :caption: main.py
+
+    namelist_file_path = "./namelist.wps"
+    namelist_id = "wps"
+
+    namelist.update_namelist(namelist_file_path, namelist_id)
+
+2. Or just some values in a dictionary
+
+.. code-block:: Python
+    :caption: main.py
+
+    namelist_value = {"share": {"max_dom": 1}}
+    namelist_id = "wps"
+
+    namelist.update_namelist(namelist_value, namelist_id)
+"""
+
+from copy import deepcopy
+from os.path import exists
+from typing import Union
+
+import f90nml
+
+from ..log import logger
+from .error import NamelistError, NamelistIDError
+
+
+class NamelistMixIn:
+    """
+    Manage namelist settings of NWP models.
+    """
+
+    def __init__(self, *args, **kwargs):
+        self._namelist_dict = {}
+        self._namelist_id_list: tuple[str, ...] = ("param", "geog_static_data", "wps", "wrf", "wrfda", "palm")
+
+        super().__init__(*args, **kwargs)
+
+    def register_namelist_id(self, namelist_id: str) -> bool:
+        """
+        Register a unique ``namelist_id`` so you can read, update and write namelist with it later.
+
+        :param namelist_id: A unique namelist id.
+        :type namelist_id: str
+        :return: True if register successfully, else False.
+        :rtype: bool
+        """
+        if namelist_id in self._namelist_id_list:
+            return False
+
+        else:
+            self._namelist_id_list += (namelist_id,)
+            return True
+
+    def unregister_namelist_id(self, namelist_id: str):
+        """
+        Unregister a ``namelist_id``.
+        If unregister successfully, all values of this namelist will be deleted.
+
+        :param namelist_id: A unique namelist id.
+        :type namelist_id: str
+        """
+        if namelist_id not in self._namelist_id_list:
+            return
+
+        self.delete_namelist(namelist_id)
+        self._namelist_id_list = tuple(
+            set(self._namelist_id_list)
+            - {
+                namelist_id,
+            }
+        )
+
+    def check_namelist_id(self, namelist_id: str) -> bool:
+        """
+        Check if a ``namelist_id`` is registered.
+
+        :param namelist_id: A ``namelist_id``.
+        :type namelist_id: str
+        :return: True if the ``namelist_id`` is registered, else False.
+        :rtype: bool
+        """
+        if namelist_id in self._namelist_id_list:
+            return True
+        else:
+            return False
+
+    def read_namelist(self, file_path: str, namelist_id: str):
+        """
+        Read namelist values from a file and store them with the ``namelist_id``.
+
+        If ``wrfrun`` can't read the file, :class:`FileNotFoundError` will be raised.
+        If ``namelist_id`` isn't registered, :class:`NamelistIDError <wrfrun.core.error.NamelistIDError>` will be raised.
+
+        :param file_path: Namelist file path.
+        :type file_path: str
+        :param namelist_id: Registered ``namelist_id``.
+        :type namelist_id: str
+        """
+        # check the file path
+        if not exists(file_path):
+            logger.error(f"File not found: {file_path}")
+            raise FileNotFoundError
+
+        if namelist_id not in self._namelist_id_list:
+            logger.error(f"Unknown namelist id: {namelist_id}, register it first.")
+            raise NamelistIDError(f"Unknown namelist id: {namelist_id}, register it first.")
+
+        self._namelist_dict[namelist_id] = f90nml.read(file_path).todict()
+
+    def write_namelist(self, save_path: str, namelist_id: str, overwrite=True):
+        """
+        Write namelist values of a ``namelist_id`` to a file.
+
+        If ``namelist_id`` hasn't been registered, or its namelist value can't be found,
+        :class:`NamelistIDError <wrfrun.core.error.NamelistIDError>` will be raised.
+
+        :param save_path: Target file path.
+        :type save_path: str
+        :param namelist_id: Registered ``namelist_id``.
+        :type namelist_id: str
+        :param overwrite: If overwrite the existed file.
+        :type overwrite: bool
+        """
+        if namelist_id not in self._namelist_id_list:
+            logger.error(f"Unknown namelist id: {namelist_id}, register it first.")
+            raise NamelistIDError(f"Unknown namelist id: {namelist_id}, register it first.")
+
+        if namelist_id not in self._namelist_dict:
+            logger.error(f"Can't found custom namelist '{namelist_id}', maybe you forget to read it first")
+            raise NamelistError(f"Can't found custom namelist '{namelist_id}', maybe you forget to read it first")
+
+        f90nml.Namelist(self._namelist_dict[namelist_id]).write(save_path, force=overwrite)
+
+    def update_namelist(self, new_values: Union[str, dict], namelist_id: str):
+        """
+        Update namelist values of a ``namelist_id``.
+
+        You can give the path of a whole namelist file or a file only contains values you want to change.
+
+        >>> from wrfrun.core import WRFRUN
+        >>> namelist_file = "./namelist.wps"
+        >>> WRFRUN.config.update_namelist(namelist_file, namelist_id="wps")
+
+        >>> namelist_file = "./namelist.wrf"
+        >>> WRFRUN.config.update_namelist(namelist_file, namelist_id="wrf")
+
+        You can also give a dictionary contains values you want to change.
+
+        >>> namelist_values = {"ungrib": {"prefix": "./output/FILE"}}
+        >>> WRFRUN.config.update_namelist(namelist_values, namelist_id="wps")
+
+        >>> namelist_values = {"time_control": {"debug_level": 100}}
+        >>> WRFRUN.config.update_namelist(namelist_values, namelist_id="wrf")
+
+        :param new_values: The path of a namelist file, or a dict contains namelist values.
+        :type new_values: str | dict
+        :param namelist_id: Registered ``namelist_id``.
+        :type namelist_id: str
+        """
+        if namelist_id not in self._namelist_id_list:
+            logger.error(f"Unknown namelist id: {namelist_id}, register it first.")
+            raise NamelistIDError(f"Unknown namelist id: {namelist_id}, register it first.")
+
+        elif namelist_id not in self._namelist_dict:
+            self._namelist_dict[namelist_id] = new_values
+            return
+
+        else:
+            reference = self._namelist_dict[namelist_id]
+
+        if isinstance(new_values, str):
+            if not exists(new_values):
+                logger.error(f"File not found: {new_values}")
+                raise FileNotFoundError(f"File not found: {new_values}")
+            new_values = f90nml.read(new_values).todict()
+
+        for key in new_values:
+            if key in reference:
+                reference[key].update(new_values[key])
+            else:
+                reference[key] = new_values[key]
+
+    def get_namelist(self, namelist_id: str) -> dict:
+        """
+        Get namelist values of a ``namelist_id``.
+
+        :param namelist_id: Registered ``namelist_id``.
+        :type namelist_id: str
+        :return: A dictionary which contains namelist values.
+        :rtype: dict
+        """
+        if namelist_id not in self._namelist_id_list:
+            logger.error(f"Unknown namelist id: {namelist_id}, register it first.")
+            raise NamelistIDError(f"Unknown namelist id: {namelist_id}, register it first.")
+        elif namelist_id not in self._namelist_dict:
+            logger.error(f"Can't found custom namelist '{namelist_id}', maybe you forget to read it first")
+            raise NamelistError(f"Can't found custom namelist '{namelist_id}', maybe you forget to read it first")
+        else:
+            return deepcopy(self._namelist_dict[namelist_id])
+
+    def delete_namelist(self, namelist_id: str):
+        """
+        Delete namelist values of a ``namelist_id``.
+
+        :param namelist_id: Registered ``namelist_id``.
+        :type namelist_id: str
+        """
+        if namelist_id not in self._namelist_id_list:
+            logger.error(f"Unknown namelist id: {namelist_id}, register it first.")
+            raise ValueError(f"Unknown namelist id: {namelist_id}, register it first.")
+
+        if namelist_id not in self._namelist_dict:
+            return
+
+        self._namelist_dict.pop(namelist_id)
+
+    def check_namelist(self, namelist_id: str) -> bool:
+        """
+        Check if a namelist has been registered and loaded.
+
+        :param namelist_id: Registered ``namelist_id``.
+        :type namelist_id: str
+        :return: ``True`` if it is registered and loaded, else ``False``.
+        :rtype: bool
+        """
+        if namelist_id in self._namelist_id_list and namelist_id in self._namelist_dict:
+            return True
+
+        else:
+            return False
+
+
+__all__ = ["NamelistMixIn"]