Interval Arithmetic in Python

This library provides a Python implementation of an algebraically closed interval system on the extended real number set. An interval object consists of a finite union of closed, possibly unbound, mathematical intervals.

Installation

The most convenient way to install this library is by means of easy_install:

easy_install pyinterval

Alternatively, it is possible to download the sources from PyPI and invoking

python setup.py install

in the unpacked directory. Note that you need the crlibm library installed on your system. It is also possible to check-out the sources from the subversion repository:

svn checkout http://pyinterval.googlecode.com/svn/trunk/ pyinterval

Using intervals

The interval package can be loaded into the Python interpreter with the statement

>>> from interval import interval, inf, imath

which injects in the current namespace the interval class, a constant representing the mathematical infinity, and a module providing interval transcendetal functions.

Intervals are immutable objects that can be created by specifying their connected components:

>>> k = interval([0, 1], [2, 3], [10, 15])

creates an object representing the union of the mathematical intervals [0, 1], [2, 3] and [10, 15].

>>> interval[1, 2]
interval([1.0, 2.0])

represents the mathematical interval [1, 2], not be confused with the union of the one-point intervals {1} and {2}:

>>> interval(1, 2)
interval([1.0], [2.0])

An interval consisting of only one number can be instantiated with either forms:

>>> interval(1), interval[1]
(interval([1.0]), interval([1.0]))

An empty interval has no components:

>>> interval()
interval()

Operations

Intervals can be added:

>>> interval[1, 2] + interval[4, 5]
interval([5.0, 7.0])

subtracted:

>>> interval[5, 7] - interval[1, 2]
interval([3.0, 6.0])

multiplied:

>>> interval[0, 2] * interval[4, inf]
interval([-inf, inf])

divided:

>>> interval[1]/interval[3]
interval([0.33333333333333331, 0.33333333333333337])

inersected:

>>> interval[1, 4] & interval[2, 5]
interval([2.0, 4.0])

unioned:

>>> interval[1, 4] | interval[2, 5]
interval([1.0, 5.0])

>>> interval[1, 2] | interval[4, 5]
interval([1.0, 2.0], [4.0, 5.0])

raised to integer power:

>>> interval[-3, 2] ** 2
interval([0.0, 9.0])

Scalar numbers are automatically cast as interval when used as operands together with intervals:

>>> 1/interval[3] == interval[1]/interval[3]
True

The imath module provides transcendental functions that accept interval arguments. For instance,

>>> imath.exp(interval[0, 1])
interval([1.0, 2.7182818284590455])

Inspection

The in operator can be used to test whether a scalar is in a interval:

>>> 0 in interval[-1, 1]
True

>>> 0 in interval[1, 2]
False

or whether an interval is a subset of another interval:

>>> interval[1, 2] in interval[0, 3]
True

>>> interval[1, 2] in interval[1.5, 3]
False

The len operator returns the number of connected components in the interval:

>>> len(interval())
0

>>> len(interval[1, 2])
1

>>> len(interval(1, 2))
2

It is possible to iterate on an interval components as in the statement

>>> [x for x in interval([1, 2], 3).components]
[interval([1.0, 2.0]), interval([3.0])]

The endpoints are given by

>>> interval([1, 2], 3).extrema
interval([1.0], [2.0], [3.0])

and the midpoints by

>>> interval([1, 2], 3).midpoint
interval([1.5], [3.0])

Modules

The code is organized in three modules:

  • interval, providing the interval class;
  • interval.fpu, providing lower-level control and helper functions;
  • interval.imath, imath, providing transendental functions for interval, akin to math for floats.

interval

interval
An algebraically closed interval system on the extended real set.

This package provides the interval class, which is usually imported into the current namespace:

>>> from interval import interval
>>> interval[1,2]
interval([1.0, 2.0])
interval.inf

Infinity in the sense of IEEE 754. Identical to interval.fpu.infinity.

>>> inf + inf == inf
True
class interval.interval

A (multi-)interval on the extended real set.

An interval is an immutable object that is created by specifying the end-points of its connected components:

>>> interval([0, 1], [2, 3], [10, 15])
interval([0.0, 1.0], [2.0, 3.0], [10.0, 15.0])

constructs an interval whose arbitrary element x must satisfy 0 <= x <= 1 or 2 <= x <= 3 or 10 <= x <= 15. Several shortcuts are available:

