Parma_Polyhedra_Library::Generator Class Reference
[C++ Language Interface]

A line, ray, point or closure point. More...

#include <ppl.hh>

Inherits Parma_Polyhedra_Library::Linear_Row.

Inherited by Parma_Polyhedra_Library::Grid_Generator [private].

Collaboration diagram for Parma_Polyhedra_Library::Generator:

Collaboration graph
[legend]

List of all members.

Public Types

enum  Type { LINE, RAY, POINT, CLOSURE_POINT }
 The generator type. More...

Public Member Functions

 Generator (const Generator &g)
 Ordinary copy-constructor.
 ~Generator ()
 Destructor.
Generatoroperator= (const Generator &g)
 Assignment operator.
dimension_type space_dimension () const
 Returns the dimension of the vector space enclosing *this.
Type type () const
 Returns the generator type of *this.
bool is_line () const
 Returns true if and only if *this is a line.
bool is_ray () const
 Returns true if and only if *this is a ray.
bool is_point () const
 Returns true if and only if *this is a point.
bool is_closure_point () const
 Returns true if and only if *this is a closure point.
Coefficient_traits::const_reference coefficient (Variable v) const
 Returns the coefficient of v in *this.
Coefficient_traits::const_reference divisor () const
 If *this is either a point or a closure point, returns its divisor.
memory_size_type total_memory_in_bytes () const
 Returns a lower bound to the total size in bytes of the memory occupied by *this.
memory_size_type external_memory_in_bytes () const
 Returns the size in bytes of the memory managed by *this.
bool is_equivalent_to (const Generator &y) const
 Returns true if and only if *this and y are equivalent generators.
bool OK () const
 Checks if all the invariants are satisfied.
void swap (Generator &y)
 Swaps *this with y.

Static Public Member Functions

static Generator line (const Linear_Expression &e)
 Returns the line of direction e.
static Generator ray (const Linear_Expression &e)
 Returns the ray of direction e.
static Generator point (const Linear_Expression &e=Linear_Expression::zero(), Coefficient_traits::const_reference d=Coefficient_one())
 Returns the point at e / d.
static Generator closure_point (const Linear_Expression &e=Linear_Expression::zero(), Coefficient_traits::const_reference d=Coefficient_one())
 Returns the closure point at e / d.
static dimension_type max_space_dimension ()
 Returns the maximum space dimension a Generator can handle.
static void initialize ()
 Initializes the class.
static void finalize ()
 Finalizes the class.
static const Generatorzero_dim_point ()
 Returns the origin of the zero-dimensional space $\Rset^0$.
static const Generatorzero_dim_closure_point ()
 Returns, as a closure point, the origin of the zero-dimensional space $\Rset^0$.

Related Functions

(Note that these are not member functions.)

std::ostream & operator<< (std::ostream &s, const Generator &g)
 Output operator.
void swap (Parma_Polyhedra_Library::Generator &x, Parma_Polyhedra_Library::Generator &y)
 Specializes std::swap.
bool operator== (const Generator &x, const Generator &y)
 Returns true if and only if x is equivalent to y.
bool operator!= (const Generator &x, const Generator &y)
 Returns true if and only if x is not equivalent to y.
template<typename To >
bool rectilinear_distance_assign (Checked_Number< To, Extended_Number_Policy > &r, const Generator &x, const Generator &y, Rounding_Dir dir)
 Computes the rectilinear (or Manhattan) distance between x and y.
template<typename Temp , typename To >
bool rectilinear_distance_assign (Checked_Number< To, Extended_Number_Policy > &r, const Generator &x, const Generator &y, Rounding_Dir dir, Temp &tmp0, Temp &tmp1, Temp &tmp2)
 Computes the rectilinear (or Manhattan) distance between x and y.
template<typename To >
bool euclidean_distance_assign (Checked_Number< To, Extended_Number_Policy > &r, const Generator &x, const Generator &y, Rounding_Dir dir)
 Computes the euclidean distance between x and y.
template<typename Temp , typename To >
bool euclidean_distance_assign (Checked_Number< To, Extended_Number_Policy > &r, const Generator &x, const Generator &y, Rounding_Dir dir, Temp &tmp0, Temp &tmp1, Temp &tmp2)
 Computes the euclidean distance between x and y.
template<typename To >
bool l_infinity_distance_assign (Checked_Number< To, Extended_Number_Policy > &r, const Generator &x, const Generator &y, Rounding_Dir dir)
 Computes the $L_\infty$ distance between x and y.
