Provided by: power-calibrate_0.01.21-1_amd64 bug

NAME

       power-calibrate - a tool to calibrate power consumption.

SYNOPSIS

       power-calibrate [options]

DESCRIPTION

       Power-calibrate  calibrates  the  power  consumption of a mobile device that has a battery
       power source or a recent Intel processor using the  RAPL  (Running  Average  Power  Limit)
       interface.   It  will  attempt  to calculate the power usage of 1% of CPU utiltisation. If
       perf is available, power-calibrate will also attempt to estimate the power consumption  of
       1 CPU cycle and 1 CPU instruction.

OPTIONS

       power-calibrate options are as follow:

       -d     specify  the  delay  in  seconds  from starting a new test configuration and before
              starting the sampling. The default is 20 seconds, which is normally enough time  to
              allow the battery statistics to settle down during the current test.

       -e     Calibrate  for  each  CPU  run,  rather  than for all the CPUs.  By default, power-
              calibrate will run tests on all the CPUs and produce one set of results for all the
              runs.  While  this  provides  a  good  average  result,  it  may  be misleading for
              processors where power  utilisation  or  performance  is  not  uniform  across  the
              processors, for example, with hyperthreading.

       -h     show help.

       -n     specify a list CPU numbers to run on.  By default, the number of CPUs is determined
              automatically, but this option allows one to override  this  by  listing  the  CPUs
              (range 0..number of CPUs-1) using a comma separated list.

       -o file
              output results into a YAML formatted file.

       -p     show  progress.  This  will display the progress in terms of % completion of a test
              run and also % completion of the total run.  The progress is  based  on  work  done
              rather than on an accurate time estimate.

       -r secs
              Set  run duration. Normally, the default of 120 seconds is suitable for most laptop
              devices where discharge rates from the battery can be fairly accurately  determined
              over  this  duration.   Setting  this  to  a  shorter  duration  will  complete the
              calibration tests in less time but may be less accurate.

       -R     read power statistics from the RAPL (Running Average Power Limit) domains. This  is
              supported by recent Linux kernels and Sandybridge and later Intel processors.  This
              option just measures the per processor package power utilization so the readings do
              not cover the entire machine.

       -s samples
              specify  the  number of samples for the CPU (-c) test. The CPU test will measure 0%
              to 100% CPU loading across 1..number of CPUs. The number of test rounds to be  done
              per  CPU  is  controlled  by  the  samples value.  If samples is low then less data
              points are gathered for the calculation of the power utilisation and this leads  to
              less accurate results.

OUTPUT

       During   the   testing/data  sampling  phase,  power-calibrate  will  show  the  following
       information:

       Column    Description
       CPU load  The loading of each CPU in terms of % utilisation for each CPU and the number of
                 CPUs being loaded. For example, 80% x 2 means 2 CPUs each at 80% utilisation and
                 for an 8 CPU machine this is effectivly 20% total utilisation since 6 other CPUs
                 are idle.
       User      % load of the CPU consumed by user space programs.
       Sys       % load of the CPU consumed by the kernel.
       Idle      % idle time of the CPU.
       Ctxt/s    Context switches per second.
       IRQ/s     Interrupts per second.
       Ops/s     Bogo operations per second.  This is the number of compute operations per second
                 (computation of a random number using a 32 bit multiple-with-carry).
       Watts     Power used in Watts.

       The following is an example of the output for the -c option:

       Power (Watts) = (% CPU load * 0.424631) + 10.131925
       Each 1% CPU load is about 424.63 mW (about 37.87 mA @ 11.21 V)
       Coefficient of determination R^2 = 0.999015 (very strong)

       Power (Watts) = (bogo op * 4.267444e-08) + 10.666399
       1 bogo ops is about 42.67 nW (about 3.81 nA @ 11.21 V)
       Coefficient of determination R^2 = 0.999460 (very strong)

       Power-calibrate will determine a suitable way of calculating the power consumed  based  on
       the CPU load and an estimation of the amount of power consumed for each 1% of CPU loading.

       The  Coefficient  of determination shows how close the results are to the measured data; a
       perfect match results in R^2 = 1.0 and this will drop towards zero as the accuracy  drops.
       Power-calibrate  will  annotate  R^2  to  provide some hint on how strong the relationship
       between the raw data and the linear estimation of power consumption.

       An estimate of the power used per bogo-op is estimated, that is,  the  power  consumed  to
       perform  1  computation of a random number using a 64 bit multiple-with-carry. This can be
       used a very naïve compute benchmarking metric when comparing different processors or power
       configurations.

EXAMPLES

       power-calibrate -d 60 -s 5 -n 0,1 -r 200 -p
              Measure  Watts  per 1% CPU (and bogo compute ops per Watt) with a 60 second warm-up
              delay per test round, 5 tests in the CPU load level (0%, 25%, 50%,  75%,  100%)  on
              CPUs 0 and 1 with a 200 second run time per test round while showing progress.

       power-calibrate -n 0,2,1,3
              Measure  Watts  per  1% CPU (and bogo compute oper per Watt) on 4 CPUs. 4 rounds of
              tests will be run for each CPU load interval, measuring:

                                         1 CPU:    CPU 0
                                         2 CPUs:   CPUs 0,2
                                         3 CPUs:   CPUs 0,2,1
                                         4 CPUs:   CPUs 0,2,1,3

       power-calibrate  -R -r 10 -d 5 -s 21 -n 0 -p
              Measure per-CPU package Watts consumed using the Intel RAPL interface. This example
              has  a  5  second warm-up delay per test round, 21 tests in the CPU load level (0%,
              5%, 10%, .., 95%, 100%) on CPUs 0 with a 10 second run time per  test  round  while
              showing progress.

BUGS

       Power-calibrate  attempts to find a linear relationship between power consumed and the CPU
       loading, bogo operations per second and the context switching.  This  is  not  necessarily
       the  case  for all processors. If the R^2 coefficient of determination is not close to 1.0
       then this indicates there may not be a linear relationship.

NOTES

       Power-calibrate relies on the battery interface to provide timely stats on  battery  power
       consumption and this will vary from device to device.  Software or firmware may adjust the
       battery readings from gas-gauges and even re-calibrate the  values  during  battery  drain
       hence  skewing  the  final results from power-calibrate.  Batteries also show a non-linear
       discharge characteristic, so running power-calibrate on low battery charge is not advised.

       Processors with hyperthreading or non-uniform processing performance will skew  the  bogo-
       ops calculations since different logical CPUs will vary in processing throughput.

       In  general,  the  more  samples  gathered,  the  more accurate the final results will be,
       however, the calibration will take longer to run.  With more samples, the tendency to  get
       a  few  random  outliers  in  the  samples may increase, and that may affect the final R^2
       coefficient of determination.

       Power-calibrate is a power estimation tool, so results will vary between  different  runs.
       It is not meant to be an accurate substitute for power measurements using a high precision
       multimeter.

SEE ALSO

       powerstat(8), eventstat(8)

AUTHOR

       power-calibrate was written by Colin King <colin.king@canonical.com>

       This manual page was written by Colin  King  <colin.king@canonical.com>,  for  the  Ubuntu
       project (but may be used by others).

COPYRIGHT

       Copyright © 2014-2016 Canonical Ltd.
       This  is  free software; see the source for copying conditions.  There is NO warranty; not
       even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

                                           18 May, 2015                        POWER-CALIBRATE(8)