help int_utils

Title

int_utils -- Tools for interval analysis and computation

Contents

help entry Purpose

+
+
---+ Basic arithmetic functions+

+
+

int_add() Add intervals

int_sub() Subtract intervals

int_mult() Multiply intervals

int_pow() Raise intervals to a power

+
+
---+ Expanded arithmetic functions+

+
+

int_matmult() Multiply interval matrices

int_rowmult() Multiply rows of intervals

int_rowadd() Add rows of intervals

int_transpose() Transpose an interval matrix

+
+
---+ Expanded arithmetic row-form matrix functions+

+
+

int_rowmatmult() Multiply interval matrices listed as rows

int_rowmatvecmult() Multiply interval matrices listed as rows with interval (row) vector

int_rowtranspose() Transpose interval matrix listed as a row

+
+
---+ Interval set operations+

+
+

int_int() Intersection of intervals

int_rowint() Rowwise intersection of intervals

int_hun() Interval hull

int_rowhull() Columnwise interval hull

int_collect() Collect intervals

+
+
---+ Various interval utilities+

+
+

int_mid() Interval midpoint (returned as interval)

mid() Interval midpoint (scalar)

int_mince() Divide intervals into smaller intervals

int_mesh() Make a series of intervals covering a region

int_widths() Compute interval widths

radius() Radii of intervals

r_up() Round interval upwards

r_down() Round interval downwards

Description

The functions above provide a means of doing interval computations, along these lines described in texts such as Jaulin et. al. (2001) or
Moore et. al. (2009). Interval computations bear much resemblance to computations using convex sets.
The idea is to develop sums, products, differences, etc. that concatenate the possibilities of two intervals. As examples, consider
the intervals [1,3] and [4,6]. The convenience is that often set computations can be performed by manipulating the
upper and lower bounds of the sets.

Another salient feature of interval arithmetic is the use of outward rounding; lower bounds are rounded down, while
upper bounds are rounded up. This convention allows the user to retain
control over numerical features of the problem, and also ensures that intervals are not inadvertently shrunk in the course
of computation by numerical problems. The examples in int_add() presents an example as to how this works.

With a slight abuse of notation, consider:

Interval Addition: [1,3]+[4,6]=[5,9]
Interval Subtraction: [1,3]-[4,6]=[-3,-1]
Interval Multiplication: [1,3]*[4,6]=[4,18]

For examples as to how the above operations work, see the individual help entries. The above-mentioned citations describe in detail
how interval operations work in more complex cases. Unlike most packages that do interval computations, the above functions do not
rely on description of an "interval class" but instead simply rely on standard mata matrices (for examples, see the individual help
entries).

Detailed descriptions of operations

int_add() -- Addition of intervals for interval computations

Syntax

real matrix int_add(real matrix X, real matrix Y [, real scalar digits])

where

X: real matrix containing data (each pair of rows i,i+1 of which represent intervals)

Y: real matrix containing data (each pair of rows i,i+1 of which represent intervals)

where

digits: real scalar containing desired rounding. Default is 1e-8.

Description

int_add() computes interval sums of vectors or matrices. Rows of the input matrices X,Y are treated as usual, while
each pair of columns are treated as intervals. Thus, an N-by-1 interval (row) vector should be represented in mata as an N-by-2 matrix,
with lower limits appearing in the first column and upper limits appearing in the second column.
An interval r-by-(2c) matrix would have lower limits in columns 1,3,5, etc. and upper limits appearing in columns 2,4,6, etc.

Conceptually, interval addition is described by adding all possible members of two interval sets together, creating another
interval. For example, adding the
two intervals [-1,5] and [2,4] gives the result [1,9]. int_add() can perform addition of any conformable matrices.

Options

The option digits specifies the minimal roundoff error used in interval computations. In effect, this sets the size of the
smallest interval recognizable by the interval addition operation and is necessary for so as not to get misleading results in the
course of interval computations. The second example below shows how int_add() automatically rounds lower limits down
and upper limits up according to digits. See r_up() or r_down() for further details concerning rounding.

Remarks

int_add() does not check if it is in fact true that the lower limits of intervals are less than or equal to upper limits; hence,
users must exert care that this is in fact the case.

Examples:

Consider the addition of two interval vectors:

. mata: X=(-1,1) \ (2,4)
. mata: Y=(2,3) \ (4,5)
. mata: int_add(X,Y)
1 2
+-------+
1 | 1 4 |
2 | 6 9 |
+-------+

An example featuring outward rounding:

. mata: X=(-.123456799,-.123456798)
. mata: Y=(0,0)
. mata: int_add(X,Y)
1 2
+
+
1 | -.1234568 -.1234567 |
+
+

. mata: int_add(X,Y,1e-10)
1 2
+
+
1 | -.123456799 -.123456798 |
+
+

Conformability

X and Y must be conformable (i. e., vectors of the same length). Moreover, lower limits (entries in odd columns) should be
less than upper limits (entries in even columns). Some care must be exercised in assuring this, as int_add() does not check
whether or not it is true.