template<typename Temp , typename To >
bool l_infinity_distance_assign (Checked_Number< To, Extended_Number_Policy > &r, const Generator &x, const Generator &y, Rounding_Dir dir, Temp &tmp0, Temp &tmp1, Temp &tmp2)
 Computes the $L_\infty$ distance between x and y.
std::ostream & operator<< (std::ostream &s, const Generator::Type &t)
 Output operator.


Detailed Description

A line, ray, point or closure point.

An object of the class Generator is one of the following:

where $n$ is the dimension of the space and, for points and closure points, $d > 0$ is the divisor.

A note on terminology.
As observed in Section Representations of Convex Polyhedra, there are cases when, in order to represent a polyhedron $\cP$ using the generator system $\cG = (L, R, P, C)$, we need to include in the finite set $P$ even points of $\cP$ that are not vertices of $\cP$. This situation is even more frequent when working with NNC polyhedra and it is the reason why we prefer to use the word `point' where other libraries use the word `vertex'.
How to build a generator.
Each type of generator is built by applying the corresponding function (line, ray, point or closure_point) to a linear expression, representing a direction in the space; the space dimension of the generator is defined as the space dimension of the corresponding linear expression. Linear expressions used to define a generator should be homogeneous (any constant term will be simply ignored). When defining points and closure points, an optional Coefficient argument can be used as a common divisor for all the coefficients occurring in the provided linear expression; the default value for this argument is 1.
In all the following examples it is assumed that variables x, y and z are defined as follows:
  Variable x(0);
  Variable y(1);
  Variable z(2);
Example 1
The following code builds a line with direction $x-y-z$ and having space dimension $3$:
  Generator l = line(x - y - z);
As mentioned above, the constant term of the linear expression is not relevant. Thus, the following code has the same effect:
  Generator l = line(x - y - z + 15);
By definition, the origin of the space is not a line, so that the following code throws an exception:
  Generator l = line(0*x);
Example 2
The following code builds a ray with the same direction as the line in Example 1:
  Generator r = ray(x - y - z);
As is the case for lines, when specifying a ray the constant term of the linear expression is not relevant; also, an exception is thrown when trying to build a ray from the origin of the space.
Example 3
The following code builds the point $\vect{p} = (1, 0, 2)^\transpose \in \Rset^3$:
  Generator p = point(1*x + 0*y + 2*z);
The same effect can be obtained by using the following code:
  Generator p = point(x + 2*z);
Similarly, the origin $\vect{0} \in \Rset^3$ can be defined using either one of the following lines of code:
  Generator origin3 = point(0*x + 0*y + 0*z);
  Generator origin3_alt = point(0*z);
Note however that the following code would have defined a different point, namely $\vect{0} \in \Rset^2$:
  Generator origin2 = point(0*y);
The following two lines of code both define the only point having space dimension zero, namely $\vect{0} \in \Rset^0$. In the second case we exploit the fact that the first argument of the function point is optional.
  Generator origin0 = Generator::zero_dim_point();
  Generator origin0_alt = point();
Example 4
The point $\vect{p}$ specified in Example 3 above can also be obtained with the following code, where we provide a non-default value for the second argument of the function point (the divisor):
  Generator p = point(2*x + 0*y + 4*z, 2);
Obviously, the divisor can be usefully exploited to specify points having some non-integer (but rational) coordinates. For instance, the point $\vect{q} = (-1.5, 3.2, 2.1)^\transpose \in \Rset^3$ can be specified by the following code:
  Generator q = point(-15*x + 32*y + 21*z, 10);
If a zero divisor is provided, an exception is thrown.
Example 5
Closure points are specified in the same way we defined points, but invoking their specific constructor function. For instance, the closure point $\vect{c} = (1, 0, 2)^\transpose \in \Rset^3$ is defined by
  Generator c = closure_point(1*x + 0*y + 2*z);
For the particular case of the (only) closure point having space dimension zero, we can use any of the following:
  Generator closure_origin0 = Generator::zero_dim_closure_point();
  Generator closure_origin0_alt = closure_point();
