API Documentation

Subpackages

• wattameter.cli package
  • wattameter.cli.main module
    • main()
  • wattameter.cli.utils module
    • ForcedExit
    • default_cli_arguments()
    • handle_signal()
    • parse_tracker_spec()
    • powerlog_filename()
    • print_powerlog_filename()
• wattameter.readers package
  • wattameter.readers.base module
    • BaseReader
      • BaseReader.compute_derived()
      • BaseReader.derived_quantities
      • BaseReader.derived_tags
      • BaseReader.get_unit()
      • BaseReader.read()
      • BaseReader.tags
  • wattameter.readers.nvml module
    • DataThroughput
      • DataThroughput.units()
    • NVMLReader
      • NVMLReader.devices
      • NVMLReader.UNITS
      • NVMLReader.get_unit()
      • NVMLReader.read()
      • NVMLReader.read_energy()
      • NVMLReader.read_energy_on_device()
      • NVMLReader.read_nvlink_throughput()
      • NVMLReader.read_nvlink_throughput_on_device()
      • NVMLReader.read_power()
      • NVMLReader.read_power_on_device()
      • NVMLReader.read_temperature()
      • NVMLReader.read_temperature_on_device()
      • NVMLReader.read_utilization()
      • NVMLReader.read_utilization_on_device()
      • NVMLReader.tags
  • wattameter.readers.rapl module
    • RAPLDevice
      • RAPLDevice.path
      • RAPLDevice.name
      • RAPLDevice.max_energy_range
      • RAPLDevice.compute_derived()
      • RAPLDevice.derived_quantities
      • RAPLDevice.derived_tags
      • RAPLDevice.get_unit()
      • RAPLDevice.read()
      • RAPLDevice.read_energy()
      • RAPLDevice.tags
    • RAPLReader
      • RAPLReader.rapl_dir
      • RAPLReader.devices
      • RAPLReader.compute_derived()
      • RAPLReader.derived_quantities
      • RAPLReader.derived_tags
      • RAPLReader.get_unit()
      • RAPLReader.read()
      • RAPLReader.read_energy()
      • RAPLReader.read_energy_on_device()
      • RAPLReader.tags
  • wattameter.readers.utils module
    • Byte
      • Byte.symbol()
      • Byte.to_si()
    • Celsius
      • Celsius.symbol()
      • Celsius.to_si()
    • Energy
      • Energy.units()
    • Joule
      • Joule.symbol()
      • Joule.to_si()
    • Power
      • Power.units()
    • Quantity
      • Quantity.units()
    • SIPrefix
      • SIPrefix.GIBI
      • SIPrefix.GIGA
      • SIPrefix.KIBI
      • SIPrefix.KILO
      • SIPrefix.MEGA
      • SIPrefix.MIBI
      • SIPrefix.MICRO
      • SIPrefix.MILLI
      • SIPrefix.NANO
      • SIPrefix.NONE
      • SIPrefix.PEBI
      • SIPrefix.TEBI
      • SIPrefix.TERA
      • SIPrefix.from_string()
    • Second
      • Second.symbol()
      • Second.to_si()
    • Temperature
      • Temperature.units()
    • Unit
      • Unit.symbol()
      • Unit.to_si()
    • Utilization
      • Utilization.units()
    • Watt
      • Watt.symbol()
      • Watt.to_si()
    • WattHour
      • WattHour.symbol()
      • WattHour.to_si()
• wattameter.utils package
  • wattameter.utils.postprocessing module
    • align_and_concat_df()
    • file_to_df()
  • wattameter.utils.wattameter module
  • wattameter.utils.wattawait module
  • wattameter.utils.slurm module
• wattameter.benchmark package
  • wattameter.benchmark.overhead module
    • benchmark_dynamic_overhead()
    • benchmark_static_overhead()
    • run_benchmark()
  • wattameter.benchmark.update_time module
    • benchmark_pynvml_update_time()
    • benchmark_rapl_update_time()
    • run_benchmark()
  • wattameter.benchmark.utils module
    • compile_gpu_burn()
    • estimate_dt()
    • get_cpu_info()
    • print_system_info()
    • stress_cpu()

wattameter.tracker module

class wattameter.tracker.BaseTracker(dt_read: float = 1.0) → None

Bases: AbstractContextManager

Base class for trackers that read data at a specified frequency.

Parameters:

dt_read (float) – Time interval (in seconds) between consecutive readings. (default: 1.0)

abstractmethod read() → float

Read data.

Return type:

float

Returns:

Time taken for the reading (in seconds).

start(freq_write: int = 0)

Start asynchronous task _update_series().

Parameters:

