access-profiling 0.1__py3-none-any.whl

access/profiling/__init__.py

@@ -0,0 +1,32 @@
+"""
+access-profiling package.
+"""
+
+from contextlib import suppress
+from importlib.metadata import PackageNotFoundError, version
+
+__version__ = "unknown"
+with suppress(PackageNotFoundError):
+    __version__ = version("access-profiling")
+
+from access.profiling.access_models import ESM16Profiling, RAM3Profiling
+from access.profiling.cice5_parser import CICE5ProfilingParser
+from access.profiling.cylc_parser import CylcDBReader, CylcProfilingParser
+from access.profiling.esmf_parser import ESMFSummaryProfilingParser
+from access.profiling.fms_parser import FMSProfilingParser
+from access.profiling.parser import ProfilingParser
+from access.profiling.payujson_parser import PayuJSONProfilingParser
+from access.profiling.um_parser import UMProfilingParser
+
+__all__ = [
+    "ProfilingParser",
+    "FMSProfilingParser",
+    "UMProfilingParser",
+    "CICE5ProfilingParser",
+    "PayuJSONProfilingParser",
+    "ESMFSummaryProfilingParser",
+    "ESM16Profiling",
+    "CylcProfilingParser",
+    "CylcDBReader",
+    "RAM3Profiling",
+]

access/profiling/access_models.py

@@ -0,0 +1,84 @@
+# Copyright 2025 ACCESS-NRI and contributors. See the top-level COPYRIGHT file for details.
+# SPDX-License-Identifier: Apache-2.0
+
+import logging
+from pathlib import Path
+
+from access.config import YAMLParser
+from access.config.esm1p6_layout_input import (
+    LayoutSearchConfig,
+    LayoutTuple,
+    generate_esm1p6_core_layouts_from_node_count,
+    generate_esm1p6_perturb_block,
+)
+
+from access.profiling.cice5_parser import CICE5ProfilingParser
+from access.profiling.cylc_manager import CylcRoseManager
+from access.profiling.experiment import ProfilingLog
+from access.profiling.fms_parser import FMSProfilingParser
+from access.profiling.payu_manager import PayuManager
+from access.profiling.um_parser import UMProfilingParser, UMTotalRuntimeParser
+
+logger = logging.getLogger(__name__)
+
+
+class ESM16Profiling(PayuManager):
+    """Handles profiling of ACCESS-ESM1.6 configurations."""
+
+    @property
+    def model_type(self) -> str:
+        return "access-esm1.6"
+
+    def get_component_logs(self, path: Path) -> dict[str, ProfilingLog]:
+        """Returns available profiling logs for the components in ACCESS-ESM1.6.
+
+        Args:
+            path (Path): Path to the output directory.
+        Returns:
+            dict[str, ProfilingLog]: Dictionary mapping component names to their ProfilingLog instances.
+        """
+        logs = {}
+        parser = YAMLParser()
+
+        um_env_path = path / "atmosphere" / "um_env.yaml"
+        um_env = parser.parse(um_env_path.read_text())
+        um_logfile = path / "atmosphere" / f"{um_env['UM_STDOUT_FILE']}0"
+        if um_logfile.is_file():
+            logger.debug(f"Found UM log file: {um_logfile}")
+            logs["UM"] = ProfilingLog(um_logfile, UMProfilingParser())
+            logs["UM_Total_Walltime"] = ProfilingLog(um_logfile, UMTotalRuntimeParser())
+
+        config_path = path / "config.yaml"
+        payu_config = parser.parse(config_path.read_text())
+        mom5_logfile = path / f"{payu_config['model']}.out"
+        if mom5_logfile.is_file():
+            logger.debug(f"Found MOM5 log file: {mom5_logfile}")
+            logs["MOM5"] = ProfilingLog(mom5_logfile, FMSProfilingParser(has_hits=False))
+
+        cice5_logfile = path / "ice" / "ice_diag.d"
+        if cice5_logfile.is_file():
+            logger.debug(f"Found CICE5 log file: {cice5_logfile}")
+            logs["CICE5"] = ProfilingLog(cice5_logfile, CICE5ProfilingParser())
+
+        return logs
+
+    def generate_core_layouts_from_node_count(
+        self, num_nodes: float, cores_per_node: int, layout_search_config: LayoutSearchConfig | None = None
+    ) -> list:
+        return generate_esm1p6_core_layouts_from_node_count(
+            num_nodes, cores_per_node, layout_search_config=layout_search_config
+        )
+
+    def generate_perturbation_block(self, layout: LayoutTuple, branch_name_prefix: str) -> dict:
+        return generate_esm1p6_perturb_block(layout, branch_name_prefix)
+
+
+class RAM3Profiling(CylcRoseManager):
+    """Handles profiling of ACCESS-rAM3 configurations."""
+
+    @property
+    def known_parsers(self):
+        return {
+            "UM_regions": UMProfilingParser(),
+            "UM_total": UMTotalRuntimeParser(),
+        }

