Add step by step example + fix typos

mlperf_logging/mllog/examples/power/README.md

@@ -1,7 +1,13 @@
 # Power measurement
 
+## Table of Contents <!-- omit in toc -->
+1. [power_measurement.py](#power_measurementpy)
+2. [Result Summarizer](#result-summarizer---computing-power-metric)
+3. [Step by step example](#step-by-step-example)
+
+
 ## [power_measurement.py](power_measurement.py)
-This script outputs the power logs in the mlperf format. It has two modes. First, you can provide a file containing the power logs in their native format (currently, only 'IMPI' and 'Bios' (csv) format are supported), and it will translate them into the mlperf format. Alternatively, you can run it in the debug mode and it will simulate the power reading in the specified format, and the translate the simulated power readings.
+This script outputs the power logs in the mlperf format. It has two modes. First, you can provide a file containing the power logs in their native format (currently, only 'IPMI' and 'Bios' (csv) format are supported), and it will translate them into the mlperf format. Alternatively, you can run it in the debug mode and it will simulate the power reading in the specified format, and the translate the simulated power readings.
 
 ### Usage
 ```
@@ -15,7 +21,7 @@ python power_measurement.py [--power-log <path_to_input_power_log>]
                             [--convertion-coef <convertion-coef>]
                             [--measurement-type <AC_or_DC>]
                             [--debug]
-                            [--log-type <IMPI_or_Bios>]
+                            [--log-type <IPMI_or_Bios>]
 ```
 
 #### Arguments
@@ -29,7 +35,7 @@ python power_measurement.py [--power-log <path_to_input_power_log>]
 - **convertion-coef:** Convertion coeffiecient, only applicable for AC.
 - **measurement-type:** Power measurement type. Either AC or DC.
 - **debug:** Flag to use debug mode. In debug mode, power readings will be simulated. The `power-log` argument is not needed in this mode.
-- **log-type:** Format type of the original power logs. Either IMPI or Bios.
+- **log-type:** Format type of the original power logs. Either IPMI or Bios.
 
 
 ## Result Summarizer - Computing power metric
@@ -46,16 +52,16 @@ Several functions have been added to the [result_summarizer.py](../../../result_
 │   │           ├── ...
 │   │           ├── result_n.txt
 │   │           └── power
-│   │               ├── result_0.txt
-│   │               ├── result_1.txt
+│   │               ├── result_0
+│   │               ├── result_1
 │   │                   ├── node_0.txt
 │   │                   ├── ...
 │   │                   ├── node_k.txt
 │   │                   ├── sw_0.txt
 │   │                   ├── ...
 │   │                   └── sw_m.txt
 │   │               ├── ...
-│   │               └── result_n.txt
+│   │               └── result_n
 │   └── systems                   
 └── ...
 ```
@@ -82,3 +88,39 @@ Computes the total energy used by the system in a single run using the previous
 
 ### Computing the power result
 Similar to the performance results, we perform and olympic average to compute the power result of the benchmark. This means the best and worst scores are dropped and the result is the average of the other ones.
+
+## Step by step examples
+
+### Producing a MLPerf power log
+1. Clone the `logging` repository, install it as a pip package:
+```
+git clone https://github.com/mlcommons/logging.git mlperf-logging --branch power_support
+pip install -e mlperf-logging
+```
+Then go into the `power` folder:
+```
+cd mlperf-logging/mlperf_logging/mllog/examples/power
+```
+2. Download the sample IPMI power readings from the MLCommons shared drive and place it inside the current folder. [Link](https://drive.google.com/file/d/1292hHqZqwjfPBFBaFIsC5hJRqcbB7Mas/view?usp=drive_link)
+
+3. Run the `power_measurement.py` python script using the following command:
+```
+python power_measurement.py --power-log IPMIPower.txt --output-log node_0.txt --log-type IPMI --start-with-readings
+```
+4. Check the output file `./output/power/node_0.txt`
+
+### Computing the metric for a single power log file
+It is assumed that you completed the previous example and you were able to produce a MLPerf power log.
+
+1. Run the `compute_metric_example.py` python script using the following command:
+```
+python compute_metric_example.py --input-log ./output/power/node_0.txt
+```
+2. The output of this should be 
+```
+Power consumed: 6514419.0
+```
+
+### Constructing a sample power submission
+It is assumed that you completed the first example and you were able to produce a MLPerf power log.
+**TODO:** Complete this example

mlperf_logging/mllog/examples/power/compute_metric_example.py

@@ -0,0 +1,33 @@
+import argparse
+from mlperf_logging.compliance_checker.mlp_parser import parse_file
+from mlperf_logging.result_summarizer.result_summarizer import _compute_power_node, _compute_power_sw
+
+def get_args():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--input-log", type=str, default=None)
+    parser.add_argument("--hardware-type", type=str, choices=["node", "sw"], default="node")
+    parser.add_argument("--ruleset", type=str, choices=["0.6.0", "0.7.0", "1.0.0", "1.1.0", "2.0.0", "2.1.0", "3.0.0"], default="3.0.0")
+    args = parser.parse_args()
+    return args
+
+
+if __name__ == "__main__":
+    args = get_args()
+    loglines, _ = parse_file(args.input_log, args.ruleset)
+    # Calculate time to train
+    run_start = None
+    run_stop = None
+    for logline in loglines:
+        if logline.key == 'power_measurement_start':
+            run_start = logline.timestamp
+        if logline.key == 'power_measurement_stop':
+            run_stop = logline.timestamp
+        if run_start is not None and run_stop is not None:
+            break
+    time_to_train = run_stop - run_start
+
+    if args.hardware_type == "node":
+        ans = _compute_power_node(loglines, time_to_train)
+    elif args.hardware_type == "sw":
+        ans = _compute_power_sw(loglines, time_to_train)
+    print(f"Power consumed: {ans}")

mlperf_logging/mllog/examples/power/power_measurement.py

@@ -43,7 +43,7 @@ def get_args():
     )
 
     parser.add_argument("--debug", action="store_true")
-    parser.add_argument("--log-type", choices=["IMPI", "Bios"], default="IMPI")
+    parser.add_argument("--log-type", choices=["IPMI", "Bios"], default="IPMI")
 
     args = parser.parse_args()
     return args
@@ -95,7 +95,7 @@ def convert2mlperf(self, s):
         # MLLOGGER.event(key=mllog_constants.INTERCONNECT_POWER_EST, value=power, time_ms=time_ms, metadata=dict(host = "sw_0"))
 
 
-class IMPIParser(LogParser):
+class IPMIParser(LogParser):
     def __init__(self, args) -> None:
         super().__init__(args)
         self.date_format = "%a %b %d %H:%M:%S %Y"
@@ -150,8 +150,8 @@ def run():
         power_reader = FilePowerReader(args)
 
     # Initilize log parser
-    if log_type == "IMPI":
-        log_parser = IMPIParser(args)
+    if log_type == "IPMI":
+        log_parser = IPMIParser(args)
     elif log_type == "Bios":
         log_parser = BiosParser(args)
     else:
@@ -184,7 +184,7 @@ def run():
         MLLOGGER.end(key=mllog_constants.POWER_MEASUREMENT_STOP)
     else:
         assert debug == False
-        s = log_parser.lines[-1]
+        s = power_reader.lines[-1]
         date = log_parser.extract_date(s)
         time_ms = log_parser.date_to_ms(date, log_parser.date_format)
         MLLOGGER.end(key=mllog_constants.POWER_MEASUREMENT_STOP, time_ms=time_ms)

mlperf_logging/mllog/examples/power/reader.py

@@ -19,8 +19,8 @@ def has_next(self):
 class DebugPowerReader(PowerReader):
     def __init__(self, args: dict) -> None:
         super().__init__()
-        self.format = args.get("log_type", "IMPI")
-        if self.format == "IMPI":
+        self.format = args.get("log_type", "IPMI")
+        if self.format == "IPMI":
             self.s = """Instantaneous power reading:                   {} Watts	    IPMI timestamp:                           {}"""
             self.date_format = "%a %b %d %H:%M:%S %Y"
         if self.format == "bios":
@@ -34,7 +34,7 @@ def __init__(self, args: dict) -> None:
 
     def read_power(self):
         self.readings += 1
-        if self.format == "IMPI":
+        if self.format == "IPMI":
             date = datetime.strftime(datetime.utcnow(), self.date_format)
             time.sleep(self.freq)
             return self.s.format(random.uniform(self.l, self.r), date)