# Bumps 0.7.14 documentation

## history - Optimizer evaluation trace

`History` | Collection of traces.
`Trace` | Value trace.

Log of progress through a computation.

Each cycle through a computation, a process can update its history, adding information about the number of function evaluations, the total time taken, the set of points evaluated and their values, the current best value and so on. The process can use this history when computing the next set of points to evaluate and when checking if the termination conditions are met. Any values that may be useful outside the computation, e.g., for logging or for updating the user, should be recorded. In the ideal case, the history is all that is needed to restart the process in case of a system crash.

History consists of a set of traces. The content of the traces themselves is provided by the computation, but various stake holders can use them. For example, the user may wish to log the set of points that have been evaluated and their values using the system logger and an optimizer may require a certain amount of history to calculate the next set of values.

New traces are provided using `History.provides()`. For example, the following adds traces for ‘value’ and ‘point’ to the history, and requires the best value on the two previous cycles in order to do its work:

    >>> from bumps.history import History
    >>> h = History()
    >>> h.provides(value=2, point=0)

Initially the history is empty:

    >>> print(len(h.value))
    0

After three updates we see that only two values are kept:

    >>> h.update(value=2,point=[1,1,1])
    >>> h.update(value=1,point=[1,0.5,1])
    >>> h.update(value=0.5,point=[1,0.5,0.9])
    >>> print(h.value)
    Trace value: 0.5, 1
    >>> print(len(h.value))
    2

Note that point is not monitored since it is not required:

    >>> print(h.point[0])
    Traceback (most recent call last):
        ...
    IndexError: point has not accumulated enough history

Traces may be used as accumulators. In that case, the next value is added to the tail value before appending to the trace. For example:

    >>> h = History()
    >>> h.provides(step=1)
    >>> h.accumulate(step=1)
    >>> h.accumulate(step=1)
    >>> print(h.step[0])
    2

class `bumps.history.``History`(**kw)

  Bases: `object`

  Collection of traces.

  Provided traces can be specified as key word arguments, name=length.

  `accumulate`(**kw)

    Extend the given traces with the provided values. The traced value will be the old value plus the new value.

  `clear`()

    Clear history, removing all traces

  `provides`(**kw)

    Specify additional provided fields.

    Raises AttributeError if trace is already provided or if the trace name matches the name of one of the history methods.

  `requires`(**kw)

    Specify required fields, and their history length.

  `restore`(state)

    Restore history to the state returned by a call to snapshot

  `snapshot`()

    Return a dictionary of traces { ‘name’: [v[n], v[n-1], …, v[0]] }

  `update`(**kw)

    Extend the given traces with the provided values. The traced values are independent. Use accumulate if you want to add the new value to the previous value in the trace.

class `bumps.history.``Trace`(keep=1, name='trace')

  Bases: `object`

  Value trace.

  This is a stack-like object with items inserted at the beginning, and removed from the end once the maximum length keep is reached.

  len(trace) returns the number of items in the trace trace[i] returns the ith previous element in the history trace.requires(n) says how much history to keep trace.put(value) stores value trace.accumulate(value) adds value to the previous value before storing state = trace.snapeshot() returns the values as a stack, most recent last trace.restore(state) restores a snapshot

  Note that snapshot/restore uses lists to represent numpy arrays, which may cause problems if the trace is capturing lists.

  `accumulate`(value)
  `put`(value)

    Add an item to the trace, shifting off from the beginning when the trace is full.

  `requires`(n)

    Set the trace length to be at least n.

  `restore`(state)

    Restore a trace from a captured snapshot.

    Lists are converted to numpy arrays.

  `snapshot`()

    Capture state of the trace.

    Numpy arrays are converted to lists so that the trace can be easily converted to json.