freq_write (int) – Frequency (in number of reads) to write the collected data. If set to 0, data is never written. (default: 0)

stop(freq_write: int = 0)

Stop async task _update_series() and reads data one last time.

On exit, perform a final read and write of the collected data.

Parameters:

freq_write (int) – Frequency (in number of reads) to write the collected data. If set to 0, data is never written. (default: 0)

track_until_forced_exit(freq_write: int = 0, *args, **kwargs)

Track data as the main task of the program until a forced exit.

On exit, perform a final read and write of the collected data.

Note

This is the preferred way to track data of programs that are being executed in the machine. This method will block the main thread until a forced exit is detected (e.g., SIGINT or SIGTERM).

Parameters:

freq_write (int) – Frequency (in number of reads) to write the collected data. If set to 0, data is never written. (default: 0)

abstractmethod write() → None

Write data.

Return type:

None

abstractmethod write_header() → None

Write header.

Return type:

None

class wattameter.tracker.Tracker(reader: BaseReader, dt_read: float = 1.0, freq_write: int = 3600, output=None) → None

Bases: BaseTracker

Generic tracker that reads data from a BaseReader at a specified frequency.

Parameters:

• reader (BaseReader) – An instance of BaseReader to read data from.

• dt_read (float) – Time interval (in seconds) between consecutive readings. (default: 1.0)

• freq_write (int) – Frequency (in number of reads) to write the collected data. If set to 0, data is never written. (default: 3600)

• output – Optional output stream to write the collected data. If not provided, the output stream is as defined in output(). (default: None)

reader

An instance of BaseReader that provides the data to be tracked.

time_series

A deque that stores the timestamps of the readings.

reading_time

A deque that stores the time taken for each reading (in nanoseconds). This information can be useful for adjusting the reading frequency. Usually, the time taken for reading should be much smaller than dt_read.

data

A deque that stores the data read from the reader.

freq_write

Frequency (in number of reads) to write the collected data. If set to 0, data is never written.

flush_data()

Flush all collected data from the tracker.

Returns:

A tuple containing three lists:

• time_series: List of timestamps (in nanoseconds).

• reading_time: List of time taken for each reading (in nanoseconds).

• data: 2D array of the collected data. Each row corresponds to a reading, and each column corresponds to a quantity read by the reader.

format_timestamp(timestamp_ns: int) → str

Format a timestamp in nanoseconds to a human-readable string.

Parameters:

timestamp_ns (int) – Timestamp in nanoseconds.

Return type:

str

property output

Output file to write the collected data.

read() → float

Read data.

Return type:

float

Returns:

Time taken for the reading (in seconds).

track_until_forced_exit()

Track data as the main task of the program until a forced exit.

On exit, perform a final read and write of the collected data.

Note

This is the preferred way to track data of programs that are being executed in the machine. This method will block the main thread until a forced exit is detected (e.g., SIGINT or SIGTERM).

Parameters:

freq_write – Frequency (in number of reads) to write the collected data. If set to 0, data is never written.

write()

Write data.

write_data(time_series, reading_time, data)

Write the collected data to the output stream.

Parameters:

• time_series – Array of timestamps (in nanoseconds).

• reading_time – Array of time taken for each reading (in nanoseconds).

• data – 2D array of the collected data. Each row corresponds to a reading, and each column corresponds to a quantity read by the reader.

write_header()

Write the header to the output stream.

class wattameter.tracker.TrackerArray(readers: list[BaseReader], dt_read: float = 1.0, freq_write: int = 3600, outputs: list = []) → None

Bases: BaseTracker

Tracker that manages multiple Tracker instances.

Parameters:

• readers (list[BaseReader]) – List of BaseReader instances to read data from.

• dt_read (float) – Time interval (in seconds) between consecutive readings. (default: 1.0)

• freq_write (int) – Frequency (in number of reads) to write the collected data. If set to 0, data is never written. (default: 3600)

• outputs (list) – List of output streams for each tracker. If not provided, the output streams are as defined in each tracker’s output(). (default: [])

trackers

List of Tracker instances managed by this tracker.

freq_write

Frequency (in number of reads) to write the collected data. If set to 0, data is never written.

read() → float

Read data.

Return type:

float

Returns:

Time taken for the reading (in seconds).

track_until_forced_exit()

Track data as the main task of the program until a forced exit.

On exit, perform a final read and write of the collected data.

Note

This is the preferred way to track data of programs that are being executed in the machine. This method will block the main thread until a forced exit is detected (e.g., SIGINT or SIGTERM).

Parameters:

freq_write – Frequency (in number of reads) to write the collected data. If set to 0, data is never written.

write()

Write data.

write_header() → None

Write header.

Return type:

None