int_sub() -- Subtraction of intervals for interval computations

Syntax

real matrix int_sub(real matrix X, real matrix Y [, real scalar digits])

where

X: real matrix containing data (each pair of rows i,i+1 of which represent intervals)

Y: real matrix containing data (each pair of rows i,i+1 of which represent intervals)

where

digits: real scalar containing desired rounding. Default is 1e-8.

Description

int_sub() computes interval sums of vectors or matrices. Rows of the input matrices X,Y are treated as they
usually are with vectors, while
each pair of columns are treated as intervals. Thus, an N-by-1 interval (row) vector should be stored in mata as an N-by-2 matrix,
with lower limits appearing in the first column and upper limits appearing in the second column. int_sub() subtracts the
interval matrix Y from the interval matrix X, or perhaps more correctly, the interval matrix represented by Y is
subtracted from the interval matrix represented by X.

Roughly speaking, interval subtraction can be viewed as the result of collecting all possible results when one interval is
subtracted from another. For example, subtracting the
interval [-1,5] from the interval [2,4] gives the result [-3,5]. int_sub() can perform subtraction of any conformable
interval matrices.

Options

The option digits specifies the minimal roundoff error used in interval computations. In effect, this sets the size of the
smallest interval recognizable by the interval addition operation and is necessary so as not to get misleading results in the
course of interval computations. The second example below shows how int_sub() automatically rounds lower limits down
and upper limits up according to digits. See r_up() or r_down() for further details concerning rounding.

Remarks

int_sub() does not check if it is in fact true that the lower limits of intervals are less than or equal to upper limits; hence,
users must exert care that this is in fact the case.

Examples:

Consider the sets of (interval) vectors:

. mata: X=(-1,1) \ (2,4)
. mata: Y=(2,3) \ (4,5)
. mata: int_sub(X,Y)
1 2
+
+
1 | -4 -1 |
2 | -3 0 |
+
+

. mata: X=(-.123456799,-.123456798)
. mata: Y=(0,0)
. mata: int_sub(X,Y)
1 2
+
+
1 | -.1234568 -.1234567 |
+
+

. mata: int_sub(X,Y,1e-10)
1 2
+
+
1 | -.123456799 -.123456798 |
+
+

Conformability

X and Y must be conformable (i. e., matrices of the same dimension). Lower limits (entries in odd columns) should be
less than upper limits (entries in even columns); once again, this is not checked by int_sub() (or any
other command in int_utils.

int_mult() -- Multiplication of intervals for interval computations

Syntax

real matrix int_mult(real matrix X, real matrix Y [, real scalar digits])

where

X: real matrix containing data (each pair of rows i,i+1 of which represent intervals)

Y: real matrix containing data (each pair of rows i,i+1 of which represent intervals)

where

digits: real scalar containing desired rounding. Default is 1e-8.

Description

int_mult() computes term-by-term interval products of interval vectors (that is, it works like the ":*" operator). Rows of the input matrices X,Y are treated as usual, while
the two columns are treated as lower and upper bounds of intervals. Thus, an N-by-1 interval (row) vector should be written as an N-by-2 matrix,
with lower limits appearing in the first column and upper limits appearing in the second column. int_mult() multiplies the
interval vector Y wiht the interval matrix X. The computed product is element-by-element.

Roughly speaking, interval multiplication is described by concatinating all possible ways of multiplying one interval
by another. For example, multiplying the
interval [-1,5] with the interval [2,4] gives the result [-4,20].

Options

The option digits specifies the minimal roundoff error used in interval computations. In effect, this sets the size of the
smallest interval recognizable by the interval addition operation and is necessary for so as not to get misleading results in the
course of interval computations. The second example below shows how int_mult() automatically rounds lower limits down
and upper limits up according to digits. See r_up() or r_down() for further details concerning rounding.

Remarks

int_mult() does not check if it is in fact true that the lower limits of intervals are less than or equal to upper limits; hence,
users must exert care that this is in fact the case.

Examples:

Consider the sets of (interval) vectors:

. mata: X=(-1,1) \ (2,4)
. mata: Y=(2,3) \ (4,5)
. mata: int_mult(X,Y)
1 2
+--------+
1 | -3 3 |
2 | -3 20 |
+--------+

. mata: X=(-.123456799,-.123456798)
. mata: Y=(1,1)
. mata: int_mult(X,Y)
1 2
+
+
1 | -.1234568 -.1234567 |
+
+

. mata: int_mult(X,Y,1e-10)
1 2
+
+
1 | -.123456799 -.123456798 |
+
+

Conformability

X and Y must be conformable (i. e., vectors of the same length, each with two columns).
Lower limits (entries in the first column) should be
less than upper limits (entries in even columns), but once again, whether or not this is true is not checked by int_mult() (or any
other command in int_utils).

int_pow() -- Raise an interval to a (scalar) power

Syntax

real matrix int_pow(real matrix X, real scalar power [, real scalar digits])

X: real matrix containing data (each pair of rows i,i+1 of which represent intervals)

power: real scalar power to raise interval to)

