hpcflow-new2 0.2.0a179__py3-none-any.whl → 0.2.0a181__py3-none-any.whl

hpcflow/sdk/submission/jobscript.py

@@ -1,3 +1,7 @@
+"""
+Model of information submitted to a scheduler.
+"""
+
 from __future__ import annotations
 import copy
 
@@ -28,8 +32,10 @@ def generate_EAR_resource_map(
     task: app.WorkflowTask,
     loop_idx: Dict,
 ) -> Tuple[List[app.ElementResources], List[int], NDArray, NDArray]:
-    """Generate an integer array whose rows represent actions and columns represent task
-    elements and whose values index unique resources."""
+    """
+    Generate an integer array whose rows represent actions and columns represent task
+    elements and whose values index unique resources.
+    """
     # TODO: assume single iteration for now; later we will loop over Loop tasks for each
     # included task and call this func with specific loop indices
     none_val = -1
@@ -83,6 +89,9 @@ def group_resource_map_into_jobscripts(
     resource_map: Union[List, NDArray],
     none_val: Any = -1,
 ):
+    """
+    Convert a resource map into a plan for what elements to group together into jobscripts.
+    """
     resource_map = np.asanyarray(resource_map)
     resource_idx = np.unique(resource_map)
     jobscripts = []
@@ -152,6 +161,9 @@ def group_resource_map_into_jobscripts(
 
 @TimeIt.decorator
 def resolve_jobscript_dependencies(jobscripts, element_deps):
+    """
+    Discover concrete dependencies between jobscripts.
+    """
     # first pass is to find the mappings between jobscript elements:
     jobscript_deps = {}
     for js_idx, elem_deps in element_deps.items():
@@ -302,6 +314,52 @@ def jobscripts_to_list(jobscripts: Dict[int, Dict]) -> List[Dict]:
 
 
 class Jobscript(JSONLike):
+    """
+    A group of actions that are submitted together to be executed by the underlying job
+    management system as a single unit.
+
+    Parameters
+    ----------
+    task_insert_IDs: list[int]
+        The task insertion IDs.
+    task_actions: list[tuple]
+        The actions of the tasks.
+        ``task insert ID, action_idx, index into task_loop_idx`` for each ``JS_ACTION_IDX``
+    task_elements: dict[int, list[int]]
+        The elements of the tasks.
+        Maps ``JS_ELEMENT_IDX`` to list of ``TASK_ELEMENT_IDX`` for each ``TASK_INSERT_ID``
+    EAR_ID:
+        Element action run information.
+    resources: ~hpcflow.app.ElementResources
+        Resources to use
+    task_loop_idx: list[dict]
+        Description of what loops are in play.
+    dependencies: dict[int, dict]
+        Description of dependencies.
+    submit_time: datetime
+        When the jobscript was submitted, if known.
+    submit_hostname: str
+        Where the jobscript was submitted, if known.
+    submit_machine: str
+        Description of what the jobscript was submitted to, if known.
+    submit_cmdline: str
+        The command line used to do the commit, if known.
+    scheduler_job_ID: str
+        The job ID from the scheduler, if known.
+    process_ID: int
+        The process ID of the subprocess, if known.
+    version_info: tuple[str, ...]
+        Version info about the target system.
+    os_name: str
+        The name of the OS.
+    shell_name: str
+        The name of the shell.
+    scheduler_name: str
+        The scheduler used.
+    running: bool
+        Whether the jobscript is currently running.
+    """
+
     _app_attr = "app"
     _EAR_files_delimiter = ":"
     _workflow_app_alias = "wkflow_app"
@@ -399,9 +457,15 @@ class Jobscript(JSONLike):
 
     @property
     def workflow_app_alias(self):
+        """
+        Alias for the workflow app in job scripts.
+        """
         return self._workflow_app_alias
 
     def get_commands_file_name(self, js_action_idx, shell=None):
+        """
+        Get the name of a file containing commands for a particular jobscript action.
+        """
         return self.app.RunDirAppFiles.get_commands_file_name(
             js_idx=self.index,
             js_action_idx=js_action_idx,
@@ -410,47 +474,74 @@ class Jobscript(JSONLike):
 
     @property
     def task_insert_IDs(self):
+        """
+        The insertion IDs of tasks in this jobscript.
+        """
         return self._task_insert_IDs
 
     @property
     def task_actions(self):
+        """
+        The IDs of actions of each task in this jobscript.
+        """
         return self._task_actions
 
     @property
     def task_elements(self):
+        """
+        The IDs of elements of each task in this jobscript.
+        """
         return self._task_elements
 
     @property
     def EAR_ID(self):
+        """
+        The array of EAR IDs.
+        """
         return self._EAR_ID
 
     @property
     def all_EAR_IDs(self) -> List[int]:
+        """
+        The IDs of all EARs in this jobscript.
+        """
         return self.EAR_ID.flatten()
 
     @property
     @TimeIt.decorator
     def all_EARs(self) -> List:
+        """
+        Description of EAR information for this jobscript.
+        """
         if not self._all_EARs:
             self._all_EARs = self.workflow.get_EARs_from_IDs(self.all_EAR_IDs)
         return self._all_EARs
 
     @property
     def resources(self):
+        """
+        The common resources that this jobscript requires.
+        """
         return self._resources
 
     @property
     def task_loop_idx(self):
+        """
+        The description of where various task loops are.
+        """
         return self._task_loop_idx
 
     @property
     def dependencies(self):
+        """
+        The dependency descriptor.
+        """
         return self._dependencies
 
     @property
     @TimeIt.decorator
     def start_time(self):
-        """Get the first start time from all EARs."""
+        """The first known start time of any EAR in this jobscript."""
         if not self.is_submitted:
             return
         all_times = [i.start_time for i in self.all_EARs if i.start_time]
@@ -462,7 +553,7 @@ class Jobscript(JSONLike):
     @property
     @TimeIt.decorator
     def end_time(self):
-        """Get the last end time from all EARs."""
+        """The last known end time of any EAR in this jobscript."""
         if not self.is_submitted:
             return
         all_times = [i.end_time for i in self.all_EARs if i.end_time]
@@ -473,6 +564,9 @@ class Jobscript(JSONLike):
 
     @property
     def submit_time(self):
+        """
+        When the jobscript was submitted, if known.
+        """
         if self._submit_time_obj is None and self._submit_time:
             self._submit_time_obj = (
                 datetime.strptime(self._submit_time, self.workflow.ts_fmt)
@@ -483,50 +577,86 @@ class Jobscript(JSONLike):
 
     @property
     def submit_hostname(self):
+        """
+        Where the jobscript was submitted, if known.
+        """
         return self._submit_hostname
 
     @property
     def submit_machine(self):
+        """
+        Description of what the jobscript was submitted to, if known.
+        """
         return self._submit_machine
 
     @property
     def submit_cmdline(self):
+        """
+        The command line used to do the commit, if known.
+        """
         return self._submit_cmdline
 
     @property
     def scheduler_job_ID(self):
+        """
+        The job ID from the scheduler, if known.
+        """
         return self._scheduler_job_ID
 
     @property
     def process_ID(self):
+        """
+        The process ID from direct execution, if known.
+        """
         return self._process_ID
 
     @property
     def version_info(self):
+        """
+        Version information about the execution environment (OS, etc).
+        """
         return self._version_info
 
     @property
     def index(self):
+        """
+        The index of this jobscript within its parent :py:class:`Submission`.
+        """
         return self._index
 
     @property
     def submission(self):
+        """
+        The parent submission.
+        """
         return self._submission
 
     @property
     def workflow(self):
+        """
+        The workflow this is all on behalf of.
+        """
         return self.submission.workflow
 
     @property
     def num_actions(self):
+        """
+        The number of actions in this jobscript.
+        """
         return self.EAR_ID.shape[0]
 
     @property
     def num_elements(self):
+        """
+        The number of elements in this jobscript.
+        """
         return self.EAR_ID.shape[1]
 
     @property
     def is_array(self):
+        """
+        Whether to generate an array job.
+        """
         if self.scheduler_name == "direct":
             return False
 
@@ -546,14 +676,23 @@ class Jobscript(JSONLike):
 
     @property
     def os_name(self) -> Union[str, None]:
+        """
+        The name of the OS to use.
+        """
         return self._os_name or self.resources.os_name
 
     @property
     def shell_name(self) -> Union[str, None]:
+        """
+        The name of the shell to use.
+        """
         return self._shell_name or self.resources.shell
 
     @property
     def scheduler_name(self) -> Union[str, None]:
+        """
+        The name of the scheduler to use.
+        """
         return self._scheduler_name or self.resources.scheduler
 
     def _get_submission_os_args(self):
@@ -578,7 +717,7 @@ class Jobscript(JSONLike):
 
     @property
     def shell(self):
-        """Retrieve the shell object for submission."""
+        """The shell for composing submission scripts."""
         if self._shell_obj is None:
             self._shell_obj = self._get_shell(
                 os_name=self.os_name,
@@ -590,7 +729,7 @@ class Jobscript(JSONLike):
 
     @property
     def scheduler(self):
-        """Retrieve the scheduler object for submission."""
+        """The scheduler that submissions go to from this jobscript."""
         if self._scheduler_obj is None:
             self._scheduler_obj = self.app.get_scheduler(
                 scheduler_name=self.scheduler_name,
@@ -601,52 +740,81 @@ class Jobscript(JSONLike):
 
     @property
     def EAR_ID_file_name(self):
+        """
+        The name of a file containing EAR IDs.
+        """
         return f"js_{self.index}_EAR_IDs.txt"
 
     @property
     def element_run_dir_file_name(self):
+        """
+        The name of a file containing run directory names.
+        """
         return f"js_{self.index}_run_dirs.txt"
 
     @property
     def direct_stdout_file_name(self):
-        """For direct execution stdout."""
+        """File for direct execution stdout."""
         return f"js_{self.index}_stdout.log"
 
     @property
     def direct_stderr_file_name(self):
-        """For direct execution stderr."""
+        """File for direct execution stderr."""
         return f"js_{self.index}_stderr.log"
 
     @property
     def direct_win_pid_file_name(self):
+        """File for holding the direct execution PID."""
         return f"js_{self.index}_pid.txt"
 
     @property
     def jobscript_name(self):
+        """The name of the jobscript file."""
         return f"js_{self.index}{self.shell.JS_EXT}"
 
     @property
     def EAR_ID_file_path(self):
+        """
+        The path to the file containing EAR IDs for this jobscript.
+        """
         return self.submission.path / self.EAR_ID_file_name
 
     @property
     def element_run_dir_file_path(self):
+        """
+        The path to the file containing run directory names for this jobscript.
+        """
         return self.submission.path / self.element_run_dir_file_name
 
     @property
     def jobscript_path(self):
+        """
+        The path to the file containing the jobscript file.
+        """
         return self.submission.path / self.jobscript_name
 
     @property
     def direct_stdout_path(self):
+        """
+        The path to the file containing the stdout from directly executed commands
+        for this jobscript.
+        """
         return self.submission.path / self.direct_stdout_file_name
 
     @property
     def direct_stderr_path(self):
+        """
+        The path to the file containing the stderr from directly executed commands
+        for this jobscript.
+        """
         return self.submission.path / self.direct_stderr_file_name
 
     @property
     def direct_win_pid_file_path(self):
+        """
+        The path to the file containing PIDs for directly executed commands for this
+        jobscript. Windows only.
+        """
         return self.submission.path / self.direct_win_pid_file_name
 
     def _set_submit_time(self, submit_time: datetime) -> None:
@@ -737,6 +905,9 @@ class Jobscript(JSONLike):
             )
 
     def get_task_loop_idx_array(self):
+        """
+        Get an array of task loop indices.
+        """
         loop_idx = np.empty_like(self.EAR_ID)
         loop_idx[:] = np.array([i[2] for i in self.task_actions]).reshape(
             (len(self.task_actions), 1)
@@ -916,6 +1087,9 @@ class Jobscript(JSONLike):
         scheduler_name: Optional[str] = None,
         scheduler_args: Optional[Dict] = None,
     ):
+        """
+        Write the jobscript to its file.
+        """
         js_str = self.compose_jobscript(
             deps=deps,
             os_name=os_name,
@@ -935,6 +1109,9 @@ class Jobscript(JSONLike):
 
     @TimeIt.decorator
     def make_artifact_dirs(self):
+        """
+        Create the directories that will hold artifacts associated with this jobscript.
+        """
         EARs_arr = self._get_EARs_arr()
         task_loop_idx_arr = self.get_task_loop_idx_array()
 
@@ -1036,6 +1213,9 @@ class Jobscript(JSONLike):
         scheduler_refs: Dict[int, (str, bool)],
         print_stdout: Optional[bool] = False,
     ) -> str:
+        """
+        Submit the jobscript to the scheduler.
+        """
         # map each dependency jobscript index to the JS ref (job/process ID) and if the
         # dependency is an array dependency:
         deps = {}
@@ -1143,11 +1323,14 @@ class Jobscript(JSONLike):
 
     @property
     def is_submitted(self):
-        """Return True if this jobscript has been submitted."""
+        """Whether this jobscript has been submitted."""
         return self.index in self.submission.submitted_jobscripts
 
     @property
     def scheduler_js_ref(self):
+        """
+        The reference to the submitted job for the jobscript.
+        """
         if isinstance(self.scheduler, Scheduler):
             return self.scheduler_job_ID
         else:
@@ -1155,6 +1338,9 @@ class Jobscript(JSONLike):
 
     @property
     def scheduler_ref(self):
+        """
+        The generalised scheduler reference descriptor.
+        """
         out = {"js_refs": [self.scheduler_js_ref]}
         if not isinstance(self.scheduler, Scheduler):
             out["num_js_elements"] = self.num_elements
@@ -1210,6 +1396,9 @@ class Jobscript(JSONLike):
         return out
 
     def cancel(self):
+        """
+        Cancel this jobscript.
+        """
         self.app.submission_logger.info(
             f"Cancelling jobscript {self.index} of submission {self.submission.index}"
         )

hpcflow/sdk/submission/jobscript_info.py

@@ -1,3 +1,7 @@
+"""
+Jobscript state enumeration.
+"""
+
 import enum
 
 
@@ -13,36 +17,42 @@ class JobscriptElementState(enum.Enum):
         member.__doc__ = doc
         return member
 
+    #: Waiting for resource allocation.
     pending = (
         0,
         "○",
         "yellow",
         "Waiting for resource allocation.",
     )
+    #: Waiting for one or more dependencies to finish.
     waiting = (
         1,
         "◊",
         "grey46",
         "Waiting for one or more dependencies to finish.",
     )
+    #: Executing now.
     running = (
         2,
         "●",
         "dodger_blue1",
         "Executing now.",
     )
+    #: Previously submitted but is no longer active.
     finished = (
         3,
         "■",
         "grey46",
         "Previously submitted but is no longer active.",
     )
+    #: Cancelled by the user.
     cancelled = (
         4,
         "C",
         "red3",
         "Cancelled by the user.",
     )
+    #: The scheduler reports an error state.
     errored = (
         5,
         "E",
@@ -52,4 +62,7 @@ class JobscriptElementState(enum.Enum):
 
     @property
     def rich_repr(self):
+        """
+        Rich representation of this enumeration element.
+        """
         return f"[{self.colour}]{self.symbol}[/{self.colour}]"

hpcflow/sdk/submission/schedulers/__init__.py

@@ -1,3 +1,7 @@
+"""
+Job scheduler models.
+"""
+
 from pathlib import Path
 import sys
 import time
@@ -5,7 +9,22 @@ from typing import Any, List, Tuple
 
 
 class NullScheduler:
+    """
+    Abstract base class for schedulers.
+
+    Keyword Args
+    ------------
+    shell_args: str
+        Arguments to pass to the shell. Pre-quoted.
+    shebang_args: str
+        Arguments to set on the shebang line. Pre-quoted.
+    options: dict
+        Options to the scheduler.
+    """
+
+    #: Default value for arguments to the shell.
     DEFAULT_SHELL_ARGS = ""
+    #: Default value for arguments on the shebang line.
     DEFAULT_SHEBANG_ARGS = ""
 
     def __init__(
@@ -20,6 +39,9 @@ class NullScheduler:
 
     @property
     def unique_properties(self):
+        """
+        Unique properties, for hashing.
+        """
         return (self.__class__.__name__,)
 
     def __eq__(self, other) -> bool:
@@ -29,20 +51,52 @@ class NullScheduler:
             return self.__dict__ == other.__dict__
 
     def get_version_info(self):
+        """
+        Get the version of the scheduler.
+        """
         return {}
 
     def parse_submission_output(self, stdout: str) -> None:
+        """
+        Parse the output from a submission to determine the submission ID.
+        """
         return None
 
     @staticmethod
     def is_num_cores_supported(num_cores, core_range: List[int]):
+        """
+        Test whether particular number of cores is supported in given range of cores.
+        """
         step = core_range[1] if core_range[1] is not None else 1
         upper = core_range[2] + 1 if core_range[2] is not None else sys.maxsize
         return num_cores in range(core_range[0], upper, step)
 
 
 class Scheduler(NullScheduler):
+    """
+    Base class for schedulers that use a job submission system.
+
+    Parameters
+    ----------
+    submit_cmd: str
+        The submission command, if overridden from default.
+    show_cmd: str
+        The show command, if overridden from default.
+    del_cmd: str
+        The delete command, if overridden from default.
+    js_cmd: str
+        The job script command, if overridden from default.
+    login_nodes_cmd: str
+        The login nodes command, if overridden from default.
+    array_switch: str
+        The switch to enable array jobs, if overridden from default.
+    array_item_var: str
+        The variable for array items, if overridden from default.
+    """
+
+    #: Default command for logging into nodes.
     DEFAULT_LOGIN_NODES_CMD = None
+    #: Default pattern for matching the names of login nodes.
     DEFAULT_LOGIN_NODE_MATCH = "*login*"
 
     def __init__(
@@ -72,6 +126,9 @@ class Scheduler(NullScheduler):
         return (self.__class__.__name__, self.submit_cmd, self.show_cmd, self.del_cmd)
 
     def format_switch(self, switch):
+        """
+        Format a particular switch to use the JS command.
+        """
         return f"{self.js_cmd} {switch}"
 
     def is_jobscript_active(self, job_ID: str):
@@ -79,6 +136,9 @@ class Scheduler(NullScheduler):
         return bool(self.get_job_state_info([job_ID]))
 
     def wait_for_jobscripts(self, js_refs: List[Any]) -> None:
+        """
+        Wait for jobscripts to update their state.
+        """
         while js_refs:
             info = self.get_job_state_info(js_refs)
             print(info)