PPL  0.12.1
Parma_Polyhedra_Library::Grid_Generator Class Reference

A grid line, parameter or grid point. More...

#include <ppl.hh>

Inheritance diagram for Parma_Polyhedra_Library::Grid_Generator:

List of all members.

Public Types

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

Public Member Functions

 Grid_Generator (const Grid_Generator &g)
 Ordinary copy constructor.
 ~Grid_Generator ()
 Destructor.
Grid_Generatoroperator= (const Grid_Generator &g)
 Assignment operator.
Grid_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_parameter () const
 Returns true if and only if *this is a parameter.
bool is_line_or_parameter () const
 Returns true if and only if *this is a line or a parameter.
bool is_point () const
 Returns true if and only if *this is a point.
bool is_parameter_or_point () const
 Returns true if and only if *this row represents a parameter or a point.
Coefficient_traits::const_reference coefficient (Variable v) const
 Returns the coefficient of v in *this.
Coefficient_traits::const_reference divisor () const
 Returns the divisor of *this.
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 Grid_Generator &y) const
 Returns true if and only if *this and y are equivalent generators.
bool is_equal_to (const Grid_Generator &y) const
 Returns true if *this is exactly equal to y.
bool is_equal_at_dimension (dimension_type dim, const Grid_Generator &gg) const
 Returns true if *this is equal to gg in dimension dim.
bool all_homogeneous_terms_are_zero () const
 Returns true if and only if all the homogeneous terms of *this are $0$.
void ascii_dump () const
 Writes to std::cerr an ASCII representation of *this.
void ascii_dump (std::ostream &s) const
 Writes to s an ASCII representation of *this.
void print () const
 Prints *this to std::cerr using operator<<.
bool ascii_load (std::istream &s)
 Loads from s an ASCII representation (as produced by ascii_dump(std::ostream&) const) and sets *this accordingly. Returns true if successful, false otherwise.
bool OK () const
 Checks if all the invariants are satisfied.
void m_swap (Grid_Generator &y)
 Swaps *this with y.
void coefficient_swap (Grid_Generator &y)
 Swaps *this with y, leaving *this with the original capacity.

Static Public Member Functions

static Grid_Generator grid_line (const Linear_Expression &e)
 Returns the line of direction e.
static Grid_Generator parameter (const Linear_Expression &e=Linear_Expression::zero(), Coefficient_traits::const_reference d=Coefficient_one())
 Returns the parameter of direction e and size e/d.
static Grid_Generator grid_point (const Linear_Expression &e=Linear_Expression::zero(), Coefficient_traits::const_reference d=Coefficient_one())
 Returns the point at e / d.
static dimension_type max_space_dimension ()
 Returns the maximum space dimension a Grid_Generator can handle.
static void initialize ()
 Initializes the class.
static void finalize ()
 Finalizes the class.
static const Grid_Generatorzero_dim_point ()
 Returns 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 Grid_Generator &g)
 Output operator.
void swap (Grid_Generator &x, Grid_Generator &y)
 Swaps x with y.
Grid_Generator grid_line (const Linear_Expression &e)
 Shorthand for Grid_Generator::grid_line(const Linear_Expression& e).
Grid_Generator parameter (const Linear_Expression &e=Linear_Expression::zero(), Coefficient_traits::const_reference d=Coefficient_one())
 Shorthand for Grid_Generator::parameter(const Linear_Expression& e, Coefficient_traits::const_reference d).
Grid_Generator grid_point (const Linear_Expression &e=Linear_Expression::zero(), Coefficient_traits::const_reference d=Coefficient_one())
 Shorthand for Grid_Generator::grid_point(const Linear_Expression& e, Coefficient_traits::const_reference d).
bool operator== (const Grid_Generator &x, const Grid_Generator &y)
 Returns true if and only if x is equivalent to y.
bool operator!= (const Grid_Generator &x, const Grid_Generator &y)
 Returns true if and only if x is not equivalent to y.
std::ostream & operator<< (std::ostream &s, const Grid_Generator::Type &t)
 Output operator.