where

digits: real scalar containing desired rounding. Default is 1e-8.

Description

int_pow() raises a collection of intervals into powers. The matrix X must be of dimension D by 2,
where lower interval bounds appear in the first column and upper bounds in the second column.
The scalar power is the power to which the intervals are to be raised, and may be either
integral or fractional, positive or negative. The scalar digits controls outward rounding, as discussed in r_up() or r_down(). If
the user attempts to raise an interval with a negative component to a negative power, missing is returned.

Example:

. mata: X=(0,1 \ 1,2)
. mata: int_pow(X,2)
1 2
+
+
1 | 0 1 |
2 | 1 8 |
+
+

int_matmult() -- Multiplication of intervals for interval computations

Syntax

real matrix int_matmult(real matrix X, real matrix Y [, real scalar digits])

where

X: real matrix containing data (each pair of rows i,i+1 of which represent intervals)

Y: real matrix containing data (each pair of rows i,i+1 of which represent intervals)

where

digits: real scalar containing desired rounding. Default is 1e-8.

Description

int_matmult() computes matrix products of interval matrices. Rows of the input matrices X,Y are treated as usual, while
pairs of columns are treated as lower and upper bounds of intervals. Thus, an r-by-c interval matrix should be written as an r-by-2c matrix,
with lower limits appearing in the first column and upper limits appearing in the second column. int_matmult() multiplies the
interval matrix Y with the interval matrix X. The computations are done using the textbook brute-force matrix multiplication approach.

Interval matrix multiplication is done by concatinating all possible ways of multiplying the entries of two matrices, and collecting results.
Consider multiplying the 1-by-2 interval matrix [(1,2),(3,4)] with the 2-by-1 interval matrix [(-1,1),(0,2)]'. This requires performing the computation
(1,2)*(-1,1)+(3,4)*(0,2). This first gives (-2,2)+(0,8), and then reduces to (-2,10). This amounts to an application of
int_add() and int_mult(). In terms of these functions, the calculation would be carried out
as int_add(int_mult((1,2),(-1,1)),int_mult((3,4),(0,2))).

Options

The option digits specifies the minimal roundoff error used in interval computations. In effect, this sets the size of the
smallest interval recognizable by the interval addition operation and is necessary for so as not to get misleading results in the
course of interval computations. Illustrations of how digits works are given in the help entries int_add(),
int_sub(), and int_mult().

Remarks

int_matmult() does not check if it is in fact true that the lower limits of intervals are less than or equal to upper limits; hence,
users must exert care in assuring that this is in fact the case.

Examples:

Multiplication of two 2-by-2 interval matrices (which are represented as 2-by-4 matrices):

. mata: X=(0,1,2,4) \ (1,2,5,7)
. mata: Y=(-1,1,4,6) \ (3,4,7,8)
. mata: int_matmult(X,Y)
1 2 3 4
+
+
1 | 5 17 14 38 |
2 | 13 30 39 68 |
+
+

Conformability

X and Y must be conformable matrices. Usually, if X is a r1-by-c1 matrix, and Y is r2-by-c2, then it must be the case that c1=r2.
In the case of interval computations, X is a matrix of intervals held in a r1-by-(2*c1) matrix, and Y is a matrix of intervals held in a
r2-by-(2*c2) matrix. Hence, for interval computations executed in this fashion, it is required that Y has half as many rows as X has columns.
For example, if X is a 3-by-6 interval matrix (implying that X is really a 3-by-3 matrix of intervals), then Y should be 3-by-(2*c2).
As a final note, int_matmult() can be used to compute standard inner (dot) products of vectors; in this case X is 1-by-(2*N) and Y is N-by-2.

int_rowmult() -- Row-wise products of intervals for interval computations

Syntax

real matrix int_rowmult(real matrix X [, real scalar digits])

where

X: real matrix containing data (each pair of rows i,i+1 of which represent intervals)

where

digits: real scalar containing desired rounding. Default is 1e-8.

Description

int_rowmult() computes rowwise products of intervals. Rows of the input matrix X are treated as usual, while
each pair of columns are treated as lower and upper bounds, respectively, of intervals. Thus, an N-by-1 interval (row)
vector should be written as an N-by-2 matrix,
with lower limits appearing in the first column and upper limits appearing in the second column. int_rowmult() treats
each pair of columns as intervals, and computes a single N-by-2 matrix representing the interval product of all represented intervals.
For details as to how interval multiplication is defined, see int_mult().

Options

The option digits specifies the minimal roundoff error used in interval computations. In effect, this sets the size of the
smallest interval recognizable by the interval addition operation and is necessary for so as not to get misleading results in the
course of interval computations. For details, see the help entries int_add(), int_sub(),
or int_mult().

Remarks

int_rowmult() does not check if it is in fact true that the lower limits of intervals are less than or equal to upper limits; hence,
users must exert care that this is in fact the case.

