Parma_Polyhedra_Library::Grid_Generator Class Reference
C++ Language Interface

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

`#include <ppl.hh>`

## Public Types

enum | Kind
| The possible kinds of Grid_Generator objects.
enum | Type { LINE, PARAMETER, POINT }
| The generator type. More...
typedef Expression_Hide_Last< Expression_Hide_Inhomo< Linear_Expression > > | expr_type
| The type of the (adapted) internal expression.

## Public Member Functions

| Grid_Generator (Representation r=default_representation)
| Returns the origin of the zero-dimensional space .
| Grid_Generator (const Grid_Generator &g)
| Grid_Generator (const Grid_Generator &g, Representation r)
| Copy constructor with specified representation.
| Grid_Generator (const Grid_Generator &g, dimension_type space_dim)
| Grid_Generator (const Grid_Generator &g, dimension_type space_dim, Representation r)
| Copy constructor with specified space dimension and representation.
| ~Grid_Generator ()
| Destructor.
Grid_Generator & | operator= (const Grid_Generator &g)
| Assignment operator.
Representation | representation () const
| Returns the current representation of *this.
void | set_representation (Representation r)
| Converts *this to the specified representation.
dimension_type | space_dimension () const
| Returns the dimension of the vector space enclosing `*this`.
void | set_space_dimension (dimension_type space_dim)
void | swap_space_dimensions (Variable v1, Variable v2)
| Swaps the coefficients of the variables `v1` and `v2` .
bool | remove_space_dimensions (const Variables_Set &vars)
| Removes all the specified dimensions from the grid generator. More...
void | permute_space_dimensions (const std::vector< Variable > &cycle)
| Permutes the space dimensions of the grid generator.
void | shift_space_dimensions (Variable v, dimension_type n)
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`. More...
Coefficient_traits::const_reference | divisor () const
| Returns the divisor of `*this`. More...
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. More...
bool | is_equal_to (const Grid_Generator &y) const
| Returns `true` if `*this` is identical to `y`. More...
bool | all_homogeneous_terms_are_zero () const
| Returns `true` if and only if all the homogeneous terms of `*this` are .
bool | OK () const
| Checks if all the invariants are satisfied.
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.
void | m_swap (Grid_Generator &y)
| Swaps `*this` with `y`.
void | scale_to_divisor (Coefficient_traits::const_reference d)
| Scales `*this` to be represented with a divisor of `d` (if \*this is a parameter or point). Does nothing at all on lines. More...
void | set_divisor (Coefficient_traits::const_reference d)
| Sets the divisor of `*this` to `d`. More...
expr_type | expression () const
| Partial read access to the (adapted) internal expression.

## Static Public Member Functions

static Grid_Generator | grid_line (const Linear_Expression &e, Representation r=default_representation)
| Returns the line of direction `e`. More...
static Grid_Generator | parameter (const Linear_Expression &e=Linear_Expression::zero(), Coefficient_traits::const_reference d=Coefficient_one(), Representation r=default_representation)
static Grid_Generator | parameter (Representation r)
| Returns the parameter of direction and size `Linear_Expression::zero()` .
static Grid_Generator | parameter (const Linear_Expression &e, Representation r)
| Returns the parameter of direction and size `e` .
static Grid_Generator | grid_point (const Linear_Expression &e=Linear_Expression::zero(), Coefficient_traits::const_reference d=Coefficient_one(), Representation r=default_representation)
| Returns the point at `e` / `d`. More...
static Grid_Generator | grid_point (Representation r)
| Returns the point at `e` .
static Grid_Generator | grid_point (const Linear_Expression &e, Representation r)
| Returns the point at `e` .
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_Generator & | zero_dim_point ()
| Returns the origin of the zero-dimensional space .

## Static Public Attributes

static const Representation | default_representation = SPARSE
| The representation used for new Grid_Generators. More...

## Related Functions

(Note that these are not member functions.)
std::ostream & | operator<< (std::ostream &s, const Grid_Generator &g)
| Output operator. More...
void | swap (Grid_Generator &x, Grid_Generator &y)
| Swaps `x` with `y`. More...
Grid_Generator | grid_line (const Linear_Expression &e, Representation r=Grid_Generator::default_representation)
| Shorthand for Grid_Generator::grid_line(const Linear_Expression& e, Representation r).
Grid_Generator | parameter (const Linear_Expression &e=Linear_Expression::zero(), Coefficient_traits::const_reference d=Coefficient_one(), Representation r=Grid_Generator::default_representation)
| Shorthand for Grid_Generator::parameter(const Linear_Expression& e, Coefficient_traits::const_reference d, Representation r).
Grid_Generator | parameter (Representation r)
| Shorthand for Grid_Generator::parameter(Representation r). More...
Grid_Generator | parameter (const Linear_Expression &e, Representation r)
| Shorthand for Grid_Generator::parameter(const Linear_Expression& e, Representation r).
Grid_Generator | grid_point (const Linear_Expression &e=Linear_Expression::zero(), Coefficient_traits::const_reference d=Coefficient_one(), Representation r=Grid_Generator::default_representation)
| Shorthand for Grid_Generator::grid_point(const Linear_Expression& e, Coefficient_traits::const_reference d, Representation r).
Grid_Generator | grid_point (Representation r)
| Shorthand for Grid_Generator::grid_point(Representation r). More...
Grid_Generator | grid_point (const Linear_Expression &e, Representation r)
| Shorthand for Grid_Generator::grid_point(const Linear_Expression& e, Representation r).
bool | operator== (const Grid_Generator &x, const Grid_Generator &y)
| Returns `true` if and only if `x` is equivalent to `y`. More...
bool | operator!= (const Grid_Generator &x, const Grid_Generator &y)
| Returns `true` if and only if `x` is not equivalent to `y`. More...
std::ostream & | operator<< (std::ostream &s, const Grid_Generator::Type &t)
| Output operator. More...
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, Representation r)
Grid_Generator | parameter (const Linear_Expression &e, Coefficient_traits::const_reference d, Representation r)
Grid_Generator | parameter (Representation r)
Grid_Generator | parameter (const Linear_Expression &e, Representation r)
Grid_Generator | grid_point (const Linear_Expression &e, Coefficient_traits::const_reference d, Representation r)
Grid_Generator | grid_point (Representation r)
Grid_Generator | grid_point (const Linear_Expression &e, Representation r)
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 ;
- a parameter ;
- a grid_point ;

where is the dimension of the space and, for grid_points and parameters, 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 and having space dimension :
  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:
  Grid_Generator l = grid_line(0*x);

Example 2
  The following code builds the parameter as the vector 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:
  Grid_Generator q = parameter(0*x);

Example 3
  The following code builds the grid point :
  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 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 :
  Grid_Generator origin2 = grid_point(0*y);
  The following two lines of code both define the only grid point having space dimension zero, namely . In the second case we exploit the fact that the first argument of the function `point` is optional.
  Grid_Generator origin0 = Generator::zero_dim_point();
  Grid_Generator origin0_alt = grid_point();

Example 4
  The grid point 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 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 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 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 , we construct the parameter `g2` having coordinates .
  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.

## Constructor & Destructor Documentation

Parma_Polyhedra_Library::Grid_Generator::Grid_Generator | ( | const Grid_Generator & | g | ) |

inline

Ordinary copy constructor. The new Grid_Generator will have the same representation as g.

Parma_Polyhedra_Library::Grid_Generator::Grid_Generator | ( | const Grid_Generator & | g,
|  | dimension_type | space_dim
| ) |  |

inline

Copy constructor with specified space dimension. The new Grid_Generator will have the same representation as g.

## Member Function Documentation

static Grid_Generator Parma_Polyhedra_Library::Grid_Generator::grid_line | ( | const Linear_Expression & | e,
|  | Representation | r = `default_representation`
| ) |  |

static

Returns the line of direction `e`.

Exceptions

  std::invalid_argument | Thrown 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()`,
