codac2_Matrix_addons_IntervalMatrixBase.h File Reference

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
template<int R = RowsAtCompileTime, int C = ColsAtCompileTime> requires IsIntervalDomain<Scalar>
	Matrix (const Matrix< double, R, C > &lb, const Matrix< double, R, C > &ub)
	Constructs an interval matrix from lower and upper bound matrices.
template<int R = RowsAtCompileTime, int C = ColsAtCompileTime> requires IsIntervalDomain<Scalar>
	Matrix (int r, int c, const double bounds[][2])
	Constructs an interval matrix from a 2D array of bounds.
auto &	init ()
	Initializes all elements of the matrix with default intervals.
template<int R = RowsAtCompileTime, int C = ColsAtCompileTime, typename OtherDerived> requires IsIntervalDomain<Scalar>
bool	operator== (const MatrixBase< OtherDerived > &x) const
	Compares this interval matrix with another matrix for equality.
double	min_rad () const
	Returns the minimum radius among the interval elements.
double	max_rad () const
	Returns the maximum radius among the interval elements.
double	min_diam () const
	Returns the minimum diameter among the interval elements.
double	max_diam () const
	Returns the maximum diameter among the interval elements.
Index	min_diam_index () const
	Returns the index of the element with the minimum diameter.
Index	max_diam_index () const
	Returns the index of the element with the maximum diameter.
Index	extr_diam_index (bool min) const
	Returns the index of the element with the minimum or maximum diameter.
void	set_empty ()
	Marks the interval matrix as empty.
auto &	inflate (double r)
	Inflates all intervals in the matrix by a fixed radius.
template<typename OtherDerived> requires IsIntervalDomain<Scalar>
auto &	inflate (const MatrixBase< OtherDerived > &r)
	Inflates each interval in the matrix by corresponding values from another matrix.
template<typename OtherDerived>
auto &	operator&= (const MatrixBase< OtherDerived > &x)
	Performs element-wise intersection assignment with another matrix.
template<typename OtherDerived>
auto &	operator|= (const MatrixBase< OtherDerived > &x)
	Performs element-wise union assignment with another matrix.
template<typename OtherDerived>
auto	operator& (const MatrixBase< OtherDerived > &x) const
	Returns the element-wise intersection of this matrix with another.
template<typename OtherDerived>
auto	operator| (const MatrixBase< OtherDerived > &x) const
	Returns the element-wise union of this matrix with another.
template<int R = RowsAtCompileTime, int C = ColsAtCompileTime> requires IsIntervalDomain<Scalar>
auto	bisect (Index i, float ratio=0.49) const
	Bisects the interval at the given index into two sub-interval matrices.
template<int R = RowsAtCompileTime, int C = ColsAtCompileTime> requires IsIntervalDomain<Scalar>
auto	bisect_largest (float ratio=0.49) const
	Bisects the interval with the largest diameter in the matrix.

Detailed Description

This class reuses some of the functions developed for ibex::IntervalMatrixBase. The original IBEX code is revised in modern C++ and adapted to the template structure proposed in Codac, based on the Eigen library. See ibex::IntervalMatrixBase (IBEX lib, author: Gilles Chabert)

This file is included in the declaration of Eigen::MatrixBase, thanks to the preprocessor token EIGEN_MATRIX_PLUGIN. See: https://eigen.tuxfamily.org/dox/TopicCustomizing_Plugins.html and the file codac2_matrices.h

---

Date

2024

Author

Simon Rohou, Gilles Chabert

Copyright

Copyright 2023 Codac Team

License: GNU Lesser General Public License (LGPL)

Function Documentation

Matrix() [1/2]

template<int R = RowsAtCompileTime, int C = ColsAtCompileTime>
requires IsIntervalDomain<Scalar>

Matrix	(	const Matrix< double, R, C > &	lb,
		const Matrix< double, R, C > &	ub )

Constructs an interval matrix from lower and upper bound matrices.

Initializes the interval matrix with the given lower bound matrix lb and upper bound matrix ub.

Each element of the resulting interval matrix is constructed from corresponding elements in lb and ub. If any lower bound element is greater than its corresponding upper bound element, the matrix is set to empty.