Examples:

Consider the rows of a matrix X which are successive intervals:

. mata: X=(-1,1),(2,4) \ (2,3),(4,5)
. mata: int_rowmult(X)
1 2
+--------+
1 | -4 4 |
2 | 8 15 |
+--------+

Conformability

As it is a sequence of intervals X should have an even number of entries, where odd entries are lower limits and even entries are upper limits.

int_rowadd() -- Row-wise sums of intervals for interval computations

Syntax

real matrix int_rowadd(real matrix X [, real scalar digits])

where

X: real matrix containing data (each pair of rows i,i+1 of which represent intervals)

where

digits: real scalar containing desired rounding. Default is 1e-8

Description

int_rowadd() computes rowwise sums of intervals. Rows of the input matrix X are treated as usual, while
each pair of columns are treated as lower and upper bounds, respectively, of intervals. Thus, an N-by-1 interval (row)
vector should be written as an N-by-2 matrix,
with lower limits appearing in the first column and upper limits appearing in the second column. int_rowadd() treats
each pair of columns as intervals, and computes a single N-by-2 matrix representing the interval sum of all represented intervals.
For details as to how interval addition is defined, see int_add().

Options

The option digits specifies the minimal roundoff error used in interval computations. In effect, this sets the size of the
smallest interval recognizable by the interval addition operation and is necessary for so as not to get misleading results in the
course of interval computations. For details, see the help entries int_add(), int_sub(),
or int_mult().

Remarks

int_rowadd() does not check if it is in fact true that the lower limits of intervals are less than or equal to upper limits; hence,
users must exert care that this is in fact the case.

Examples:

Consider the rows of a matrix X which are successive intervals:

. mata: X=(-1,1),(2,4) \ (2,3),(4,5)
. mata: int_rowadd(X)
1 2
+------+
1 | 1 5 |
2 | 6 8 |
+------+

Conformability

As it is a sequence of intervals X should have an even number of entries, where odd entries are lower limits and even entries are upper limits.

int_transpose() -- Transposition of interval matrices

Syntax

real matrix int_transpose(real matrix X)

where

X: real matrix containing data (each pair of rows i,i+1 of which represent intervals)

Description

int_transpose() transposes interval matrices. Rows of the input matrix X are treated as usual, while
pairs of columns are treated as lower and upper bounds of intervals. Thus, an r-by-c interval matrix should be written as an r-by-2c matrix,
with lower limits appearing in the first column and upper limits appearing in the second column.

Remarks

int_transpose() does not check if it is in fact true that the lower limits of intervals are less than or equal to upper limits; hence,
users must exert care in assuring that this is in fact the case.

Examples:

Transposition of an interval matrix:

. mata: X=(0,1,2,4) \ (1,2,5,7)
. mata: int_transpose(X)
1 2 3 4
+
+
1 | 0 1 1 2 |
2 | 2 4 5 7 |
+
+

Conformability

X and Y must be conformable matrices. Usually, if X is a r1-by-c1 matrix, and Y is r2-by-c2, then it must be the case that c1=r2.
In the case of interval computations, X is a matrix of intervals held in a r1-by-(2*c1) matrix, and Y is a matrix of intervals held in a
r2-by-(2*c2) matrix. Hence, for interval computations executed in this fashion, it is required that Y has half as many rows as X has columns.
For example, if X is a 3-by-6 interval matrix (implying that X is really a 3-by-3 matrix of intervals), then Y should be 3-by-(2*c2).
As a final note, int_matmult() can be used to compute standard inner (dot) products of vectors; in this case X is 1-by-(2*N) and Y is N-by-2.

int_rowmatmult() -- (Square) matrix-interval products in parallel, where matrices are in single row form

Syntax

real matrix int_rowmatmult(real matrix X, real matrix Y [, real scalar digits])

where

X: real matrix containing data (each pair of rows i,i+1 of which represent entries in order of an interval)

Y: real matrix containing data (each pair of rows i,i+1 of which represent entries in order of an interval matrix)

where

digits: real scalar containing desired rounding. Default is 1e-8

Description