|  | Representation | r = `default_representation`
| ) |  |

static

Returns the parameter of direction `e` and size `e/d`, with the same representation as e.

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.

static Grid_Generator Parma_Polyhedra_Library::Grid_Generator::grid_point | ( | const Linear_Expression & | e = `Linear_Expression::zero()`,
|  | Coefficient_traits::const_reference | d = `Coefficient_one()`,
|  | Representation | r = `default_representation`
| ) |  |

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_argument | Thrown if `d` is zero.

void Parma_Polyhedra_Library::Grid_Generator::set_space_dimension | ( | dimension_type | space_dim | ) |

inline

Sets the dimension of the vector space enclosing `*this` to `space_dim` .

bool Parma_Polyhedra_Library::Grid_Generator::remove_space_dimensions | ( | const Variables_Set & | vars | ) |

Removes all the specified dimensions from the grid generator.

The space dimension of the variable with the highest space dimension in `vars` must be at most the space dimension of `this`.

Always returns `true`. The return value is needed for compatibility with the Generator class.

void Parma_Polyhedra_Library::Grid_Generator::shift_space_dimensions | ( | Variable | v,
|  | dimension_type | n
| ) |  |

inline

Shift by `n` positions the coefficients of variables, starting from the coefficient of `v`. This increases the space dimension by `n`.