Parameters

lb	Matrix of lower bounds.
ub	Matrix of upper bounds.

Precondition

lb and ub must have the same size.

  : Matrix<Scalar,R,C>(lb)
{
  assert_release(lb.size() == ub.size());
 
  for(Index i = 0 ; i < this->size() ; i++)
  {
    auto& lbi = *(this->data()+i);
    const auto& ubi = *(ub.data()+i);
 
    if(lbi.lb() > ubi)
    {
      set_empty();
      break;
    }
 
    else
      lbi |= ubi;
  }
}

Matrix() [2/2]

template<int R = RowsAtCompileTime, int C = ColsAtCompileTime>
requires IsIntervalDomain<Scalar>

Matrix	(	int	r,
		int	c,
		const double	bounds[][2] )

Constructs an interval matrix from a 2D array of bounds.

Initializes the matrix with dimensions (r,c) where each element is set to an interval constructed from the corresponding pair of lower and upper bounds in the bounds array.

Parameters

r	Number of rows in the matrix.
c	Number of columns in the matrix.
bounds	2D array of size [r*c][2], where each sub-array contains the lower and upper bound for one element.

Precondition

r and c must be positive.

The bounds array size must exactly match the total number of elements.

Postcondition

Each matrix element (i,j) is initialized to codac2::Interval(bounds[k][0], bounds[k][1]) with k mapping row-major order index.

  : Matrix<Scalar,R,C>(r,c)
{
  assert_release(r > 0 && c > 0);
 
  Index k = 0;
  for(Index i = 0 ; i < this->rows() ; i++)
    for(Index j = 0 ; j < this->cols() ; j++)
    {
      (*this)(i,j) = codac2::Interval(bounds[k][0],bounds[k][1]);
      k++;
    }
  assert_release(k == this->size() && "incorrect array size");
}

init()

auto & init ( )

inline

Initializes all elements of the matrix with default intervals.

Sets every element in the matrix to a default-constructed codac2::Interval.

Returns

Reference to the current matrix object (enables method chaining).

{
  for(Index i = 0 ; i < this->size() ; i++)
    (this->data()+i)->init();
  return *this;
}

operator==()

template<int R = RowsAtCompileTime, int C = ColsAtCompileTime, typename OtherDerived>
requires IsIntervalDomain<Scalar>

bool operator== ( const MatrixBase< OtherDerived > & x ) const

inline

Compares this interval matrix with another matrix for equality.

Evaluates and casts the other matrix to an interval matrix, then performs an element-wise equality comparison.

Parameters

x	The other matrix (of arbitrary derived type) to compare.

Returns

true if the matrices are equal after casting; false otherwise.

{
  return operator==(x.eval().template cast<codac2::Interval>());
}

min_rad()

double min_rad ( ) const

inline

Returns the minimum radius among the interval elements.

Returns

The smallest radius value in the matrix.

{
  return (this->data()+extr_diam_index(true))->rad();
}

max_rad()

double max_rad ( ) const

inline

Returns the maximum radius among the interval elements.

Returns

The largest radius value in the matrix.

{
  return (this->data()+extr_diam_index(false))->rad();
}

min_diam()

double min_diam ( ) const

inline

Returns the minimum diameter among the interval elements.

Returns

The smallest diameter value in the matrix.

{
  return (this->data()+extr_diam_index(true))->diam();
}

max_diam()

double max_diam ( ) const

inline

Returns the maximum diameter among the interval elements.

Returns

The largest diameter value in the matrix.

{
  return (this->data()+extr_diam_index(false))->diam();
}

min_diam_index()

Index min_diam_index ( ) const

inline

Returns the index of the element with the minimum diameter.

Returns

The index of the matrix element with the smallest diameter.

{
  return extr_diam_index(true);
}

max_diam_index()

Index max_diam_index ( ) const

inline

Returns the index of the element with the maximum diameter.

Returns

The index of the matrix element with the largest diameter.

{
  return extr_diam_index(false);
}

extr_diam_index()

Index extr_diam_index ( bool min ) const

inline