int_rowmatmult() computes rowwise products of interval matrices, where each row of X and Y holds all matrix entries.
Ignoring the interval component of the problem for the moment, consider the case of multiplying two 3-by-3 matrices. int_rowmatmult()
would correspond to reshaping (see, e.g., rowshape() each matrix into single 1-by-9 rows and stacking them. The advantage
is that now matrix multiplication can proceed in parallel, observation by observation.

int_rowmatmult() executes this sort of operation using interval computations. Square in this case are represented by a r-by-2r setting,
where each pair of columns represents an interval; see int_matmult() for more discussion. In the case of int_rowmatmult(),
each interval matrix is held in a single row of dimension 1-by-(2r^2).

Options

The option digits specifies the minimal roundoff error used in interval computations. In effect, this sets the size of the
smallest interval recognizable by the interval addition operation and is necessary for so as not to get misleading results in the
course of interval computations. For details, see the help entries int_add(), int_sub(),
or int_mult().

Remarks

int_rowmatmult() does not check if it is in fact true that the lower limits of intervals are less than or equal to upper limits; hence,
users must exert care that this is in fact the case. Moreover, int_rowmatmult() does not check if the represented matrices are square, so care must
also be exerted that matrices are of correct dimension.

Examples:

Multiplication of two 2-by-2 interval matrices (which are represented as 2-by-4 matrices):

. mata: X=(0,1,2,4) \ (1,2,5,7)
. mata: Y=(-1,1,4,6) \ (3,4,7,8)
. mata: int_matmult(X,Y)
1 2 3 4
+
+
1 | 5 17 14 38 |
2 | 13 30 39 68 |
+
+

. mata: X=rowshape(X,1)
. mata: Y=rowshape(Y,1)
. mata: int_rowmatmult(X,Y)
1 2 3 4 5 6 7 8
+
+
1 | 5 17 14 38 13 30 39 68 |
+
+

Conformability

As X,Y represent a collection of m square matrices, they should have dimension m-by-(2*r^2),
where odd entries are lower limits and even entries are upper limits.

int_rowmatvecmult() -- (Square) matrix-vector interval products in parallel, where matrices and vectors are in single row form

Syntax

real matrix int_rowmatvecmult(real matrix X, real matrix y [, real scalar digits])

where

X: real matrix containing data (each pair of rows i,i+1 of which represent entries in order of an interval)

y: real matrix containing data (each pair of rows i,i+1 of which represent entries in order of an interval matrix)

where

digits: real scalar containing desired rounding. Default is 1e-8.

Description

int_rowmatvecmult() is a companion to int_matmult(). It computes rowwise products of interval matrices
and interval vectors, where each row of X holds an interval matrix and each row of y holds an interval vector.
Ignoring the interval component of the problem for the moment, consider the case of multiplying a sequence of
3-by-3 matrices and 3-by-1 column vectors.
int_rowmatvecmult() would correspond to reshaping (see, e.g., rowshape()) each matrix into 1-by-9 rows
and stacking them, and reshaping each vector into 1-by-3 rows and stacking them.
The advantage is that now matrix multiplication can proceed in parallel rather than through looping.

int_rowmatvecmult() executes this sort of operation using interval computations. Square matrices in this case are represented
by a r-by-2r collection of intervals, where each pair of columns represents an interval; see int_matmult() for more discussion.
A conformable interval vector written in row form is of dimension 1-by-(2r).

Options

The option digits specifies the minimal roundoff error used in interval computations. In effect, this sets the size of the
smallest interval recognizable by the interval addition operation and is necessary for so as not to get misleading results in the
course of interval computations. For details, see the help entries int_add(), int_sub(),
or int_mult().

Remarks

int_rowmatvecmult() does not check if it is in fact true that the lower limits of intervals are less than or equal to upper limits; hence,
users must exert care that this is in fact the case. Moreover, int_rowmatmult() does not check if the represented matrices are square, so care must
also be exerted that matrices are of correct dimension.

Examples:

Multiplication of two 2-by-2 interval matrices (which are represented as 2-by-4 matrices):

. mata: X=(0,1,2,4) \ (1,2,5,7)
. mata: Y=(-1,1) \ (4,6)
. mata: int_matmult(X,Y)
1 2
+
+
1 | 7 25 |
2 | 18 44 |
+
+

. mata: X=rowshape(X,1)
. mata: Y=rowshape(Y,1)
. mata: int_rowmatvecmult(X,Y)
1 2 3 4
+
+
1 | 7 25 18 44 |
+
+

Conformability

As X represents a collection of m square (interval) matrices, and y represents a collection of
X should have dimension m-by-(2*r^2), and y should have dimension m-by-(2r). In each case,
Odd column entries are lower limits of intervals and even entries are upper limits of intervals.

int_rowtranpose() -- Transpose of a (square) interval matrix written in single row form

Syntax

real matrix int_rowtranspose(real matrix X)

where

X: real matrix containing data (each pair of rows i,i+1 of which represent entries in order of an interval)

Description

int_rowtranspose() is a companion to int_rowmatmult(). It computes rowwise transposes of interval matrices
and may help in performing rowwise interval computations.

Examples:

Reshaping and transposing a 2-by-2 interval matrix:

. mata: X=(0,1,2,4) \ (1,2,5,7)
. mata: X=rowshape(X,1)
. mata: int_rowtranspose(X)
1 2 3 4 5 6 7 8
+
+
1 | 0 1 1 2 2 4 5 7 |
+
+

Conformability

As X represents a collection of m square (interval) matrices,
X should have dimension m-by-(2*r^2). In each case,
Odd column entries are lower limits of intervals and even entries are upper limits of intervals.

int_int() -- Intersection of intervals for interval computations

Syntax

real matrix int_int(real matrix X, real matrix Y)

where

X: real matrix containing data (pairs of rows of which represent intervals)

Y: real matrix containing data (pairs of rows of which represent intervals)

Description

int_int() computes row-by-row interval intersections of two interval vectors. Rows of the input matrices X,Y are treated as usual, while
the first column of X and Y is treated as the lower limit of an interval, and the second column of X and Y
are treated as upper limits. An N-by-1 interval (column) vector should be represented in mata as an N-by-2 matrix.

Interval intersection is simply returns the range of common elements for two interval vectors. For example, the intervals
[-1,1] and [0,4] have intersection [0,1].

Remarks

int_int() does not check if it is in fact true that the lower limits of intervals are less than or equal to upper limits; hence,
users must exert care that this is in fact the case. int_int() returns missing values if the intervals do not intersect.

Examples:

. mata: X=(-1,1) \ (2,4)
. mata: Y=(0,3) \ (5,6)
. mata: int_int(X,Y)
1 2
+-------+
1 | 0 1 |
2 | . . |
+-------+

Conformability

X and Y must be of the same length, each with two columns. Moreover, lower limits (entries in the first column) should be
less than upper limits (entries in the second column). Some care must be exercised in assuring this, as int_int() does not check
whether or not it is true.

int_int() -- Rowwise intersection of intervals for interval computations

Syntax

real matrix int_int(real matrix X, real matrix Y)

where

X,Y: real matrix containing data (each pair of columns i,i+1 of which represent intervals)

Description

int_rowint() computes interval intersections of a set of row-interval vectors, arranged as columns of the matrices X
and Y.
Each pair of columns of both matrices i,i+1 is treated as a separate interval. Effectively, int_rowint() applies
int_int() repeatedly to each pair of columns of X and Y. For the definition of interval intersection, see
int_int().

Remarks

int_rowint() does not check if it is in fact true that the lower limits of intervals are less than or equal to upper limits; hence,
users must exert care that this is in fact the case. int_rowint() returns missing values if intervals do not intersect.

Examples:

Consider the addition of two interval vectors:

. mata: X=-1,1,0,3 \ 2,4,5,6
. mata: Y=0,1,2,3 \ 1,2,3,4
. mata: int_rowint(X,Y)
1 2 3 4
+
+
1 | 0 1 2 3 |
2 | 2 2 . . |
+
+

Conformability

X and Y must be of the same length, each with the same number of columns. Moreover, lower limits (entries in the first column) should be
less than upper limits (entries in the second column). Some care must be exercised in assuring this, as int_int() does not check
whether or not it is true.

int_hun() -- Interval hull (union) for interval computations

Syntax

real matrix int_hun(real matrix X, real matrix Y [, real scalar digits])

where

X: real matrix containing data (first column represents lower bounds, the second upper bounds) of an interval)

