API Documentation

This document details the API exposed by the modules that make up this library.

Contents

• API Documentation
  • interval — Interval arithmetic
  • interval.fpu — FPU control and helper functions
  • interval.imath — Mathematical functions for intervals

interval — Interval arithmetic

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.

>>> from interval import inf
>>> 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])

classmethod cast(x)

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.

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])'

classmethod function(f)

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])

classmethod hull(intervals)

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.

classmethod new(components)

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])

classmethod union(intervals)

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 — FPU control and helper functions

This module provides:

1. Mechanisms for the control of the rounding modes of the floating-point unit (FPU);
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.

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, in the sense of IEEE 754. Note that you must not use nan in comparisons. 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.isinteger(n)

True if the argument is an instance of an integer type.

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 — Mathematical functions for intervals

This module provides transcendental functions with interval argument.

interval.imath.atan(x)

Arc tangent.

interval.imath.atanpi(x)

atan(x)/pi.

interval.imath.cos(x)

Cosine.

interval.imath.cosh(x)

Hyberbolic cosine.

interval.imath.cospi(x)

cos(pi*x).

interval.imath.exp(x)

Exponential.

interval.imath.expm1(x)

exp(x) - 1.

interval.imath.log(x)

Natural logarithm.

interval.imath.log10(x)

Logarithm in base 10.

interval.imath.log1p(x)

log(1+x).

interval.imath.log2(x)

Logarithm in base 2.

interval.imath.sin(x)

Sine.

interval.imath.sinh(x)

Hyberbolic sine.

interval.imath.sinpi(x)

sin(pi*x).

interval.imath.sqrt(x)

Square root.

interval.imath.tan(x)

Tangent.

interval.imath.tanh(x)

Hyberbolic tangent.

interval.imath.tanpi(x)

tan(pi*x).