Returns the index of the element with the minimum or maximum diameter.

Searches the matrix elements for the interval with either the smallest or largest diameter, depending on the min flag.

This method handles unbounded intervals specially:

• If looking for minimum diameter, unbounded intervals are ignored unless no bounded intervals exist.
• If looking for maximum diameter, unbounded intervals are considered.

Parameters

min	If true, returns the index of the element with minimum diameter; otherwise maximum diameter.

Returns

Index of the element with the minimum or maximum diameter.

Precondition

The matrix must not be empty (diameter undefined otherwise).

{
  // This code originates from the ibex-lib
  // See: ibex_TemplateVector.h
  // Author: Gilles Chabert
 
  double d = min ? codac2::oo : -1; // -1 to be sure that even a 0-diameter interval can be selected
  int selected_index = -1;
  bool unbounded = false;
  assert_release(!this->is_empty() && "Diameter of an empty IntervalVector is undefined");
 
  Index i;
 
  for(i = 0 ; i < this->size() ; i++) 
  {
    if((this->data()+i)->is_unbounded()) 
    {
      unbounded = true;
      if(!min) break;
    }
    else
    {
      double w = (this->data()+i)->diam();
      if(min ? w<d : w>d)
      {
        selected_index = i;
        d = w;
      }
    }
  }
 
  if(min && selected_index == -1)
  {
    assert(unbounded);
    // the selected interval is the first one.
    i = 0;
  }
 
  // The unbounded intervals are not considered if we look for the minimal diameter
  // and some bounded intervals have been found (selected_index!=-1)
  if(unbounded && (!min || selected_index == -1))
  {
    double pt = min ? -codac2::oo : codac2::oo; // keep the point less/most distant from +oo (we normalize if the lower bound is -oo)
    selected_index = i;
 
    for(; i < this->size() ; i++)
    {
      if((this->data()+i)->lb() == -codac2::oo)
      {
        if((this->data()+i)->ub() == codac2::oo)
          if(!min)
          {
            selected_index = i;
            break;
          }
 
        if((min && (-(this->data()+i)->ub() > pt)) || (!min && (-(this->data()+i)->ub() < pt)))
        {
          selected_index = i;
          pt = -(this->data()+i)->ub();
        }
      }
 
      else if((this->data()+i)->ub() == codac2::oo)
        if((min && ((this->data()+i)->lb() > pt)) || (!min && ((this->data()+i)->lb() < pt)))
        {
          selected_index = i;
          pt = (this->data()+i)->lb();
        }
    }
  }
 
  return selected_index;
}

set_empty()

void set_empty ( )

inline

Marks the interval matrix as empty.

Sets all elements to an empty interval.

{
  this->init(codac2::Interval::empty());
}

inflate() [1/2]

auto & inflate ( double r )

inline

Inflates all intervals in the matrix by a fixed radius.

Adds radius r to each interval element, expanding their bounds.

Parameters

r	The non-negative radius by which to inflate each interval.

Returns

Reference to the current matrix object (for chaining).

Precondition

r must be greater than or equal to zero.

{
  assert_release(r >= 0.);
 
  for(Index i = 0 ; i < this->size() ; i++)
    (this->data()+i)->inflate(r);
  return *this;
}

inflate() [2/2]

template<typename OtherDerived>
requires IsIntervalDomain<Scalar>

auto & inflate ( const MatrixBase< OtherDerived > & r )

inline

Inflates each interval in the matrix by corresponding values from another matrix.

Inflates each element by the radius specified at the same position in matrix r.

Parameters

r	Matrix containing non-negative inflation radii.

Returns

Reference to the current matrix object (for chaining).

Precondition

The size of this matrix and r must be the same.

All elements in r must be greater than or equal to zero.

{
  assert_release(this->size() == r.size());
  assert_release(r.min_coeff() >= 0.);
 
  for(Index i = 0 ; i < this->rows() ; i++)
    for(Index j = 0 ; j < this->cols() ; j++)
      (*this)(i,j).inflate(r(i,j));
  return *this;
}

operator&=()

template<typename OtherDerived>