Y: real matrix containing data (first column represents lower bounds, the second upper bounds) of an interval)

where

digits: real scalar containing desired rounding. Default is 1e-8

Description

int_hun() computes the interval hull of two interval (column) vectors. Rows of the input matrices X,Y are treated as usual, while
the first column of X and Y is treated as the lower limit of an interval, and the second column of X and Y
are treated as upper limits. An N-by-1 interval (column) vector should be represented in mata as an N-by-2 matrix.

The interval hull is, roughly speaking, the largest interval that contains the intervals in the rows of X and Y.
For example, the interval hull
of (-1,3) and (-2,2) is (-2,3). While this is seemingly the same as the union of two intervals, the hull fills in gaps. So, for example, the
interval hull of (-2,-1) and (0,1) is the interval (-2,1).

Options

The option digits specifies the minimal roundoff error used in interval computations. In effect, this sets the size of the
smallest interval recognizable by the interval addition operation and is necessary for so as not to get misleading results in the
course of interval computations. Illustrations of how digits works are given in the help entries int_add(),
int_sub(), and int_mult().

In the case of interval hull computations, the idea is to get the smallest interval that contains all the elements of two intervals. Hence,
lower limits are rounded down to the lower bound suggested by digits, and upper limits are rounded up to the upper bound suggested
by digits.

Remarks

int_hun() does not check if it is in fact true that the lower limits of intervals are less than or equal to upper limits; hence,
users must exert care that this is in fact the case. int_hun() returns missing values if the intervals do not intersect.

Examples:

. mata: X=(-1,1) \ (2,4)
. mata: Y=(0,3) \ (5,6)
. mata: int_hun(X,Y)
1 2
+--------+
1 | -1 3 |
2 | 2 6 |
+--------+

Conformability

X and Y must be of the same length, each with two columns. Moreover, lower limits (entries in the first column) should be
less than upper limits (entries in the second column). Some care must be exercised in assuring this, as int_hun() does not check
whether or not it is true.

int_rowhull() -- Rowwise interval hulls for interval computations

Syntax

real matrix int_rowhull(real matrix X)

where

X: real matrix containing data (each pair of columns i,i+1 of which represent intervals)

Description