How to inspect a generator
Several methods are provided to examine a generator and extract all the encoded information: its space dimension, its type and the value of its integer coefficients.
Example 6
The following code shows how it is possible to access each single coefficient of a generator. If g1 is a point having coordinates $(a_0, \ldots, a_{n-1})^\transpose$, we construct the closure point g2 having coordinates $(a_0, 2 a_1, \ldots, (i+1)a_i, \ldots, n a_{n-1})^\transpose$.
  if (g1.is_point()) {
    cout << "Point g1: " << g1 << endl;
    Linear_Expression e;
    for (dimension_type i = g1.space_dimension(); i-- > 0; )
      e += (i + 1) * g1.coefficient(Variable(i)) * Variable(i);
    Generator g2 = closure_point(e, g1.divisor());
    cout << "Closure point g2: " << g2 << endl;
  }
  else
    cout << "Generator g1 is not a point." << endl;
Therefore, for the point
  Generator g1 = point(2*x - y + 3*z, 2);
we would obtain the following output:
  Point g1: p((2*A - B + 3*C)/2)
  Closure point g2: cp((2*A - 2*B + 9*C)/2)
When working with (closure) points, be careful not to confuse the notion of coefficient with the notion of coordinate: these are equivalent only when the divisor of the (closure) point is 1.

Member Enumeration Documentation

The generator type.

Enumerator:
LINE  The generator is a line.
RAY  The generator is a ray.
POINT  The generator is a point.
CLOSURE_POINT  The generator is a closure point.

Reimplemented in Parma_Polyhedra_Library::Grid_Generator.


Member Function Documentation

Generator line ( const Linear_Expression e  )  [inline, static]

Returns the line of direction e.

Shorthand for Generator Generator::line(const Linear_Expression& e).

Exceptions:
std::invalid_argument Thrown if the homogeneous part of e represents the origin of the vector space.

Generator ray ( const Linear_Expression e  )  [inline, static]

Returns the ray of direction e.

Shorthand for Generator Generator::ray(const Linear_Expression& e).

Exceptions:
std::invalid_argument Thrown if the homogeneous part of e represents the origin of the vector space.

Generator point ( const Linear_Expression e = Linear_Expression::zero(),
Coefficient_traits::const_reference  d = Coefficient_one() 
) [inline, static]

Returns the point at e / d.

Shorthand for Generator Generator::point(const Linear_Expression& e, Coefficient_traits::const_reference d).

Both e and d are optional arguments, with default values Linear_Expression::zero() and Coefficient_one(), respectively.

Exceptions:
std::invalid_argument Thrown if d is zero.

Generator closure_point ( const Linear_Expression e = Linear_Expression::zero(),
Coefficient_traits::const_reference  d = Coefficient_one() 
) [inline, static]

Returns the closure point at e / d.

Shorthand for Generator Generator::closure_point(const Linear_Expression& e, Coefficient_traits::const_reference d).

Both e and d are optional arguments, with default values Linear_Expression::zero() and Coefficient_one(), respectively.

Exceptions:
std::invalid_argument Thrown if d is zero.

Coefficient_traits::const_reference Parma_Polyhedra_Library::Generator::coefficient ( Variable  v  )  const [inline]

Returns the coefficient of v in *this.

Exceptions:
std::invalid_argument Thrown if the index of v is greater than or equal to the space dimension of *this.

Reimplemented in Parma_Polyhedra_Library::Grid_Generator.

Coefficient_traits::const_reference Parma_Polyhedra_Library::Generator::divisor (  )  const [inline]

If *this is either a point or a closure point, returns its divisor.

Exceptions:
std::invalid_argument Thrown if *this is neither a point nor a closure point.

Reimplemented in Parma_Polyhedra_Library::Grid_Generator.

bool Parma_Polyhedra_Library::Generator::is_equivalent_to ( const Generator y  )  const

Returns true if and only if *this and y are equivalent generators.

Generators having different space dimensions are not equivalent.


Friends And Related Function Documentation

std::ostream & operator<< ( std::ostream &  s,
const Generator g 
) [related]

Output operator.

Specializes std::swap.

bool operator== ( const Generator x,
const Generator y 
) [related]

Returns true if and only if x is equivalent to y.

bool operator!= ( const Generator x,
const Generator y 
) [related]

Returns true if and only if x is not equivalent to y.

template<typename To >
bool rectilinear_distance_assign ( Checked_Number< To, Extended_Number_Policy > &  r,
const Generator x,
const Generator y,
Rounding_Dir  dir 
) [related]

Computes the rectilinear (or Manhattan) distance between x and y.

Computes the euclidean distance between x and y.

If the rectilinear distance between x and y is defined, stores an approximation of it into r and returns true; returns false otherwise.

The direction of the approximation is specified by dir.

All computations are performed using variables of type Checked_Number<To, Extended_Number_Policy>.