>>> interval(1, [2, 3])
interval([1.0], [2.0, 3.0])
>>> interval[1, 2]
interval([1.0, 2.0])
>>> interval[1]
interval([1.0])

Intervals are closed with respect to all arithmetic operations, integer power, union, and intersection. Casting is provided for scalars in the real set.

>>> (1 + interval[3, 4] / interval[-1, 2]) & interval[-5, 5]
interval([-5.0, -2.0], [2.5, 5.0])
cast

Cast a scalar to an interval.

If the argument is an interval, it is returned unchanged. If the argument is not a scalar an interval.ScalarError is raised:

>>> interval.cast('asd')
...
ScalarError: Invalid scalar: 'asd'
format(fs)

Format into a string using fs as format for the interval bounds.

The argument fs can be any string format valid with floats:

>>> interval[-2.1, 3.4].format("%+g")
'interval([-2.1, +3.4])'
function

Decorator creating an interval function from a function on a single component.

The original function accepts one argument and returns a sequence of (inf, sup) pairs:

>>> @interval.function
... def mirror(c):
...    return (-c.sup, -c.inf), c
>>> mirror(interval([1, 2], 3))
interval([-3.0], [-2.0, -1.0], [1.0, 2.0], [3.0])
hull

Return the hull of the specified intervals.

The hull of a set of intervals is the smallest connected interval enclosing all the intervals.

>>> interval.hull((interval[1, 3], interval[10, 15]))
interval([1.0, 15.0])
>>> interval.hull([interval(1, 2)])
interval([1.0, 2.0])
inverse(x)
Return self ** -1, or, equivalently, 1 / self.
new
Create a new interval from existing components.
newton(f, p, maxiter=10000, tracer_cb=None)

Find the roots of f(x) (where p=df/dx) within self using Newton-Raphson.

For instance, the following solves x**3 == x in [-10, 10]:

>>> interval[-10, 10].newton(lambda x: x - x**3, lambda x: 1 - 3*x**2)
interval([-1.0], [0.0], [1.0])
>>> interval[-1.5, 3].newton(lambda x: (x**2 - 1)*(x - 2), lambda x:3*x**2 - 4*x -1)
interval([-1.0], [1.0], [2.0])
union

Return the union of the specified intervals.

This class method is equivalent to the repeated use of the | operator.

>>> interval.union([interval([1, 3], [4, 6]), interval([2, 5], 9)])
interval([1.0, 6.0], [9.0])
>>> interval([1, 3], [4, 6]) | interval([2, 5], 9)
interval([1.0, 6.0], [9.0])

interval.fpu

interval.fpu
Floating-point unit control and helper functions.

This module provides:

  1. Mechanisms for the control of the FPU’s rounding modes;
  2. Helper functions that respect IEEE 754 semantics.
Limitations
The current implementation of the FPU’s rounding-mode control is thought to be not thread-safe.
interval.fpu.infinity

Infinity in the sense of IEEE 754. Also exported as interval.inf.

>>> from interval import fpu
>>> fpu.infinity + fpu.infinity == fpu.infinity
True
interval.fpu.nan

An instance of not-a-number, also in the sense of IEEE 754. Note that you cannot use nan in conditional clauses. Use isnan instead.

>>> from interval import fpu
>>> fpu.nan == fpu.nan
False
>>> fpu.isnan(fpu.nan)
True
exception interval.fpu.NanException
Exception thrown when an unwanted nan is encountered.
interval.fpu.down(f)
Perform a computation with the FPU rounding downwards.
interval.fpu.ensure_nonan(x)
Return x, throwing a NanException if x is nan.
interval.fpu.isnan(x)
Return True if x is nan.
interval.fpu.max(l)
Return the maximum of the elements in l, or nan if any element is nan.
interval.fpu.min(l)
Return the minimum of the elements in l, or nan if any element is nan.
interval.fpu.power_rd(x, n)
Raise x to the n-th power (with n positive integer), rounded toward -inf.
interval.fpu.power_rn(x, n)
Raise x to the n-th power (with n positive integer), rounded to nearest.
interval.fpu.power_ru(x, n)
Raise x to the n-th power (with n positive integer), rounded toward +inf.
interval.fpu.up(f)
Perform a computation with the FPU rounding upwards.

interval.imath

interval.imath
Mathematical function library for intervals.

This module provides transcendental functions with interval argument.

Indices and tables