auto & operator&= ( const MatrixBase< OtherDerived > & x )

inline

Performs element-wise intersection assignment with another matrix.

Updates each element of this matrix by intersecting it with the corresponding element of matrix x.

If x is empty, this matrix is set empty.

Parameters

x	The matrix to intersect with.

Returns

Reference to this matrix after intersection.

Precondition

The size of this matrix and x must be the same.

{
  assert_release(this->size() == x.size());
 
  if constexpr(std::is_same_v<typename MatrixBase<OtherDerived>::Scalar,codac2::Interval>)
  {
    if(x.is_empty())
    {
      set_empty();
      return *this;
    }
  }
  
  for(Index i = 0 ; i < this->rows() ; i++)
    for(Index j = 0 ; j < this->cols() ; j++)
      (*this)(i,j) &= x(i,j);
  return *this;
}

operator|=()

template<typename OtherDerived>

auto & operator|= ( const MatrixBase< OtherDerived > & x )

inline

Performs element-wise union assignment with another matrix.

Updates each element of this matrix by taking the union with the corresponding element of matrix x.

If x is empty, this matrix remains unchanged.

Parameters

x	The matrix to union with.

Returns

Reference to this matrix after union.

Precondition

The size of this matrix and x must be the same.

{
  assert_release(this->size() == x.size());
 
  if constexpr(std::is_same_v<typename MatrixBase<OtherDerived>::Scalar,codac2::Interval>)
  {
    if(x.is_empty())
      return *this;
  }
 
  for(Index i = 0 ; i < this->rows() ; i++)
    for(Index j = 0 ; j < this->cols() ; j++)
      (*this)(i,j) |= x(i,j);
  return *this;
}

operator&()

template<typename OtherDerived>

auto operator& ( const MatrixBase< OtherDerived > & x ) const

inline

Returns the element-wise intersection of this matrix with another.

Creates a copy of this matrix and performs element-wise intersection assignment with matrix x, then returns the result.

Parameters

x	The matrix to intersect with.

Returns

A new matrix representing the intersection.

{
  auto y = *this;
  return y &= x;
}

operator|()

template<typename OtherDerived>

auto operator| ( const MatrixBase< OtherDerived > & x ) const

inline

Returns the element-wise union of this matrix with another.

Creates a copy of this matrix and performs element-wise union assignment with the interval-casted matrix x, then returns the result.

Parameters

x	The matrix to union with.

Returns

A new matrix representing the union.

{
  auto y = *this;
  return y |= x.template cast<codac2::Interval>();
}

bisect()

template<int R = RowsAtCompileTime, int C = ColsAtCompileTime>
requires IsIntervalDomain<Scalar>

auto bisect ( Index i, float ratio = 0.49 ) const

inline

Bisects the interval at the given index into two sub-interval matrices.

Splits the interval at element index i into two parts according to the ratio and returns a pair of matrices having the two resulting sub-intervals.

Parameters

i	Index of the element to bisect (must be within valid range).
ratio	Ratio to determine the split point within the interval (default 0.49, must lie in [0,1]).

Returns

A pair of matrices resulting from the bisection.

Precondition

The element at index i must be bisectable.

{
  assert_release(i >= 0 && i < this->size());
  assert_release((this->data()+i)->is_bisectable());
  assert_release(codac2::Interval(0,1).interior_contains(ratio));
 
  auto p = std::make_pair(*this,*this);
  auto pi = (this->data()+i)->bisect(ratio);
  *(p.first.data()+i) = pi.first;
  *(p.second.data()+i) = pi.second;
  return p;
}

bisect_largest()

template<int R = RowsAtCompileTime, int C = ColsAtCompileTime>
requires IsIntervalDomain<Scalar>

auto bisect_largest ( float ratio = 0.49 ) const

inline

Bisects the interval with the largest diameter in the matrix.

Uses max_diam_index() to find the element with the largest diameter and bisects it using the given ratio.

Parameters

ratio

Ratio to determine the split point within the interval (default 0.49).

Returns

A pair of matrices resulting from the bisection of the largest diameter interval.

{
  return bisect(max_diam_index(), ratio);
}