bool operator== (const Grid_Generator &x, const Grid_Generator &y)
bool operator!= (const Grid_Generator &x, const Grid_Generator &y)
Grid_Generator grid_line (const Linear_Expression &e)
Grid_Generator parameter (const Linear_Expression &e, Coefficient_traits::const_reference d)
Grid_Generator grid_point (const Linear_Expression &e, Coefficient_traits::const_reference d)
void swap (Grid_Generator &x, Grid_Generator &y)

Detailed Description

A grid line, parameter or grid point.

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

  • a grid_line $\vect{l} = (a_0, \ldots, a_{n-1})^\transpose$;
  • a parameter $\vect{q} = (\frac{a_0}{d}, \ldots, \frac{a_{n-1}}{d})^\transpose$;
  • a grid_point $\vect{p} = (\frac{a_0}{d}, \ldots, \frac{a_{n-1}}{d})^\transpose$;

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

How to build a grid generator.
Each type of generator is built by applying the corresponding function (grid_line, parameter or grid_point) to a linear expression; 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 grid points and parameters, 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 grid line with direction $x-y-z$ and having space dimension $3$:
  Grid_Generator l = grid_line(x - y - z);
By definition, the origin of the space is not a line, so that the following code throws an exception:
Example 2
The following code builds the parameter as the vector $\vect{p} = (1, -1, -1)^\transpose \in \Rset^3$ which has the same direction as the line in Example 1:
  Grid_Generator q = parameter(x - y - z);
Note that, unlike lines, for parameters, the length as well as the direction of the vector represented by the code is significant. Thus q is not the same as the parameter q1 defined by
  Grid_Generator q1 = parameter(2x - 2y - 2z);
By definition, the origin of the space is not a parameter, so that the following code throws an exception:
Example 3
The following code builds the grid point $\vect{p} = (1, 0, 2)^\transpose \in \Rset^3$:
  Grid_Generator p = grid_point(1*x + 0*y + 2*z);
The same effect can be obtained by using the following code:
  Grid_Generator p = grid_point(x + 2*z);
Similarly, the origin $\vect{0} \in \Rset^3$ can be defined using either one of the following lines of code:
  Grid_Generator origin3 = grid_point(0*x + 0*y + 0*z);
  Grid_Generator origin3_alt = grid_point(0*z);
Note however that the following code would have defined a different point, namely $\vect{0} \in \Rset^2$:
  Grid_Generator origin2 = grid_point(0*y);
The following two lines of code both define the only grid 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.
Example 4
The grid 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 grid_point (the divisor):
  Grid_Generator p = grid_point(2*x + 0*y + 4*z, 2);
Obviously, the divisor can be used to specify points having some non-integer (but rational) coordinates. For instance, the grid point $\vect{p1} = (-1.5, 3.2, 2.1)^\transpose \in \Rset^3$ can be specified by the following code:
  Grid_Generator p1 = grid_point(-15*x + 32*y + 21*z, 10);
If a zero divisor is provided, an exception is thrown.
Example 5
Parameters, like grid points can have a divisor. For instance, the parameter $\vect{q} = (1, 0, 2)^\transpose \in \Rset^3$ can be defined:
  Grid_Generator q = parameter(2*x + 0*y + 4*z, 2);
Also, the divisor can be used to specify parameters having some non-integer (but rational) coordinates. For instance, the parameter $\vect{q} = (-1.5, 3.2, 2.1)^\transpose \in \Rset^3$ can be defined:
  Grid_Generator q = parameter(-15*x + 32*y + 21*z, 10);
If a zero divisor is provided, an exception is thrown.
How to inspect a grid generator
Several methods are provided to examine a grid generator and extract all the encoded information: its space dimension, its type and the value of its integer coefficients and the value of the denominator.
Example 6
The following code shows how it is possible to access each single coefficient of a grid generator. If g1 is a grid point having coordinates $(a_0, \ldots, a_{n-1})^\transpose$, we construct the parameter g2 having coordinates $(a_0, 2 a_1, \ldots, (i+1)a_i, \ldots, n a_{n-1})^\transpose$.
  if (g1.is_point()) {
    cout << "Grid 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);
    Grid_Generator g2 = parameter(e, g1.divisor());
    cout << "Parameter g2: " << g2 << endl;
  }
  else
    cout << "Grid Generator g1 is not a grid point." << endl;