access/profiling/cice5_parser.py

@@ -0,0 +1,80 @@
+# Copyright 2025 ACCESS-NRI and contributors. See the top-level COPYRIGHT file for details.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Parser for CICE5 profiling data.
+The data to be parsed is written in the following form, where block stats are discarded:
+
+Timer   1:     Total    8133.37 seconds
+  Timer stats (node): min =     8133.36 seconds
+                      max =     8133.37 seconds
+                      mean=     8133.36 seconds
+  Timer stats(block): min =        0.00 seconds
+                      max =        0.00 seconds
+                      mean=        0.00 seconds
+Timer   2:  TimeLoop    8133.00 seconds
+  Timer stats (node): min =     8132.99 seconds
+                      max =     8133.00 seconds
+                      mean=     8132.99 seconds
+  Timer stats(block): min =        0.00 seconds
+                      max =        0.00 seconds
+                      mean=        0.00 seconds
+
+These timers are printed at the end of the CICE5 run and can be an arbitrary number of timers.
+For example, ESM1.6 has 17 timers printed at the end of ice_diag.d output log.
+"""
+
+import os
+import re
+from pathlib import Path
+
+from access.profiling.metrics import tavg, tmax, tmin
+from access.profiling.parser import ProfilingParser, _read_text_file
+
+
+class CICE5ProfilingParser(ProfilingParser):
+    """CICE5 profiling output parser."""
+
+    _metrics = [tmin, tmax, tavg]
+
+    def parse(self, file_path: str | Path | os.PathLike) -> dict:
+        """Implements "parse" abstract method to parse profiling data in CICE5 log output.
+
+        Args:
+            file_path (str | Path | os.PathLike): file to parse.
+
+        Returns:
+            dict: Parsed timing information.
+
+        Raises:
+            ValueError: If matching timings aren't found.
+            TypeError: If file_path cannot be converted to a valid Path object.
+            FileNotFoundError: If file_path doesn't exist or isn't a file.
+        """
+
+        stream = _read_text_file(file_path)
+
+        # Initialize result dictionary
+        result = {"region": [], tmin: [], tmax: [], tavg: []}
+
+        # Regex pattern to match timer blocks
+        # This captures the region name and the three node timing values
+        pattern = (
+            r"Timer\s+\d+:\s+(\w+)\s+[\d.]+\s+seconds\s+Timer stats \(node\): min =\s+([\d.]+) seconds\s+max ="
+            r"\s+([\d.]+) seconds\s+mean=\s+([\d.]+) seconds"
+        )
+
+        # Find all matches
+        matches = re.findall(pattern, stream, re.MULTILINE | re.DOTALL)
+
+        if not matches:
+            raise ValueError("No CICE5 profiling data found")
+
+        # Extract data from matches
+        for match in matches:
+            region, min_time, max_time, mean_time = match
+            result["region"].append(region)
+            result[tmin].append(float(min_time))
+            result[tmax].append(float(max_time))
+            result[tavg].append(float(mean_time))
+
+        return result

access/profiling/cylc_manager.py

@@ -0,0 +1,209 @@
+# Copyright 2025 ACCESS-NRI and contributors. See the top-level COPYRIGHT file for details.
+# SPDX-License-Identifier: Apache-2.0
+
+import logging
+import shutil
+import subprocess
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from access.profiling.cylc_parser import CylcDBReader, CylcProfilingParser
+from access.profiling.experiment import ProfilingExperiment, ProfilingExperimentStatus, ProfilingLog
+from access.profiling.manager import ProfilingManager
+from access.profiling.parser import ProfilingParser
+
+logger = logging.getLogger(__name__)
+
+
+class CylcRoseManager(ProfilingManager, ABC):
+    """Abstract base class to handle profiling data for Cylc Rose configurations.
+
+    Args:
+        work_dir (Path): Working directory where profiling experiments will be generated and run.
+        archive_dir (Path): Directory where completed experiments will be archived.
+        layout_variable (str): Name of the variable in rose-suite-run.conf file that defines the layout.
+    """
+
+    _layout_variable: str  # Name of the variable in rose-suite-run.conf file that defines the layout.
+
+    def __init__(self, work_dir: Path, archive_dir: Path, layout_variable: str):
+        super().__init__(work_dir, archive_dir)
+        self._layout_variable = layout_variable
+
+    @property
+    @abstractmethod
+    def known_parsers(self) -> dict[str, ProfilingParser]:
+        """Returns the parsers that this model configuration knows about.
+
+        Returns:
+            dict[str, ProfilingParser]: a dictionary of known parsers with names as keys.
+        """
+
+    def parse_ncpus(self, path: Path, run_path: Path | None = None) -> int:
+        # both the run and original config will store cpu information
+        config_paths = []
+        if run_path is not None:
+            config_paths.append(run_path / "log/rose-suite-run.conf")
+        config_paths.append(path / "rose-suite.conf")
+
+        config_path = next((candidate for candidate in config_paths if candidate.is_file()), None)
+        if config_path is None:
+            tried = ", ".join(str(p) for p in config_paths)
+            raise FileNotFoundError(f"Could not find suitable config file. Tried: {tried}")
+
+        for line in config_path.read_text().splitlines():
+            if not line.startswith("!!") and "=" in line:
+                key, value = line.split("=", 1)
+                if key.strip() == self._layout_variable:
+                    layout = value.split(",")
+                    return int(layout[0].strip()) * int(layout[1].strip())
+
+        raise ValueError(f"Cannot find layout key, {self._layout_variable}, in {config_path}.")
+
+    def add_rose_experiment(self, rose: str, run_path: Path | None = None) -> None:
+        """Adds the given rose as an experiment to this manager.
+
+        Args:
+            rose (str): The rose to add as an experiment.
+            run_path (Path | None): Path to the Cylc run directory holding the results. If not provided, or if the
+                provided directory does not exist, archiving will only include the experiment files.
+
+        Raises:
+            ValueError: If the experiment path does not exist.
+        """
+        experiment_path = self.work_dir / rose
+        if not experiment_path.is_dir():
+            raise ValueError(f"Experiment path '{experiment_path}' does not exist or is not a directory.")
+
+        if run_path is not None and not run_path.is_dir():
+            logger.warning(f"Run path '{run_path}' does not exist. Archiving will only include experiment files.")
+            run_path = None
+
+        self.experiments[rose] = ProfilingExperiment(path=experiment_path, run_path=run_path)
+        self.experiments[rose].status = ProfilingExperimentStatus.DONE
+
+    def run_experiments(self) -> None:
+        """Runs Rose Cylc experiments via `rose suite-run` for profiling data generation."""
+
+        to_run = {name: exp for name, exp in self.experiments.items() if exp.status == ProfilingExperimentStatus.NEW}
+
+        if not to_run:
+            logger.info("No new experiments to run. Will skip execution.")
+            return
+
+        for name, exp in to_run.items():
+            logger.info(f"Running experiment '{name}' via rose suite-run in '{exp.path}'.")
+            try:
+                result = subprocess.run(["rose", "suite-run"], cwd=exp.path, check=True, capture_output=True, text=True)
+            except subprocess.CalledProcessError as e:
+                for line in e.stdout.splitlines():
+                    logger.info(f"[{name}] {line}")
+                for line in e.stderr.splitlines():
+                    logger.error(f"[{name}] {line}")
+                raise
+            for line in result.stdout.splitlines():
+                logger.info(f"[{name}] {line}")
+            for line in result.stderr.splitlines():
+                logger.warning(f"[{name}] {line}")
+            exp.status = ProfilingExperimentStatus.RUNNING
+
+        # TODO: properly detect when running experiments have completed rather than marking them done immediately.
+        for exp_name in self.experiments:
+            if self.experiments[exp_name].status == ProfilingExperimentStatus.RUNNING:
+                self.experiments[exp_name].status = ProfilingExperimentStatus.DONE
+
+    def _delete_experiment(self, name: str, dry_run: bool) -> None:
+        """Deletes the experiment and run directories of a single Rose Cylc experiment.
+
+        Args:
+            name (str): Name of the experiment to delete.
+            dry_run (bool): If True, logs what would be deleted without making any changes.
+        """
+        exp = self.experiments[name]
+        exp_path = exp.path
+        run_path = exp.run_path
+        if dry_run:
+            logger.info(f"Dry run: would delete experiment directory '{exp_path}' and run directory '{run_path}'.")
+            return
+        if exp_path.is_dir():
+            logger.info(f"Deleting experiment directory '{exp_path}'.")
+            shutil.rmtree(exp_path)
+        else:
+            logger.warning(f"Experiment directory '{exp_path}' does not exist. Skipping deletion.")
+        if run_path is not None:
+            if run_path.is_dir():
+                logger.info(f"Deleting run directory '{run_path}'.")
+                shutil.rmtree(run_path)
+            else:
+                logger.warning(f"Run directory '{run_path}' does not exist. Skipping deletion.")
+
+    def archive_experiments(
+        self,
+        exclude_dirs: list[str] | None = None,
+        exclude_files: list[str] | None = None,
+        follow_symlinks: bool = False,
+        overwrite: bool = False,
+    ) -> None:
+        """Archives completed experiments to the specified archive path.
+
+        Args:
+            exclude_dirs (list[str] | None): Directory patterns to exclude when archiving. Defaults to
+                [".svn", "share"] if not provided.
+            exclude_files (list[str] | None): File patterns to exclude when archiving. Defaults to
+                ["*.nc"] if not provided.
+            follow_symlinks (bool): Whether to follow symlinks when archiving. Defaults to False.
+            overwrite (bool): Whether to overwrite existing archives. Defaults to False.
+        """
+        if exclude_dirs is None:
+            exclude_dirs = [".svn", "share"]
+        if exclude_files is None:
+            exclude_files = ["*.nc"]
+        super().archive_experiments(
+            exclude_dirs=exclude_dirs,
+            exclude_files=exclude_files,
+            follow_symlinks=follow_symlinks,
+            overwrite=overwrite,
+        )
+
+    def profiling_logs(self, path: Path, run_path: Path | None = None) -> dict[str, dict[int, ProfilingLog]]:
+        """Returns all profiling logs from the specified path.
+
+        Args:
+            path (Path): Path to the experiment directory.
+            run_path (Path | None): Path to the Cylc run directory.
+        Returns:
+            dict[str, dict[int, ProfilingLog]]: Dictionary mapping log names to their logs, keyed by run number.
+                Cylc workflows have no concept of repeated runs, so every log is returned as the single run 0.
+        """
+        if run_path is None:
+            raise ValueError("Cylc run_path is required to locate profiling logs.")
+
+        logs = {}
+
+        # setup log paths
+        suite_log = run_path / "log/suite/log"  # cylc log file
+        cylcdb = run_path / "cylc-suite.db"  # database with task runtimes
+        jobdir = run_path / "log/job"  # where task logs are stored
+
+        logs["cylc_suite_log"] = ProfilingLog(suite_log, CylcProfilingParser())
+        # cylcdb.read_text = lambda x: x # hack to make log work
+        logs["cylc_tasks"] = ProfilingLog(cylcdb, CylcDBReader())
+
+        # Search for available profiling logs for the components in the configuration.
+        # matches <cycle> / <task> / NN / job.out e.g. 20220226T0000Z/Lismore_d1100_GAL9_um_fcst_000/NN/job.out
+        # NN is the last attempt
+        # job.out is the stdout
+        # this pattern is followed for all cylc workflows.
+        # as tasks of interest will likely have their own logging regions e.g. UM each task_cycle is
+        # treated as a "component" of the configuration.
+        possible_component_logs = list(jobdir.glob("*/*/NN/job.out"))
+        if not possible_component_logs:
+            raise RuntimeError(f"Could not find any known logs in {jobdir}")
+
+        for logfile in possible_component_logs:
+            cycle, task = logfile.parts[-4:-2]
+            for parser_name, parser in self.known_parsers.items():
+                logs[f"{task}_cycle{cycle}_{parser_name}"] = ProfilingLog(logfile, parser, optional=True)
+
+        # Cylc workflows have no concept of repeated runs, so every log is registered as the single run 0.
+        return {name: {0: log} for name, log in logs.items()}

access/profiling/cylc_parser.py

@@ -0,0 +1,146 @@
+# Copyright 2025 ACCESS-NRI and contributors. See the top-level COPYRIGHT file for details.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Parser for Cylc log files. The data to be parsed is written in the following form:
+
+2025-10-17T00:51:12Z INFO - Suite server: url=... pid=152868
+2025-10-17T00:51:12Z INFO - Run: (re)start=0 log=1
+2025-10-17T00:51:12Z INFO - Cylc version: 7.9.9
+2025-10-17T00:51:12Z INFO - Run mode: live
+2025-10-17T00:51:12Z INFO - Initial point: 20220226T0000Z
+2025-10-17T00:51:12Z INFO - Final point: 20220226T0300Z
+2025-10-17T00:51:12Z INFO - Cold Start 20220226T0000Z
+...
+2025-10-17T01:36:23Z INFO - Suite shutting down - AUTOMATIC
+2025-10-17T01:36:30Z INFO - DONE
+
+The differences between the first and last time-stamp are used to determine the
+total pipeline walltime.
+"""
+
+import os
+import sqlite3
+from datetime import datetime
+from pathlib import Path
+
+from access.profiling.metrics import tmax
+from access.profiling.parser import ProfilingParser, _read_text_file, _test_file
+
+
+class CylcProfilingParser(ProfilingParser):
+    """Cylc log profiling parser."""
+
+    _metrics = [tmax]
+
+    def parse(self, file_path: str | Path | os.PathLike) -> dict:
+        """Implements "parse" abstract method to parse the Cycle suite run log.
+
+        Args:
+            file_path (str | Path | os.PathLike): String containing the suite run log.
+
+        Returns:
+            dict: Parsed timing information.
+
+        Raises:
+            ValueError: when the last line does not contain "DONE".
+        """
+        lines = _read_text_file(file_path).splitlines()
+
+        first_line = lines[0]
+        last_line = lines[-1]
+
+        if "DONE" not in last_line:
+            raise ValueError("Cylc log is incomplete.")
+
+        try:
+            start_time = _extract_timestamp(first_line)
+        except Exception as e:
+            raise ValueError("First line of log doesn't contain a valid timestamp.") from e
+        try:
+            end_time = _extract_timestamp(last_line)
+        except Exception as e:
+            raise ValueError("Last line of log doesn't contain a valid timestamp.") from e
+
+        return {
+            "region": ["pipeline_elapsed_time"],
+            tmax: [int((end_time - start_time).total_seconds())],
+        }
+
+
+class CylcDBReader(ProfilingParser):
+    """Cylc database reader."""
+
+    _table = "task_jobs"
+    _required_cols = ("cycle", "name", "time_run", "time_run_exit", "run_status")
+    _metrics = [tmax]
+
+    def parse(self, file_path: str | Path | os.PathLike) -> dict:
+        """Implements "read" abstract method of CylcDBReader to parse the Cylc Rose task database.
+
+        Args:
+            file_path (str | Path | os.PathLike): The path to the SQLite database.
+
+        Returns:
+            dict: Read timing information.
+
+        Raises:
+            FileNotFoundError: When the provided database file doesn't exist.
+            RuntimeError: when the expected table is not present in the database or if the table doesn't have the
+                          expected column names.
+        """
+
+        dbpath = _test_file(file_path)
+
+        with sqlite3.connect(dbpath) as con:
+            cur = con.cursor()
+
+            # collect and validate table columns . Return type: list of tuples
+            # where each list item corresponds to a column. Each tuple is (index, name, type, ?, ?, primary key)
+            col_metadata = cur.execute(f"PRAGMA table_info({self._table})").fetchall()
+            if col_metadata == []:
+                raise RuntimeError(f"Table {self._table} not found in {dbpath}!")
+            col_map = {col_data[1]: col_data[0] for col_data in col_metadata}
+            columns_missing_from_tbl = set(self._required_cols) - set(col_map.keys())
+            if columns_missing_from_tbl:
+                raise RuntimeError(f"Expected table columns: {', '.join(columns_missing_from_tbl)}")
+
+            # collect table data
+            table_data = cur.execute(f"SELECT * FROM {self._table}").fetchall()
+
+        # turn timestamps into time elapsed (seconds)
+        data = {"region": []}
+        for m in self._metrics:
+            data[m] = []
+        for row in table_data:
+            # filter out tasks that haven't completed successfully
+            if row[col_map["run_status"]] == 0:
+                # region will look like <task>_<chunk no.>_cycle<cycle timestamp>
+                region = row[col_map["name"]] + "_cycle" + row[col_map["cycle"]]
+                start = row[col_map["time_run"]]
+                end = row[col_map["time_run_exit"]]
+                runtime = (_extract_timestamp(end) - _extract_timestamp(start)).total_seconds()
+                data["region"].append(region)
+                data[self._metrics[0]].append(runtime)
+
+        return data
+
+
+def _extract_timestamp(line: str) -> datetime:
+    """Helper function to extra and convert timestamp to datetime object.
+
+    Args:
+        line (str): The line of text with the timestamp at the beginning.
+
+    Raises:
+        ValueError: When there is no timestamp or the timestamp is inavlid.
+    """
+
+    timestamp = line.split()[0]
+    if timestamp.endswith("Z"):
+        timestamp = timestamp[:-1] + "+00:00"
+    try:
+        time = datetime.fromisoformat(timestamp)
+    except Exception as e:
+        raise ValueError("Invalid or missing timestamp") from e
+
+    return time