int_rowhull() computes column-wise interval hull unions for a set of row-interval vectors, arranged as columns of the matrices X.
Each pair of columns i,i+1 of X is treated as a separate interval. Effectively, int_rowhull() applies
int_hun() successively to each row of X and returns a single row of entries comprising the interval hull
of each interval in X. For the definition of the interval hull, see
int_hun().

Remarks

int_rowhull() does not check if it is in fact true that the lower limits of intervals are less than or equal to upper limits; hence,
users must exert care that this is in fact the case.

Examples:

Consider the addition of two interval vectors:

. mata: X=-1,1,0,3 \ 2,4,5,6
. mata: int_rowhull(X)
1 2 3 4
+
+
1 | -1 4 0 6 |
+
+

Conformability

X should have an even number of columns, where each pair of columns represents an interval vector.
Moreover, lower limits (entries in the first column) should be
less than upper limits (entries in the second column). Some care must be exercised in assuring this, as int_int() does not check
whether or not it is true.

int_collect() -- Collection of intervals into distinct disjoint intervals

Syntax

real matrix int_collect(real matrix X)

where

X: real matrix containing data (each pair of columns i,i+1 of which represent intervals)

Description

int_collect() sweeps a matrix containing column-vector intervals and assembles these intervals in to
the smallest possible number of disjoint intervals. To be more specific, int_collect() takes a group of intervals and
checks to see whether there are common points of intersection among those intervals by applying int_rowint() (see
int_rowint()). In the event that intervals overlap, int_collect() then combines these
intervals by applying int_rowhull() (see int_rowint()). The idea is to resolve a set of intervals
into the smallest possible group of disjoint yet all-inclusive intervals.

Remarks

int_collect() does not check if it is in fact true that the lower limits of intervals are less than or equal to upper limits; hence,
users must exert care that the numbers appearing in the odd columns i are less than their counterparts in even columns i+1.

Examples:

. mata: X=.1,.2,.4,.5 \ .15,.18,3,4 \10,11,12,13
. mata: int_collect(X)
1 2 3 4
+
+
1 | .1 .2 .4 4 |
1 | 10 11 12 13 |
+
+

Conformability

X should have an even number of columns, where each pair of columns represents an interval vector.
Moreover, lower limits (entries in the first column) should be
less than upper limits (entries in the second column). Some care must be exercised in assuring this, as int_collect() does not check
whether or not it is true.

int_mid() -- Midpoints of intervals returned as intervals

Syntax

real matrix int_mid(real matrix X [, digits])

where

X: real matrix containing data (each pair of columns i,i+1 of which represent intervals)

Description

