wattameter 0.5.0__tar.gz

wattameter-0.5.0/LICENSE

@@ -0,0 +1,26 @@
+Copyright (c) 2025, Alliance for Sustainable Energy, LLC. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+- Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+- Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+- Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

wattameter-0.5.0/MANIFEST.in

@@ -0,0 +1 @@
+include src/wattameter/utils/*.sh

wattameter-0.5.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: wattameter
+Version: 0.5.0
+Summary: Default template for PDM package
+Author-email: Weslley da Silva Pereira <wdasilv@nrel.gov>
+License: BSD-3-Clause
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: codecarbon>=3.0.0
+Dynamic: license-file
+
+[![CI](https://github.com/NREL/WattAMeter/actions/workflows/ci.yml/badge.svg)](https://github.com/NREL/WattAMeter/actions/workflows/ci.yml)
+
+# WattAMeter
+
+**wattameter** is a Python package for monitoring and recording power consumption over time, enabling users to collect time series data on CPU, GPU, and RAM power usage. It also estimates energy consumption and CO₂ emissions.
+
+## Features
+
+- Track power usage for CPU, GPU, and RAM
+- Periodically log power data to file
+- Estimate energy consumption and CO₂ emissions
+- Customizable logging and output options
+- Command-line interface for easy usage
+
+## Installation
+
+You can install **wattameter** via pip:
+
+```bash
+pip install wattameter
+```
+
+## Usage
+
+### As a Python module
+
+```python
+from wattameter.power_tracker import PowerTracker
+
+tracker = PowerTracker(
+    country_iso_code="USA",
+    region="colorado",
+    measure_power_secs=1,
+    api_call_interval=3600,
+    output_dir=".",
+    output_file="emissions_data.csv",
+    output_power_file="power_data.log",
+)
+tracker.start()
+# ... your code ...
+tracker.stop()
+```
+
+### Command-line interface
+
+```sh
+wattameter \
+    --machine-id id \
+    --dt-read 1 \
+    --freq-write 3600 \
+    --log-level info \
+    --country USA \
+    --region colorado
+```
+
+| Option       | Short | Default  | Description                                              |
+| ------------ | ----- | -------- | -------------------------------------------------------- |
+| --machine-id | -i    | None     | Unique identifier for the machine (used in output files) |
+| --dt-read    | -t    | 1        | Time interval (seconds) for reading power data           |
+| --freq-write | -f    | 3600     | Frequency (reads) for writing power data to file         |
+| --log-level  | -l    | warning  | Logging level: debug, info, warning, error, critical     |
+| --country    | -c    | USA      | ISO code of the country for CO₂ emissions tracking       |
+| --region     | -r    | colorado | Region for CO₂ emissions tracking                        |
+| --help       | -h    |          | Show the help message and exit                           |
+
+### Command-line interface with SLURM
+
+For asynchronous usage with SLURM, we recommend using our [wattameter.sh](src/wattameter/utils/wattameter.sh) script as in [examples/slurm.sh](examples/slurm.sh), i.e.,
+
+```bash
+#SBATCH --signal=USR1@0 # Send USR1 signal at the end of the job to stop wattameter
+#SBATCH --mem-per-cpu=1G # Should be set according to your needs
+
+# Load Python environment with wattameter installed...
+
+# Get the path of the wattameter script
+WATTAPATH=$(python -c 'import wattameter; import os; print(os.path.dirname(wattameter.__file__))')
+WATTASCRIPT="${WATTAPATH}/utils/wattameter.sh"
+WATTAWAIT="${WATTAPATH}/utils/wattawait.sh"
+
+# Run wattameter on all nodes
+srun --overlap --wait=0 --nodes=$SLURM_JOB_NUM_NODES --ntasks-per-node=1 "${WATTAWAIT}" &
+WAIT_PID=$!
+srun --overlap --wait=0 --output=slurm-$SLURM_JOB_ID-wattameter.txt --nodes=$SLURM_JOB_NUM_NODES --ntasks-per-node=1 "${WATTASCRIPT}" -i $SLURM_JOB_ID \
+    [-t dt_read] \
+    [-f freq_write] \
+    [-l log_level] \
+    [-c country] \
+    [-r region] \
+    &
+wait $WAIT_PID
+
+# Run your script here...
+
+# Cancel the job to stop wattameter
+scancel $SLURM_JOB_ID
+```
+
+Almost all options are the same as the regular command-line interface. The exception is that the `--machine-id` option is replaced with `--run-id`, which is used to identify the SLURM job run. The script will automatically handle the output file naming based on the provided run ID and node information.
+
+## Contributing
+
+Contributions are welcome! Please open issues or submit pull requests.
+
+## License
+
+This project is planned to be licensed under the BSD-3-Clause License.
+
+## Acknowledgements
+
+- [CodeCarbon](https://github.com/mlco2/codecarbon) for emissions tracking and wrappers to energy tracking tools.
+
+---
+
+_NREL Software Record number: SWR-25-101_

wattameter-0.5.0/README.md

@@ -0,0 +1,115 @@
+[![CI](https://github.com/NREL/WattAMeter/actions/workflows/ci.yml/badge.svg)](https://github.com/NREL/WattAMeter/actions/workflows/ci.yml)
+
+# WattAMeter
+
+**wattameter** is a Python package for monitoring and recording power consumption over time, enabling users to collect time series data on CPU, GPU, and RAM power usage. It also estimates energy consumption and CO₂ emissions.
+
+## Features
+
+- Track power usage for CPU, GPU, and RAM
+- Periodically log power data to file
+- Estimate energy consumption and CO₂ emissions
+- Customizable logging and output options
+- Command-line interface for easy usage
+
+## Installation
+
+You can install **wattameter** via pip:
+
+```bash
+pip install wattameter
+```
+
+## Usage
+
+### As a Python module
+
+```python
+from wattameter.power_tracker import PowerTracker
+
+tracker = PowerTracker(
+    country_iso_code="USA",
+    region="colorado",
+    measure_power_secs=1,
+    api_call_interval=3600,
+    output_dir=".",
+    output_file="emissions_data.csv",
+    output_power_file="power_data.log",
+)
+tracker.start()
+# ... your code ...
+tracker.stop()
+```
+
+### Command-line interface
+
+```sh
+wattameter \
+    --machine-id id \
+    --dt-read 1 \
+    --freq-write 3600 \
+    --log-level info \
+    --country USA \
+    --region colorado
+```
+
+| Option       | Short | Default  | Description                                              |
+| ------------ | ----- | -------- | -------------------------------------------------------- |
+| --machine-id | -i    | None     | Unique identifier for the machine (used in output files) |
+| --dt-read    | -t    | 1        | Time interval (seconds) for reading power data           |
+| --freq-write | -f    | 3600     | Frequency (reads) for writing power data to file         |
+| --log-level  | -l    | warning  | Logging level: debug, info, warning, error, critical     |
+| --country    | -c    | USA      | ISO code of the country for CO₂ emissions tracking       |
+| --region     | -r    | colorado | Region for CO₂ emissions tracking                        |
+| --help       | -h    |          | Show the help message and exit                           |
+
+### Command-line interface with SLURM
+
+For asynchronous usage with SLURM, we recommend using our [wattameter.sh](src/wattameter/utils/wattameter.sh) script as in [examples/slurm.sh](examples/slurm.sh), i.e.,
+
+```bash
+#SBATCH --signal=USR1@0 # Send USR1 signal at the end of the job to stop wattameter
+#SBATCH --mem-per-cpu=1G # Should be set according to your needs
+
+# Load Python environment with wattameter installed...
+
+# Get the path of the wattameter script
+WATTAPATH=$(python -c 'import wattameter; import os; print(os.path.dirname(wattameter.__file__))')
+WATTASCRIPT="${WATTAPATH}/utils/wattameter.sh"
+WATTAWAIT="${WATTAPATH}/utils/wattawait.sh"
+
+# Run wattameter on all nodes
+srun --overlap --wait=0 --nodes=$SLURM_JOB_NUM_NODES --ntasks-per-node=1 "${WATTAWAIT}" &
+WAIT_PID=$!
+srun --overlap --wait=0 --output=slurm-$SLURM_JOB_ID-wattameter.txt --nodes=$SLURM_JOB_NUM_NODES --ntasks-per-node=1 "${WATTASCRIPT}" -i $SLURM_JOB_ID \
+    [-t dt_read] \
+    [-f freq_write] \
+    [-l log_level] \
+    [-c country] \
+    [-r region] \
+    &
+wait $WAIT_PID
+
+# Run your script here...
+
+# Cancel the job to stop wattameter
+scancel $SLURM_JOB_ID
+```
+
+Almost all options are the same as the regular command-line interface. The exception is that the `--machine-id` option is replaced with `--run-id`, which is used to identify the SLURM job run. The script will automatically handle the output file naming based on the provided run ID and node information.
+
+## Contributing
+
+Contributions are welcome! Please open issues or submit pull requests.
+
+## License
+
+This project is planned to be licensed under the BSD-3-Clause License.
+
+## Acknowledgements
+
+- [CodeCarbon](https://github.com/mlco2/codecarbon) for emissions tracking and wrappers to energy tracking tools.
+
+---
+
+_NREL Software Record number: SWR-25-101_

wattameter-0.5.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "wattameter"
+version = "0.5.0"
+description = "Default template for PDM package"
+authors = [
+    {name = "Weslley da Silva Pereira", email = "wdasilv@nrel.gov"},
+]
+dependencies = [
+    "codecarbon>=3.0.0",
+]
+requires-python = ">=3.9"
+readme = "README.md"
+license = {text = "BSD-3-Clause"}
+
+[project.scripts]
+wattameter = "wattameter.cli.main:main"
+wattameter_powerlog_filename = "wattameter.cli.main:print_powerlog_filename"
+wattameter_emissions_filename = "wattameter.cli.main:print_emissions_filename"
+
+[dependency-groups]
+example = [
+    "jupyter",
+    "matplotlib",
+    "py-cpuinfo",
+    "nvidia-ml-py",
+]
+test = [
+    "pytest",
+    "pytest-asyncio",
+]
+
+[tool.pdm]
+distribution = true
+package-dir = "src"
+includes = ["src/wattameter/utils/*.sh"]
+
+[tool.pdm.scripts]
+devwattameter = { call = "wattameter.cli.main:main" }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

wattameter-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wattameter-0.5.0/src/wattameter/__init__.py

@@ -0,0 +1,6 @@
+"""wattameter package"""
+
+__all__ = ["power_tracker", "cli", "utils", "PowerTracker"]
+
+from . import power_tracker, cli, utils
+from .power_tracker import PowerTracker

wattameter-0.5.0/src/wattameter/cli/__init__.py

@@ -0,0 +1,2 @@
+__all__ = ["main"]
+from . import main

wattameter-0.5.0/src/wattameter/cli/main.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: BSD-3-Clause
+# SPDX-FileCopyrightText: 2025, Alliance for Sustainable Energy, LLC
+
+from ..power_tracker import PowerTracker
+
+import signal
+import time
+import logging
+import argparse
+import threading
+
+
+class ForcedExit(BaseException):
+    """Exception raised for forced exit signals."""
+
+    pass
+
+
+signal_handled = threading.Event()
+
+
+def handle_signal(signum, frame):
+    """Handle termination signals."""
+    if signal_handled.is_set():  # Thread-safe read
+        return  # Ignore further signals
+    signal_handled.set()  # Thread-safe write
+    signame = signal.Signals(signum).name
+    raise ForcedExit(f"Signal handler called with signal {signame} ({signum})")
+
+
+def _suffix(machine_id=None):
+    """Generate a suffix based on the machine ID."""
+    if machine_id is not None:
+        return f"_{machine_id}"
+
+    # If no machine ID is provided, try to parse it from command line arguments
+    parser = argparse.ArgumentParser(exit_on_error=False)
+    parser.add_argument(
+        "--machine-id",
+        "-i",
+        type=str,
+        default=None,
+        help="Unique identifier for the machine used as suffix in the output files.",
+    )
+    machine_id = parser.parse_known_args()[0].machine_id
+
+    return "" if machine_id is None else f"_{machine_id}"
+
+
+def powerlog_filename(machine_id=None):
+    """Generate a log filename based on the machine ID."""
+    suffix = _suffix(machine_id)
+    return f"wattameter{suffix}.log"
+
+
+def print_powerlog_filename(machine_id=None):
+    """Print the power log filename based on the machine ID."""
+    print(powerlog_filename(machine_id))
+
+
+def emissions_filename(machine_id=None):
+    """Generate an emissions filename based on the machine ID."""
+    suffix = _suffix(machine_id)
+    return f"wattameter_emmisions{suffix}.csv"
+
+
+def print_emissions_filename(machine_id=None):
+    """Print the emissions filename based on the machine ID."""
+    print(emissions_filename(machine_id))
+
+
+def main():
+    # Register the signals to handle forced exit
+    for sig in (signal.SIGTERM, signal.SIGINT, signal.SIGUSR1, signal.SIGHUP):
+        signal.signal(sig, handle_signal)
+
+    # Parse command line arguments
+    parser = argparse.ArgumentParser(
+        description="Track power over time, energy and CO2 emissions from your computer."
+    )
+    parser.add_argument(
+        "--machine-id",
+        "-i",
+        type=str,
+        default=None,
+        help="Unique identifier for the machine used as suffix in the output files.",
+    )
+    parser.add_argument(
+        "--dt-read",
+        "-t",
+        type=float,
+        default=1,
+        help="Time interval in seconds for reading power data (default: 1 second).",
+    )
+    parser.add_argument(
+        "--freq-write",
+        "-f",
+        type=float,
+        default=3600,
+        help="Frequence for writing power data to file (default: every 3600 reads).",
+    )
+    parser.add_argument(
+        "--log-level",
+        "-l",
+        choices=["debug", "info", "warning", "error", "critical"],
+        default="warning",
+        help="Set the logging level (default: warning).",
+    )
+    parser.add_argument(
+        "--country",
+        "-c",
+        type=str,
+        default="USA",
+        help="ISO code of the country for CO2 emissions tracking (default: USA).",
+    )
+    parser.add_argument(
+        "--region",
+        "-r",
+        type=str,
+        default="colorado",
+        help="Region for CO2 emissions tracking (default: colorado).",
+    )
+    args = parser.parse_args()
+
+    # Set up logging
+    logging.basicConfig(level=args.log_level.upper())
+
+    # Initialize the tracker
+    tracker = PowerTracker(
+        # For CO2 emissions tracking
+        country_iso_code=args.country,
+        region=args.region,
+        # For power tracking
+        measure_power_secs=args.dt_read,
+        # For recording data
+        log_level=args.log_level.upper(),
+        # For saving power and energy data to file
+        api_call_interval=int(args.freq_write / args.dt_read),
+        output_dir=".",
+        output_file=emissions_filename(args.machine_id),
+        output_power_file=powerlog_filename(args.machine_id),
+    )
+
+    # Start tracking power and energy consumption
+    t0 = time.time()
+    tracker.start()
+
+    # Repeat until interrupted
+    try:
+        logging.info("Tracking power...")
+        while True:
+            time.sleep(86400)  # Sleep for a long time to keep the tracker running
+    except ForcedExit:
+        logging.info("Forced exit detected. Stopping tracker...")
+    finally:
+        tracker.stop()
+        t1 = time.time()
+        logging.info(f"Tracker stopped. Elapsed time: {t1 - t0:.2f} seconds.")
+
+
+if __name__ == "__main__":
+    main()  # Call the main function to start the tracker

wattameter-0.5.0/src/wattameter/power_tracker.py

@@ -0,0 +1,161 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# SPDX-FileCopyrightText: 2025, Alliance for Sustainable Energy, LLC
+
+from codecarbon import OfflineEmissionsTracker
+from codecarbon.external.hardware import CPU, GPU
+from codecarbon.external.ram import RAM
+from codecarbon.core.util import count_physical_cpus
+
+from collections import deque
+from typing import Optional
+from datetime import datetime
+import re
+import os
+
+
+class PowerTracker(OfflineEmissionsTracker):
+    """Power tracker based on the CodeCarbon offline emission tracker.
+
+    :param output_power_file: Optional path to the output file where power data
+        will be saved. If not provided, a default file named
+        `power_<run_id>.log` will be created.
+    :param time_fmt: Format for the time values in the output file.
+    :param power_fmt: Format for the power values in the output file.
+    """
+
+    def __init__(
+        self,
+        *args,
+        output_power_file: Optional[str] = None,
+        time_fmt: str = ".3e",
+        power_fmt: str = ".3e",
+        **kwargs,
+    ):
+        super().__init__(*args, **kwargs)
+
+        # Create queues to store power data
+        self._time_series = deque([])
+        self._timestamp_series = deque([])
+        self._power_series = {key: [] for key in ("cpu", "gpu", "ram")}
+        count_cpu = 0
+        count_gpu = 0
+        count_ram = 0
+        for hw in self._hardware:
+            if isinstance(hw, CPU):
+                assert count_cpu < 1, "Only one CPU object is supported."
+                if hw._mode == "intel_rapl":
+                    self._power_series["cpu"] = [
+                        deque([]) for _ in range(count_physical_cpus())
+                    ]
+                else:
+                    self._power_series["cpu"] = [deque([])]
+                count_cpu += 1
+            elif isinstance(hw, GPU):
+                assert count_gpu < 1, "Only one GPU object is supported."
+                self._power_series["gpu"] = [deque([]) for _ in range(hw.num_gpus)]
+                count_gpu += 1
+            elif isinstance(hw, RAM):
+                assert count_ram < 1, "Only one RAM object is supported."
+                self._power_series["ram"] = [deque([])]
+                count_ram += 1
+
+        # Initialize the last time written to file
+        if self._api_call_interval != -1:
+            self.output_power_file = (
+                f"power_{self.run_id}.log"
+                if output_power_file is None
+                else output_power_file
+            )
+            self.output_power_file = os.path.join(
+                self._output_dir, self.output_power_file
+            )
+            self._last_time_written = 0
+
+            # Get the format for time and power values
+            self.timestamp_fmt = "%Y-%m-%d_%H:%M:%S.%f"
+            self.time_fmt = time_fmt
+            self.power_fmt = power_fmt
+
+            # Write header to the power file
+            timestamp_str = datetime.now().strftime(self.timestamp_fmt)[:-3]
+            with open(self.output_power_file, "a", encoding="utf-8") as f:
+                f.write(f"# {timestamp_str} - Power data for run {self.run_id}\n")
+
+    def start(self) -> None:
+        super().start()
+
+        if self._api_call_interval != -1:
+            timestamp_str = datetime.now().strftime(self.timestamp_fmt)[:-3]
+
+            timestamp_len = len(timestamp_str)
+            time_len = len(f"{0:{self.time_fmt}}")
+            power_len = len(f"{0:{self.power_fmt}}")
+
+            with open(self.output_power_file, "a", encoding="utf-8") as f:
+                f.write(f"# {timestamp_str} - Tracking started\n")
+                f.write("# timestamp" + " " * (timestamp_len - 9))
+                f.write(" time (s)" + " " * (time_len - 8))
+                for i in range(len(self._power_series["cpu"])):
+                    f.write(f"{' cpu ' + str(i):>{power_len - 8}} (W)")
+                for i in range(len(self._power_series["gpu"])):
+                    f.write(f"{' gpu ' + str(i):>{power_len - 8}} (W)")
+                for i in range(len(self._power_series["ram"])):
+                    f.write(f"{' ram ' + str(i):>{power_len - 8}} (W)")
+                f.write("\n")
+
+    def _measure_power_and_energy(self) -> None:
+        """Specialization of the method from the parent class that keeps track
+        of the power for each component (CPU, GPU, RAM) and writes it to a file
+        periodically."""
+        # Measure power and energy consumption
+        # Save measure_occurrence before it is modified inside the method
+        measure_occurrence = self._measure_occurrence
+        super()._measure_power_and_energy()
+        timestamp_str = datetime.now().strftime(self.timestamp_fmt)[:-3]
+        measure_occurrence += 1
+
+        # Update power series
+        self._time_series.append(self._last_measured_time - self._start_time)
+        self._timestamp_series.append(timestamp_str)
+        for hw in self._hardware:
+            if isinstance(hw, CPU):
+                if hw._mode == "intel_rapl":
+                    all_cpu_details = hw._intel_interface.get_static_cpu_details()
+                    i = 0
+                    for metric, value in all_cpu_details.items():
+                        if re.match(r"^Processor Power", metric):
+                            self._power_series["cpu"][i].append(value)
+                            i += 1
+                else:
+                    self._power_series["cpu"][0].append(self._cpu_power.W)
+            elif isinstance(hw, GPU):
+                for i in range(hw.num_gpus):
+                    self._power_series["gpu"][i].append(hw.devices.devices[i].power.W)
+            elif isinstance(hw, RAM):
+                self._power_series["ram"][0].append(self._ram_power.W)
+
+        # Write power to file if needed
+        if (
+            self._api_call_interval != -1
+            and measure_occurrence >= self._api_call_interval
+        ) or self._scheduler is None:
+            n = len(self._time_series)
+            if n == self._last_time_written:
+                return
+
+            buffer = ""
+            for i in range(self._last_time_written, n):
+                buffer += "  " + self._timestamp_series[i]
+                buffer += f" {self._time_series[i]:{self.time_fmt}}"
+                for k in range(len(self._power_series["cpu"])):
+                    buffer += f" {self._power_series['cpu'][k][i]:{self.power_fmt}}"
+                for k in range(len(self._power_series["gpu"])):
+                    buffer += f" {self._power_series['gpu'][k][i]:{self.power_fmt}}"
+                for k in range(len(self._power_series["ram"])):
+                    buffer += f" {self._power_series['ram'][k][i]:{self.power_fmt}}"
+                buffer += "\n"
+
+            with open(self.output_power_file, "a", encoding="utf-8") as f:
+                f.write(buffer)
+
+            self._last_time_written = n

wattameter-0.5.0/src/wattameter/utils/__init__.py

@@ -0,0 +1,2 @@
+__all__ = ["codecarbon"]
+from wattameter.utils import codecarbon

wattameter-0.5.0/src/wattameter/utils/codecarbon.py

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# SPDX-FileCopyrightText: 2025, Alliance for Sustainable Energy, LLC
+
+import csv
+from importlib import resources
+
+
+def add_cpu(cpu_model: str, tdp: float) -> bool:
+    """
+    Add a CPU model and its TDP (Thermal Design Power) to codecarbon's CPU power database.
+
+    This function adds a new CPU entry to codecarbon's hardware database CSV file,
+    which is used for power consumption calculations. The function checks if the
+    CPU model already exists in the database before adding it to avoid duplicates.
+
+    Example usage:
+    .. code-block:: python
+        >>> add_cpu("Intel Xeon Platinum 8470QL", 95.0)
+        True
+        >>> add_cpu("Intel Xeon Platinum 8470QL", 95.0)  # Already exists
+        False
+
+    Note:
+        This function modifies the codecarbon package's internal CPU power database.
+        The changes will persist across sessions but may be overwritten when
+        codecarbon is updated.
+
+    :param cpu_model: The name/model of the CPU (e.g., "Intel Xeon Platinum 8470QL").
+    :param tdp: The Thermal Design Power of the CPU in watts.
+
+    :return: True if the CPU was successfully added to the database,
+             False if the CPU already existed in the database.
+    """
+    # Get the path to the CSV file using importlib.resources
+    with resources.path(
+        "codecarbon.data.hardware", "cpu_power.csv"
+    ) as cpu_power_csv_path:
+        # Check if the line already exists
+        line_exists = False
+        new_row = [cpu_model, str(tdp)]
+        with open(cpu_power_csv_path, "r", encoding="utf-8") as csvfile:
+            reader = csv.reader(csvfile)
+            for row in reader:
+                if row == new_row:
+                    line_exists = True
+                    break
+
+        # Only add the line if it doesn't already exist
+        if not line_exists:
+            with open(cpu_power_csv_path, "a", newline="", encoding="utf-8") as csvfile:
+                writer = csv.writer(csvfile)
+                writer.writerow(new_row)
+
+    return (
+        not line_exists
+    )  # Return True if the line was added, False if it already existed

wattameter-0.5.0/src/wattameter/utils/wattameter.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# SPDX-License-Identifier: BSD-3-Clause
+# SPDX-FileCopyrightText: 2025, Alliance for Sustainable Energy, LLC
+#
+# This script is used to run the WattAMeter CLI tool for power tracking.
+# It captures the output and PID of the process, allowing for graceful termination on timeout.
+
+get_log_file_name() {
+    NODE=$(hostname)
+    if [ -z "${RUN_ID}" ]; then
+        echo "wattameter-${NODE}.txt"
+    else
+        echo "wattameter-${RUN_ID}-${NODE}.txt"
+    fi
+}
+
+main() {
+    # Default values
+    RUN_ID=""
+    DT_READ=1
+    FREQ_WRITE=3600
+    LOG_LEVEL="warning"
+    COUNTRY="USA"
+    REGION="colorado"
+
+    # Find the WattAMeter CLI tool
+    if ! command -v wattameter 2>&1 >/dev/null; then
+        SCRIPTPATH="$( cd -- "$(dirname "$0")" >/dev/null 2>&1 ; pwd -P )"
+        if [ -f "${SCRIPTPATH}/../cli/main.py" ]; then
+            WATTAMETER="python ${SCRIPTPATH}/../cli/main.py"
+        else
+            echo "WattAMeter CLI not found. Please ensure it is installed and available in the path."
+            exit 1
+        fi
+    else
+        WATTAMETER=$(command -v wattameter)
+    fi
+
+    # Usage function to display help
+    usage() {
+        echo "Usage: $0 [-i run_id] [-t dt_read] [-f freq_write] [-l log_level] [-c country] [-r region]"
+        exit 1
+    }
+
+    # Parse command line options
+    while getopts ":i:t:f:l:c:r:" opt; do
+        case $opt in
+            i) RUN_ID="$OPTARG" ;;
+            t) DT_READ="$OPTARG" ;;
+            f) FREQ_WRITE="$OPTARG" ;;
+            l) LOG_LEVEL="$OPTARG" ;;
+            c) COUNTRY="$OPTARG" ;;
+            r) REGION="$OPTARG" ;;
+            \?) echo "Invalid option: -$OPTARG" >&2; usage ;;
+            :) echo "Option -$OPTARG requires an argument." >&2; usage ;;
+        esac
+    done
+
+    # Get the hostname of the current node
+    NODE=$(hostname)
+
+    # Use the log identifier name if provided
+    log_file=$(get_log_file_name)
+    echo "Logging execution on ${NODE} to ${log_file}"
+
+    # Kill other instances of CodeCarbon that might be running
+    find /tmp/ -name ".codecarbon.lock" 2>/dev/null | xargs rm -f
+
+    # Start the power series tracking and log the output
+    ${WATTAMETER} \
+        --machine-id "${NODE}" \
+        --dt-read "${DT_READ}" \
+        --freq-write "${FREQ_WRITE}" \
+        --log-level "${LOG_LEVEL}" \
+        --country "${COUNTRY}" \
+        --region "${REGION}" > "${log_file}" 2>&1 &
+    WATTAMETER_PID=$!
+
+    # Gracefully terminates the tracking process on exit.
+    on_exit() {
+        if [ -n "$EXITING" ]; then
+            return
+        fi
+        EXITING=1
+        echo "WattAMeter interrupted on ${NODE}!"
+        kill -TERM "$WATTAMETER_PID" 2>/dev/null
+        wait "$WATTAMETER_PID" 2>/dev/null
+        while kill -0 "$WATTAMETER_PID" 2>/dev/null; do
+            sleep 1
+        done
+        echo "WattAMeter has been terminated on node ${NODE}."
+    }
+    trap on_exit INT TERM HUP USR1
+    trap 'echo "WattAMeter exiting on ${NODE}..."' EXIT
+
+    # Wait for the WattAMeter process to finish
+    wait "$WATTAMETER_PID"
+}
+
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    main "$@"
+fi

wattameter-0.5.0/src/wattameter/utils/wattawait.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# SPDX-License-Identifier: BSD-3-Clause
+# SPDX-FileCopyrightText: 2025, Alliance for Sustainable Energy, LLC
+#
+# This script is used to wait for the WattAMeter timer to start before proceeding.
+
+# Record the timestamp of the script start
+START_TIME=$(date +%s)
+
+# Get the hostname of the current node
+NODE=$(hostname)
+
+# Check if an input filename was given
+if [ $# -ge 1 ]; then
+    WATTAMETER_FILENAME="$1"
+else
+    # Get the WattAMeter powerlog filename for the current node
+    WATTAMETER_FILENAME=$(wattameter_powerlog_filename --machine-id "${NODE}")
+fi
+
+# Wait for the WattAMeter powerlog file to be created or updated
+if [ -f "${WATTAMETER_FILENAME}" ]; then
+    # Check if the file was created after $START_TIME
+    FILE_CREATION_TIME=$(stat -c %W "${WATTAMETER_FILENAME}")
+    if [ "${FILE_CREATION_TIME}" -ge "${START_TIME}" ]; then
+        echo "${WATTAMETER_FILENAME} file created."
+    else
+        # Wait until the WattAMeter powerlog file is updated
+        LAST_MODIFIED="${START_TIME}"
+        while [ "${LAST_MODIFIED}" -le "${START_TIME}" ]; do
+            # Read the timestamp of the last modification
+            LAST_MODIFIED=$(stat -c %Y "${WATTAMETER_FILENAME}")
+            sleep 1  # Wait for 1 second before checking again
+        done
+        echo "${WATTAMETER_FILENAME} file updated."
+    fi
+else
+    # Wait for the WattAMeter-PowerLog-Filename CLI tool to create the file
+    until [ -f "${WATTAMETER_FILENAME}" ]; do
+        sleep 1
+    done
+    echo "${WATTAMETER_FILENAME} file created."
+fi

wattameter-0.5.0/src/wattameter.egg-info/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: wattameter
+Version: 0.5.0
+Summary: Default template for PDM package
+Author-email: Weslley da Silva Pereira <wdasilv@nrel.gov>
+License: BSD-3-Clause
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: codecarbon>=3.0.0
+Dynamic: license-file
+
+[![CI](https://github.com/NREL/WattAMeter/actions/workflows/ci.yml/badge.svg)](https://github.com/NREL/WattAMeter/actions/workflows/ci.yml)
+
+# WattAMeter
+
+**wattameter** is a Python package for monitoring and recording power consumption over time, enabling users to collect time series data on CPU, GPU, and RAM power usage. It also estimates energy consumption and CO₂ emissions.
+
+## Features
+
+- Track power usage for CPU, GPU, and RAM
+- Periodically log power data to file
+- Estimate energy consumption and CO₂ emissions
+- Customizable logging and output options
+- Command-line interface for easy usage
+
+## Installation
+
+You can install **wattameter** via pip:
+
+```bash
+pip install wattameter
+```
+
+## Usage
+
+### As a Python module
+
+```python
+from wattameter.power_tracker import PowerTracker
+
+tracker = PowerTracker(
+    country_iso_code="USA",
+    region="colorado",
+    measure_power_secs=1,
+    api_call_interval=3600,
+    output_dir=".",
+    output_file="emissions_data.csv",
+    output_power_file="power_data.log",
+)
+tracker.start()
+# ... your code ...
+tracker.stop()
+```
+
+### Command-line interface
+
+```sh
+wattameter \
+    --machine-id id \
+    --dt-read 1 \
+    --freq-write 3600 \
+    --log-level info \
+    --country USA \
+    --region colorado
+```
+
+| Option       | Short | Default  | Description                                              |
+| ------------ | ----- | -------- | -------------------------------------------------------- |
+| --machine-id | -i    | None     | Unique identifier for the machine (used in output files) |
+| --dt-read    | -t    | 1        | Time interval (seconds) for reading power data           |
+| --freq-write | -f    | 3600     | Frequency (reads) for writing power data to file         |
+| --log-level  | -l    | warning  | Logging level: debug, info, warning, error, critical     |
+| --country    | -c    | USA      | ISO code of the country for CO₂ emissions tracking       |
+| --region     | -r    | colorado | Region for CO₂ emissions tracking                        |
+| --help       | -h    |          | Show the help message and exit                           |
+
+### Command-line interface with SLURM
+
+For asynchronous usage with SLURM, we recommend using our [wattameter.sh](src/wattameter/utils/wattameter.sh) script as in [examples/slurm.sh](examples/slurm.sh), i.e.,
+
+```bash
+#SBATCH --signal=USR1@0 # Send USR1 signal at the end of the job to stop wattameter
+#SBATCH --mem-per-cpu=1G # Should be set according to your needs
+
+# Load Python environment with wattameter installed...
+
+# Get the path of the wattameter script
+WATTAPATH=$(python -c 'import wattameter; import os; print(os.path.dirname(wattameter.__file__))')
+WATTASCRIPT="${WATTAPATH}/utils/wattameter.sh"
+WATTAWAIT="${WATTAPATH}/utils/wattawait.sh"
+
+# Run wattameter on all nodes
+srun --overlap --wait=0 --nodes=$SLURM_JOB_NUM_NODES --ntasks-per-node=1 "${WATTAWAIT}" &
+WAIT_PID=$!
+srun --overlap --wait=0 --output=slurm-$SLURM_JOB_ID-wattameter.txt --nodes=$SLURM_JOB_NUM_NODES --ntasks-per-node=1 "${WATTASCRIPT}" -i $SLURM_JOB_ID \
+    [-t dt_read] \
+    [-f freq_write] \
+    [-l log_level] \
+    [-c country] \
+    [-r region] \
+    &
+wait $WAIT_PID
+
+# Run your script here...
+
+# Cancel the job to stop wattameter
+scancel $SLURM_JOB_ID
+```
+
+Almost all options are the same as the regular command-line interface. The exception is that the `--machine-id` option is replaced with `--run-id`, which is used to identify the SLURM job run. The script will automatically handle the output file naming based on the provided run ID and node information.
+
+## Contributing
+
+Contributions are welcome! Please open issues or submit pull requests.
+
+## License
+
+This project is planned to be licensed under the BSD-3-Clause License.
+
+## Acknowledgements
+
+- [CodeCarbon](https://github.com/mlco2/codecarbon) for emissions tracking and wrappers to energy tracking tools.
+
+---
+
+_NREL Software Record number: SWR-25-101_

wattameter-0.5.0/src/wattameter.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+src/wattameter/__init__.py
+src/wattameter/power_tracker.py
+src/wattameter.egg-info/PKG-INFO
+src/wattameter.egg-info/SOURCES.txt
+src/wattameter.egg-info/dependency_links.txt
+src/wattameter.egg-info/entry_points.txt
+src/wattameter.egg-info/requires.txt
+src/wattameter.egg-info/top_level.txt
+src/wattameter/cli/__init__.py
+src/wattameter/cli/main.py
+src/wattameter/utils/__init__.py
+src/wattameter/utils/codecarbon.py
+src/wattameter/utils/wattameter.sh
+src/wattameter/utils/wattawait.sh

wattameter-0.5.0/src/wattameter.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

wattameter-0.5.0/src/wattameter.egg-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+wattameter = wattameter.cli.main:main
+wattameter_emissions_filename = wattameter.cli.main:print_emissions_filename
+wattameter_powerlog_filename = wattameter.cli.main:print_powerlog_filename

wattameter-0.5.0/src/wattameter.egg-info/requires.txt

@@ -0,0 +1 @@
+codecarbon>=3.0.0

wattameter-0.5.0/src/wattameter.egg-info/top_level.txt

@@ -0,0 +1 @@
+wattameter