Coefficient_traits::const_reference Parma_Polyhedra_Library::Grid_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`.

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

inline

Returns the divisor of `*this`.

Exceptions

  std::invalid_argument | Thrown if `*this` is a line.

bool Parma_Polyhedra_Library::Grid_Generator::is_equivalent_to | ( | const Grid_Generator & | y | ) | const

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

Generators having different space dimensions are not equivalent.

bool Parma_Polyhedra_Library::Grid_Generator::is_equal_to | ( | const Grid_Generator & | y | ) | const

Returns `true` if `*this` is identical to `y`.

This is faster than is_equivalent_to(), but it may return `false' even for equivalent generators.

void Parma_Polyhedra_Library::Grid_Generator::scale_to_divisor | ( | Coefficient_traits::const_reference | d | ) |

Scales `*this` to be represented with a divisor of `d` (if \*this is a parameter or point). Does nothing at all on lines.

It is assumed that `d` is a multiple of the current divisor and different from zero. The behavior is undefined if the assumption does not hold.

void Parma_Polyhedra_Library::Grid_Generator::set_divisor | ( | Coefficient_traits::const_reference | d | ) |

inline

Sets the divisor of `*this` to `d`.

Exceptions

  std::invalid_argument | Thrown if `*this` is a line.

## 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 | ( | Representation | r | ) |

related

Shorthand for Grid_Generator::parameter(Representation r).

Grid_Generator grid_point | ( | Representation | r | ) |

related

Shorthand for Grid_Generator::grid_point(Representation r).

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,
|  | Representation | r
| ) |  |

related

Grid_Generator parameter | ( | const Linear_Expression & | e,
|  | Coefficient_traits::const_reference | d,
|  | Representation | r
| ) |  |

related

Grid_Generator parameter | ( | Representation | r | ) |

related

Grid_Generator parameter | ( | const Linear_Expression & | e,
|  | Representation | r
| ) |  |

related

Grid_Generator grid_point | ( | const Linear_Expression & | e,
|  | Coefficient_traits::const_reference | d,
|  | Representation | r
| ) |  |

related

Grid_Generator grid_point | ( | Representation | r | ) |

related

Grid_Generator grid_point | ( | const Linear_Expression & | e,
|  | Representation | r
| ) |  |

related

void swap | ( | Grid_Generator & | x,
|  | Grid_Generator & | y
| ) |  |

related

## Member Data Documentation

const Representation Parma_Polyhedra_Library::Grid_Generator::default_representation = SPARSE

static

The representation used for new Grid_Generators.

Note
  The copy constructor and the copy constructor with specified size use the representation of the original object, so that it is indistinguishable from the original object.

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

- ppl.hh