int_mid() computes the interval midpoints of the collection of intervals represented by X. It differs from the related command
mid() (see mid() in that it returns results in interval form. The midpoint of an interval is defined in the obvious
way; the midpoint of an interval is simply the average of its lower and upper bound. int_mid() returns results in interval form so as
to ease conformability with other interval functions. So, when confronted with the interval (4,6), int_mid() returns the result (5,5).

Options

The option digits specifies the minimal roundoff error used in interval computations. In effect, this sets the size of the
smallest interval recognizable by the interval addition operation and is necessary for so as not to get misleading results in the
course of interval computations. Illustrations of how digits works are given in the help entries int_add(),
int_sub(), and int_mult(). This can be important when executing int_mid(); if the
result of the midpoint calculation has more decimal places than recognized by int_mid(), it will return the smallest possible interval
bracketing the middle point of the interval.

Remarks

int_mid() does not check if it is in fact true that the lower limits of intervals are less than or equal to upper limits; hence,
users must exert care that the numbers appearing in the odd columns i are less than their counterparts in even columns i+1.

Examples:

Consider the addition of two interval vectors:

. mata: X=.1,.4 \ .15,3 \10,12
. mata: int_mid(X)
1 2
+
+
1 | .25 .25 |
2 | 1.575 1.575 |
3 | 11 11 |
+
+

Conformability

X should have an even number of columns, where each pair of columns represents an interval vector.
Moreover, lower limits (entries in the first column) should be
less than upper limits (entries in the second column). Some care must be exercised in assuring this, as int_mid() does not check
whether or not it is true.

mid() -- Midpoints of intervals

Syntax

real matrix mid(real matrix X)

where

X: real matrix containing data (each pair of columns i,i+1 of which represent intervals)

Description

mid() computes the midpoints of the collection of intervals represented by X. It differs from the related command
int_mid() in that it returns results in scalar form. The midpoint of an interval is defined in the obvious
way; the midpoint of an interval is simply the average of its lower and upper bound. When confronted with the interval (4,6),
mid() returns the result 5.

Remarks

mid() does not check if it is in fact true that the lower limits of intervals are less than or equal to upper limits; hence,
users must exert care that the numbers appearing in the odd columns i are less than their counterparts in even columns i+1.

Examples:

Consider the addition of two interval vectors:

. mata: X=.1,.4 \ .15,3 \10,12
. mata: mid(X)
1
+--------+
1 | .25 |
2 | 1.575 |
3 | 11 |
+--------+

Conformability

X should have an even number of columns, where each pair of columns represents an interval vector.
Moreover, lower limits (entries in the first column) should be
less than upper limits (entries in the second column). Some care must be exercised in assuring this, as int_mid() does not check
whether or not it is true.

int_mince() -- Split a series of intervals in a larger list of intervals

Syntax

real matrix int_mince(real matrix X, real scalar t, real scalar n)

Description

int_mince() resolves a specific component of a collection of intervals into smaller intervals.
The scalar t points In int_mince() to the interval represented by columns 2t-1,2t of X,
while the scalar n tells int_mince() how many smaller intervals to break this interval into.

Example:

. mata: X=(0,1,1,2)
. mata: int_mince(X,2,4)
1 2 3 4
+
+
1 | 0 .5 1 1.25 |
2 | .5 1 1.25 1.5 |
3 | 0 .5 1.5 1.75 |
4 | .5 1 1.75 2 |
+
+

int_mesh() -- Create a mesh of intervals covering [0,1]^n

Syntax

real matrix int_mesh(real scalar n, real scalar t)

Description

int_mesh() creates disjoint intervals that cover the n-dimensional unit space [0,1]. The first argument n is the number
of desired dimensions, and t describes the number of desired points per dimension. The odd-numbered columns are the lower limits of
the intervals, while the even-numbered columns are upper limits. Be wary: the size of the resulting matrix expands rapidly in n and t!

Example:

. mata: int_mesh(3,2)
1 2 3 4 5 6
+
+
1 | 0 .5 0 .5 0 .5 |
2 | .5 1 0 .5 0 .5 |
3 | 0 .5 .5 1 0 .5 |
4 | .5 1 .5 1 0 .5 |
5 | 0 .5 0 .5 .5 1 |
6 | .5 1 0 .5 .5 1 |
7 | 0 .5 .5 1 .5 1 |
8 | .5 1 .5 1 .5 1 |
+
+

int_widths() -- Widths of intervals

Syntax

real matrix int_widths(real matrix X)

where

X: real matrix containing data (each pair of columns i,i+1 of which represent intervals)

Description

int_widths() computes the widths of the collection of interval column vectors represented by X.
The midpoint of an interval is defined in the obvious way; the distance between the upper limit and the lower limit.
When confronted with the interval (4,6),
int_widths() returns the result 2.

Remarks

int_widths() does not check if it is in fact true that the lower limits of intervals are less than or equal to upper limits; hence,
users must exert care that the numbers appearing in the odd columns i are less than their counterparts in even columns i+1.

Examples:

Consider the addition of two interval vectors:

. mata: X=.1,.4 \ .15,.3 \10,12
. mata: mid(X)
1 2 3
+
+
1 | .3 .15 2 |
+
+

Conformability

X should have an even number of columns, where each pair of columns represents an interval vector.
Moreover, lower limits (entries in the first column) should be
less than upper limits (entries in the second column). Some care must be exercised in assuring this, as int_widths() does not check
whether or not it is true.

radius() -- Radii of intervals

Syntax

real matrix radius(real matrix X)

where

X: real matrix containing data (each pair of columns i,i+1 of which represent intervals)

Description

radius() computes the radius of the collection of interval column vectors represented by X.
The radius is simply the distance from the center of an interval to its upper (and lower) limit.
When confronted with the interval (4,6), for example, radius((4,6)) returns the result 1.

Remarks

radius() does not check if lower limits of intervals are less than or equal to upper limits; hence,
users must exert care that the numbers appearing in the odd columns i are less than their counterparts
in even columns i+1.

Example:

. mata: X=.1,.4 \ .15,.3 \10,12
. mata: radius(X)
1 2 3
+
+
1 | .15 .075 2 |
+
+

Conformability

X should have an even number of columns, where each pair of columns represents an interval vector.
Moreover, lower limits (entries in the first column) should be
less than upper limits (entries in the second column). Some care must be exercised in assuring this, as radius() does not check
whether or not it is true.

r_up() -- Round numbers up

Syntax

real matrix r_up(real matrix X, real scalar digits)

where

X: real matrix containing data.

Description

r_up() rounds numbers up according to the decimal places indicated by digits.

Example:

. mata: X=.1234567891234
. mata: r_up(X,1e-4)
.124

Conformability

X can be any real matrix.

r_down() -- Round numbers down

Syntax

real matrix r_down(real matrix X, real scalar digits)

where

X: real matrix containing data.

Description

r_down() rounds numbers down according to the decimal places indicated by digits.

Example:

. mata: X=.1234567891234
. mata: r_down(X,1e-4)
.123

Conformability

X can be any real matrix.

Author

Matthew Baker, Hunter College and the Graduate Center, CUNY, mjbaker@hunter.cuny.edu

References

Jaulin, Luc, Michel Kieffer, Oliver Didrit, and Eric Walter. 2001. Applied Interval Analysis. London: Springer.

Moore, Ramon E., R. Baker Kearfott, and Michael J. Cloud. 2009. Introduction to Interval Analysis. Philadelphia: SIAM.