Note:
Distances are only defined between generators that are points and/or closure points; for rays or lines, false is returned.
If the rectilinear distance between x and y is defined, stores an approximation of it into r and returns true; returns false otherwise.

The direction of the approximation is specified by dir.

All computations are performed using variables of type Checked_Number<Temp, Extended_Number_Policy>.

Note:
Distances are only defined between generators that are points and/or closure points; for rays or lines, false is returned.
If the euclidean distance between x and y is defined, stores an approximation of it into r and returns true; returns false otherwise.

The direction of the approximation is specified by dir.

All computations are performed using variables of type Checked_Number<Temp, Extended_Number_Policy>.

Note:
Distances are only defined between generators that are points and/or closure points; for rays or lines, false is returned.

template<typename Temp , typename To >
bool rectilinear_distance_assign ( Checked_Number< To, Extended_Number_Policy > &  r,
const Generator x,
const Generator y,
Rounding_Dir  dir,
Temp &  tmp0,
Temp &  tmp1,
Temp &  tmp2 
) [related]

Computes the rectilinear (or Manhattan) distance between x and y.

If the rectilinear distance between x and y is defined, stores an approximation of it into r and returns true; returns false otherwise.

The direction of the approximation is specified by dir.

All computations are performed using the temporary variables tmp0, tmp1 and tmp2.

Note:
Distances are only defined between generators that are points and/or closure points; for rays or lines, false is returned.

template<typename To >
bool euclidean_distance_assign ( Checked_Number< To, Extended_Number_Policy > &  r,
const Generator x,
const Generator y,
Rounding_Dir  dir 
) [related]

Computes the euclidean distance between x and y.

If the euclidean distance between x and y is defined, stores an approximation of it into r and returns true; returns false otherwise.

The direction of the approximation is specified by dir.

All computations are performed using variables of type Checked_Number<To, Extended_Number_Policy>.

Note:
Distances are only defined between generators that are points and/or closure points; for rays or lines, false is returned.

template<typename Temp , typename To >
bool euclidean_distance_assign ( Checked_Number< To, Extended_Number_Policy > &  r,
const Generator x,
const Generator y,
Rounding_Dir  dir,
Temp &  tmp0,
Temp &  tmp1,
Temp &  tmp2 
) [related]

Computes the euclidean distance between x and y.

If the euclidean distance between x and y is defined, stores an approximation of it into r and returns true; returns false otherwise.

The direction of the approximation is specified by dir.

All computations are performed using the temporary variables tmp0, tmp1 and tmp2.

Note:
Distances are only defined between generators that are points and/or closure points; for rays or lines, false is returned.

template<typename To >
bool l_infinity_distance_assign ( Checked_Number< To, Extended_Number_Policy > &  r,
const Generator x,
const Generator y,
Rounding_Dir  dir 
) [related]

Computes the $L_\infty$ distance between x and y.

If the $L_\infty$ distance between x and y is defined, stores an approximation of it into r and returns true; returns false otherwise.

The direction of the approximation is specified by dir.

All computations are performed using variables of type Checked_Number<To, Extended_Number_Policy>.

Note:
Distances are only defined between generators that are points and/or closure points; for rays or lines, false is returned.
If the $L_\infty$ distance between x and y is defined, stores an approximation of it into r and returns true; returns false otherwise.

The direction of the approximation is specified by dir.

All computations are performed using variables of type Checked_Number<Temp, Extended_Number_Policy>.

Note:
Distances are only defined between generators that are points and/or closure points; for rays or lines, false is returned.

template<typename Temp , typename To >
bool l_infinity_distance_assign ( Checked_Number< To, Extended_Number_Policy > &  r,
const Generator x,
const Generator y,
Rounding_Dir  dir,
Temp &  tmp0,
Temp &  tmp1,
Temp &  tmp2 
) [related]

Computes the $L_\infty$ distance between x and y.

If the $L_\infty$ distance between x and y is defined, stores an approximation of it into r and returns true; returns false otherwise.

The direction of the approximation is specified by dir.

All computations are performed using the temporary variables tmp0, tmp1 and tmp2.

Note:
Distances are only defined between generators that are points and/or closure points; for rays or lines, false is returned.

std::ostream & operator<< ( std::ostream &  s,
const Generator::Type t 
) [related]

Output operator.


The documentation for this class was generated from the following file:

Generated on Tue Oct 7 22:03:26 2008 for PPL by  doxygen 1.5.7.1