Provided by: power-calibrate_0.01.25-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  (one  may  need  to  run  as  root  or  set
       /proc/sys/kernel/perf_event_paranoid to below 2 for this to work).

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-2017 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.

                                          15 April, 2017                       POWER-CALIBRATE(8)