Therefore, for the grid point
  Grid_Generator g1 = grid_point(2*x - y + 3*z, 2);
we would obtain the following output:
  Grid point g1: p((2*A - B + 3*C)/2)
  Parameter g2: parameter((2*A - 2*B + 9*C)/2)
When working with grid points and parameters, be careful not to confuse the notion of coefficient with the notion of coordinate: these are equivalent only when the divisor is 1.

Member Enumeration Documentation

The generator type.

Enumerator:
LINE 

The generator is a grid line.

PARAMETER 

The generator is a parameter.

POINT 

The generator is a grid point.

Reimplemented from Parma_Polyhedra_Library::Generator.


Member Function Documentation

Returns the line of direction e.

Exceptions:
std::invalid_argumentThrown if the homogeneous part of e represents the origin of the vector space.
static Grid_Generator Parma_Polyhedra_Library::Grid_Generator::parameter ( const Linear_Expression e = Linear_Expression::zero(),
Coefficient_traits::const_reference  d = Coefficient_one() 
)
static

Returns the parameter of direction e and size e/d.

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

Exceptions:
std::invalid_argumentThrown if d is zero.
static Grid_Generator Parma_Polyhedra_Library::Grid_Generator::grid_point ( const Linear_Expression e = Linear_Expression::zero(),
Coefficient_traits::const_reference  d = Coefficient_one() 
)
static

Returns the point at e / d.

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

Exceptions:
std::invalid_argumentThrown if d is zero.
Coefficient_traits::const_reference Parma_Polyhedra_Library::Grid_Generator::coefficient ( Variable  v) const
inline

Returns the coefficient of v in *this.

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

Reimplemented from Parma_Polyhedra_Library::Generator.

Coefficient_traits::const_reference Parma_Polyhedra_Library::Grid_Generator::divisor ( ) const
inline

Returns the divisor of *this.

Exceptions:
std::invalid_argumentThrown if *this is a line.

Reimplemented from Parma_Polyhedra_Library::Generator.

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

Generators having different space dimensions are not equivalent.

Swaps *this with y, leaving *this with the original capacity.

All elements up to and including the last element of the smaller of *this and y are swapped. The parameter divisor element of y is swapped with the divisor element of *this.


Friends And Related Function Documentation

std::ostream & operator<< ( std::ostream &  s,
const Grid_Generator g 
)
related

Output operator.

void swap ( Grid_Generator x,
Grid_Generator y 
)
related

Swaps x with y.

Grid_Generator parameter ( const Linear_Expression e = Linear_Expression::zero(),
Coefficient_traits::const_reference  d = Coefficient_one() 
)
related

Shorthand for Grid_Generator::parameter(const Linear_Expression& e, Coefficient_traits::const_reference d).

Grid_Generator grid_point ( const Linear_Expression e = Linear_Expression::zero(),
Coefficient_traits::const_reference  d = Coefficient_one() 
)
related

Shorthand for Grid_Generator::grid_point(const Linear_Expression& e, Coefficient_traits::const_reference d).

bool operator== ( const Grid_Generator x,
const Grid_Generator y 
)
related

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

bool operator!= ( const Grid_Generator x,
const Grid_Generator y 
)
related

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

std::ostream & operator<< ( std::ostream &  s,
const Grid_Generator::Type t 
)
related

Output operator.

bool operator== ( const Grid_Generator x,
const Grid_Generator y 
)
related
bool operator!= ( const Grid_Generator x,
const Grid_Generator y 
)
related
Grid_Generator grid_line ( const Linear_Expression e)
related
Grid_Generator parameter ( const Linear_Expression e,
Coefficient_traits::const_reference  d 
)
related
Grid_Generator grid_point ( const Linear_Expression e,
Coefficient_traits::const_reference  d 
)
related
void swap ( Grid_Generator x,
Grid_Generator y 
)
related

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