Class IncrementalTimer

object --+
         |
        IncrementalTimer

Track absolute total and incremental wall and CPU time and,
optionally, times per item processed, possibly for several types
of item.  IncrementalTimer is intended for coarse-level monitoring
and reporting of times for various program stages, not for detailed
benchmarking or profiling.

In practice, the user initializes an instance, then, after each call
to update(), obtains the relevant timings from the public instance
variables.

Four times are always computed: total wall and cpu time accumulated
since initialization and incremental wall and cpu time since the
last call to update() or initialization.

In addition, an IncrementalTimer object can optionally compute
the same set of times per item processed, for an arbitrary number
of items. For example, when reading structures and computing their
unique SMILES, a timer can be told to compute not only the times, but
also the times per structure and times per unique SMILES encountered
on both a total and an incremental basis.  To track times per item,
the user specifies, at initialization time, a list of initial counts
(typically 0) for the various items whose times per item are to
be tracked.  On each call to update(), a corresponding list is
passed, giving the current values of the counts.  The list can be
passed as a positional first argument or as the value of a "counts="
keyword argument.

Initialization optionally takes a second keyword argument,
init_times_from, which specifies a pre-existing IncrementalTimer
instance whose initial times are to be used as the initial times
for the new instance. The intended use is for multiple timers that
should start off at the same time; for example, a timer for an
overall process and a timer for the first stage of the process.

The public instance variables (all floats) are:
    cpu: cpu time since initialization
    wall: wall time since initialization
    cpu_incr: cpu time since last update or initialization
    wall_incr: wall time since last update or initialization
    counts: array of counts since initialization
    counts_incr: array of counts since last update or initialization
    cpu_per_count: array of cpu times per count since initialization
    wall_per_count: array of cpu times per count since initialization
    cpu_per_count_incr:
      array of cpu times per count since last update or initialization
    wall_per_count_incr:
      array of wall times per count since last update or initialization
These are to be treated as read-only

If a value of count or incremental count is 0, the corresponding
time per count will be set to None.

The user may call the stop() method to temporarily stop a timer;
timing is resumed by calling the start() method.  An attempt to call
update() on a stopped timer raises a ValueError.

The cpu time is computed using the Python time.clock() function. In
32-bit UNIX executables, the clock rolls over approximately every
72 minutes.  We account for this roll-over, but the accounting
will fail unless some IncrementalTimer calls its update() method at
least once during every rollover interval. On Windows, or in 64-bit
UNIX executables, rollover should not be a problem.