numkit.observables — Observables as quantities with errors — GromacsWrapper 0.5.0-dev documentation

# `numkit.observables` — Observables as quantities with errors

Example showing how to use `QuantityWithError`:

      >>> from numkit.observables import QuantityWithError
      >>> a = QuantityWithError(2.0, 1.0)
      >>> a2 = QuantityWithError(2.0, 1.0)  # 2nd independent measurement of a
      >>> a3 = QuantityWithError(2.0, 1.0)  # 3rd independent measurement of a
      >>> b = QuantityWithError(-1, 0.5)
      >>> a+a
      4 (2)
      >>> a+a2
      4 (1.41421)
      >>> (a+a+a)/3
      2 (1)
      >>> (a+a2+a3)/3
      2 (0.57735)
      >>> a/b
      -2 (1.41421)

Note that each quantity has an identity: it makes a difference to the error of a combined quantity such as a+a if the inputs are independent measurements of the same.

See also

Various packages that describe quantities with units, in particular quantities.

class `numkit.observables.` `QuantityWithError`(value, error=None, qid=None, **kwargs)

  Number with error and basic error propagation arithmetic.

  The quantity is assumed to be a mean of an observable (`value`) with an associated (Gaussian) error `error` (which is the sqrt of the variance `variance` of the data).

  The covariance is not taken into account in the error propagation (i.e. all quantities are assumed to be uncorrelated) with the exception of the case of binary relations of the quantity with itself. For instance, a*a is correctly interpreted as a**2). However, this behaviour is not guaranteed to work for any complicated expression.

  static `asQuantityWithError`(other)

    Return a `QuantityWithError`.

    If the input is already a `QuantityWithError` then it is returned itself. This is important because a new quantity x’ would be considered independent from the original one x and thus lead to different error estimates for quantities such as x*x versus x*x’.

  `astuple`()

    Return tuple (value,error).

  `copy`()

    Create a new quantity with the same value and error.

  `deepcopy`()

    Create an exact copy with the same identity.

  `isSame`(other)

    Check if other is 100% correlated with self.

    `True` if
      `- other is the same observable (instance)

        - other was derived from self without using any other independent quantities with errors, e.g.

              >>> a = QuantityWithError(1.0, 0.5)
              >>> b = a**2 - a*2
              >>> a.isSame(b)
              True

    `False` if
      - other is a scalar (without an error), or
      - other was computed from self without involvement of any other observables.

    TODO: | How should one treat the case when a quantity is used again in an operation, e.g.
        c = a + b
        d = c/a
    How to compute the error on d? What should the result for `c.isSame(a)` be?

`QuantityWithError.` `value`

  Value of the observable A, typically the mean of a number of observations, <A>.

`QuantityWithError.` `error`

  Error of the observable, typically the square root of the `QuantityWithError.variance` of the observations, sqrt(<(A-<A>)**2>).

  Changing the error automatically changes the `QuantityWithError.variance`.

`QuantityWithError.` `variance`

  Variance <(A-<A>)**2> of the observable. Changing the variance automatically changes the `QuantityWithError.error`.

class `numkit.observables.` `QID`

  Identity of a `QuantityWithError`.

  > QID(iterable) –> identity QID() –> `None`

  The anonymous identity is `None`, anything else is a `frozenset()`.

  The QID can contain arbitray (but unique) identifiers in the iterable; however, strings are treated as individual objects and not as iterables.

  The error arithmetic encapsulated by the operator-overloading of `QuantityWithError` builds new QIDs by accumulating QIDs of the terms of the expression. In a certain sense, the “history” of a quantity becomes its “identity”.