The C<--with-piplib> option can
be used to specify which C<piplib>
library to use, either an installed version (C<system>),
-an externally built version (C<build>), a bundled version (C<bundled>)
+an externally built version (C<build>)
or no version (C<no>). The option C<build> is mostly useful
in C<configure> scripts of larger projects that bundle both C<isl>
and C<piplib>.
=item C<--with-piplib>
-Which copy of C<piplib> to use, either C<no> (default), C<system>, C<build>
-or C<bundled>. Note that C<bundled> only works if you have obtained
-C<isl> and its submodules from the git repository.
+Which copy of C<piplib> to use, either C<no> (default), C<system> or C<build>.
=item C<--with-piplib-prefix>
appear between those of the set variables and those
of the parameters.
-=head3 Dumping the internal state
-
-For lack of proper output functions, the following functions
-can be used to dump the internal state of a set or relation.
-The user should not depend on the output format of these functions.
-
- void isl_basic_set_dump(__isl_keep isl_basic_set *bset,
- FILE *out, int indent);
- void isl_basic_map_dump(__isl_keep isl_basic_map *bmap,
- FILE *out, int indent);
- void isl_set_dump(__isl_keep isl_set *set,
- FILE *out, int indent);
- void isl_map_dump(__isl_keep isl_map *map,
- FILE *out, int indent);
-
=head2 Creating New Sets and Relations
C<isl> has functions for creating some standard sets and relations.
bset = isl_basic_set_read_from_str(ctx,
"{[i] : exists (a : i = 2a and i >= 10 and i <= 42)}", -1);
+=head2 Inspecting Sets and Relations
+
+Usually, the user should not have to care about the actual constraints
+of the sets and maps, but should instead apply the abstract operations
+explained in the following sections.
+Occasionally, however, it may be required to inspect the individual
+coefficients of the constraints. This section explains how to do so.
+In these cases, it may also be useful to have C<isl> compute
+an explicit representation of the existentially quantified variables.
+
+ __isl_give isl_set *isl_set_compute_divs(
+ __isl_take isl_set *set);
+ __isl_give isl_map *isl_map_compute_divs(
+ __isl_take isl_map *map);
+
+This explicit representation defines the existentially quantified
+variables as integer divisions of the other variables, possibly
+including earlier existentially quantified variables.
+An explicitly represented existentially quantified variable therefore
+has a unique value when the values of the other variables are known.
+If, furthermore, the same existentials, i.e., existentials
+with the same explicit representations, should appear in the
+same order in each of the disjuncts of a set or map, then the user should call
+either of the following functions.
+
+ __isl_give isl_set *isl_set_align_divs(
+ __isl_take isl_set *set);
+ __isl_give isl_map *isl_map_align_divs(
+ __isl_take isl_map *map);
+
+To iterate over all the basic sets or maps in a set or map, use
+
+ int isl_set_foreach_basic_set(__isl_keep isl_set *set,
+ int (*fn)(__isl_take isl_basic_set *bset, void *user),
+ void *user);
+ int isl_map_foreach_basic_map(__isl_keep isl_map *map,
+ int (*fn)(__isl_take isl_basic_map *bmap, void *user),
+ void *user);
+
+The callback function C<fn> should return 0 if successful and
+-1 if an error occurs. In the latter case, or if any other error
+occurs, the above functions will return -1.
+
+It should be noted that C<isl> does not guarantee that
+the basic sets or maps passed to C<fn> are disjoint.
+If this is required, then the user should call one of
+the following functions first.
+
+ __isl_give isl_set *isl_set_make_disjoint(
+ __isl_take isl_set *set);
+ __isl_give isl_map *isl_map_make_disjoint(
+ __isl_take isl_map *map);
+
+To iterate over the constraints of a basic set or map, use
+
+ #include <isl_constraint.h>
+
+ int isl_basic_map_foreach_constraint(
+ __isl_keep isl_basic_map *bmap,
+ int (*fn)(__isl_take isl_constraint *c, void *user),
+ void *user);
+ void isl_constraint_free(struct isl_constraint *c);
+
+Again, the callback function C<fn> should return 0 if successful and
+-1 if an error occurs. In the latter case, or if any other error
+occurs, the above functions will return -1.
+
+The coefficients of the constraints can be inspected using
+the following functions.
+
+ void isl_constraint_get_constant(
+ __isl_keep isl_constraint *constraint, isl_int *v);
+ void isl_constraint_get_coefficient(
+ __isl_keep isl_constraint *constraint,
+ enum isl_dim_type type, int pos, isl_int *v);
+
+The explicit representations of the existentially quantified
+variables can be inspected using the following functions.
+Note that the user is only allowed to use these functions
+if the inspected set or map is the result of a call
+to C<isl_set_compute_divs> or C<isl_map_compute_divs>.
+
+ __isl_give isl_div *isl_constraint_div(
+ __isl_keep isl_constraint *constraint, int pos);
+ void isl_div_get_constant(__isl_keep isl_div *div,
+ isl_int *v);
+ void isl_div_get_denominator(__isl_keep isl_div *div,
+ isl_int *v);
+ void isl_div_get_coefficient(__isl_keep isl_div *div,
+ enum isl_dim_type type, int pos, isl_int *v);
+
=head2 Properties
=head3 Unary Properties
int isl_basic_set_is_universe(__isl_keep isl_basic_set *bset);
int isl_basic_map_is_universe(__isl_keep isl_basic_map *bmap);
+ int isl_set_fast_is_universe(__isl_keep isl_set *set);
=back
=over
+=item * Complement
+
+ __isl_give isl_set *isl_set_complement(
+ __isl_take isl_set *set);
+
=item * Projection
__isl_give isl_basic_set *isl_basic_set_project_out(
__isl_take isl_map *map, int *exact);
Compute the transitive closure of C<map>.
-The result may be an overapproximation. If the result is exact,
+The result may be an overapproximation. If the result is known to be exact,
then C<*exact> is set to C<1>.
The current implementation only produces exact results for particular
cases of piecewise translations (i.e., piecewise uniform dependences).
__isl_give isl_map *isl_map_lexmax(
__isl_take isl_map *map);
+=head2 Points
+
+Points are elements of a set. They can be used to construct
+simple sets (boxes) or they can be used to represent the
+individual elements of a set.
+The zero point (the origin) can be created using
+
+ __isl_give isl_point *isl_point_zero(__isl_take isl_dim *dim);
+
+The coordinates of a point can be inspected, set and changed
+using
+
+ void isl_point_get_coordinate(__isl_keep isl_point *pnt,
+ enum isl_dim_type type, int pos, isl_int *v);
+ __isl_give isl_point *isl_point_set_coordinate(
+ __isl_take isl_point *pnt,
+ enum isl_dim_type type, int pos, isl_int v);
+
+ __isl_give isl_point *isl_point_add_ui(
+ __isl_take isl_point *pnt,
+ enum isl_dim_type type, int pos, unsigned val);
+ __isl_give isl_point *isl_point_sub_ui(
+ __isl_take isl_point *pnt,
+ enum isl_dim_type type, int pos, unsigned val);
+
+Points can be copied or freed using
+
+ __isl_give isl_point *isl_point_copy(
+ __isl_keep isl_point *pnt);
+ void isl_point_free(__isl_take isl_point *pnt);
+
+A singleton set can be created from a point using
+
+ __isl_give isl_set *isl_set_from_point(
+ __isl_take isl_point *pnt);
+
+and a box can be created from two opposite extremal points using
+
+ __isl_give isl_set *isl_set_box_from_points(
+ __isl_take isl_point *pnt1,
+ __isl_take isl_point *pnt2);
+
+All elements of a B<bounded> set can be enumerated using
+the following function.
+
+ int isl_set_foreach_point(__isl_keep isl_set *set,
+ int (*fn)(__isl_take isl_point *pnt, void *user),
+ void *user);
+
+The function C<fn> is called for each integer point in
+C<set> with as second argument the last argument of
+the C<isl_set_foreach_point> call. The function C<fn>
+should return C<0> on success and C<-1> on failure.
+In the latter case, C<isl_set_foreach_point> will stop
+enumerating and return C<-1> as well.
+If the enumeration is performed successfully and to completion,
+then C<isl_set_foreach_point> returns C<0>.
+
+To obtain a single point of a set, use
+
+ __isl_give isl_point *isl_set_sample_point(
+ __isl_take isl_set *set);
+
+If C<set> does not contain any (integer) points, then the
+resulting point will be ``void'', a property that can be
+tested using
+
+ int isl_point_is_void(__isl_keep isl_point *pnt);
+
+=head2 Piecewise Quasipolynomials
+
+A piecewise quasipolynomial is a particular kind of function that maps
+a parametric point to a rational value.
+More specifically, a quasipolynomial is a polynomial expression in greatest
+integer parts of affine expressions of parameters and variables.
+A piecewise quasipolynomial is a subdivision of a given parametric
+domain into disjoint cells with a quasipolynomial associated to
+each cell. The value of the piecewise quasipolynomial at a given
+point is the value of the quasipolynomial associated to the cell
+that contains the point. Outside of the union of cells,
+the value is assumed to be zero.
+For example, the piecewise quasipolynomial
+
+ [n] -> { [x] -> ((1 + n) - x) : x <= n and x >= 0 }
+
+maps C<x> to C<1 + n - x> for values of C<x> between C<0> and C<n>.
+Piecewise quasipolynomials are mainly used by the C<barvinok>
+library for representing the number of elements in a parametric set or map.
+For example, the piecewise quasipolynomial above represents
+the number of point in the map
+
+ [n] -> { [x] -> [y] : x,y >= 0 and 0 <= x + y <= n }
+
+=head3 Printing (Piecewise) Quasipolynomials
+
+Quasipolynomials and piecewise quasipolynomials can be printed
+using the following functions.
+
+ void isl_qpolynomial_print(__isl_keep isl_qpolynomial *qp,
+ FILE *out, unsigned output_format);
+
+ void isl_pw_qpolynomial_print(
+ __isl_keep isl_pw_qpolynomial *pwqp, FILE *out,
+ unsigned output_format);
+
+=head3 Creating New (Piecewise) Quasipolynomials
+
+Some simple quasipolynomials can be created using the following functions.
+More complicated quasipolynomials can be created by applying
+operations such as addition and multiplication
+on the resulting quasipolynomials
+
+ __isl_give isl_qpolynomial *isl_qpolynomial_zero(
+ __isl_take isl_dim *dim);
+ __isl_give isl_qpolynomial *isl_qpolynomial_infty(
+ __isl_take isl_dim *dim);
+ __isl_give isl_qpolynomial *isl_qpolynomial_nan(
+ __isl_take isl_dim *dim);
+ __isl_give isl_qpolynomial *isl_qpolynomial_rat_cst(
+ __isl_take isl_dim *dim,
+ const isl_int n, const isl_int d);
+ __isl_give isl_qpolynomial *isl_qpolynomial_div(
+ __isl_take isl_div *div);
+ __isl_give isl_qpolynomial *isl_qpolynomial_var(
+ __isl_take isl_dim *dim,
+ enum isl_dim_type type, unsigned pos);
+
+The zero piecewise quasipolynomial or a piecewise quasipolynomial
+with a single cell can be created using the following functions.
+Multiple of these single cell piecewise quasipolynomials can
+be combined to create more complicated piecewise quasipolynomials.
+
+ __isl_give isl_pw_qpolynomial *isl_pw_qpolynomial_zero(
+ __isl_take isl_dim *dim);
+ __isl_give isl_pw_qpolynomial *isl_pw_qpolynomial_alloc(
+ __isl_take isl_set *set,
+ __isl_take isl_qpolynomial *qp);
+
+Quasipolynomials can be copied and freed again using the following
+functions.
+
+ __isl_give isl_qpolynomial *isl_qpolynomial_copy(
+ __isl_keep isl_qpolynomial *qp);
+ void isl_qpolynomial_free(__isl_take isl_qpolynomial *qp);
+
+ __isl_give isl_pw_qpolynomial *isl_pw_qpolynomial_copy(
+ __isl_keep isl_pw_qpolynomial *pwqp);
+ void isl_pw_qpolynomial_free(
+ __isl_take isl_pw_qpolynomial *pwqp);
+
+=head3 Inspecting (Piecewise) Quasipolynomials
+
+To iterate over the cells in a piecewise quasipolynomial,
+use the following function
+
+ int isl_pw_qpolynomial_foreach_piece(
+ __isl_keep isl_pw_qpolynomial *pwqp,
+ int (*fn)(__isl_take isl_set *set,
+ __isl_take isl_qpolynomial *qp,
+ void *user), void *user);
+
+As usual, the function C<fn> should return C<0> on success
+and C<-1> on failure.
+
+To iterate over all terms in a quasipolynomial,
+use
+
+ int isl_qpolynomial_foreach_term(
+ __isl_keep isl_qpolynomial *qp,
+ int (*fn)(__isl_take isl_term *term,
+ void *user), void *user);
+
+The terms themselves can be inspected and freed using
+these functions
+
+ unsigned isl_term_dim(__isl_keep isl_term *term,
+ enum isl_dim_type type);
+ void isl_term_get_num(__isl_keep isl_term *term,
+ isl_int *n);
+ void isl_term_get_den(__isl_keep isl_term *term,
+ isl_int *d);
+ int isl_term_get_exp(__isl_keep isl_term *term,
+ enum isl_dim_type type, unsigned pos);
+ __isl_give isl_div *isl_term_get_div(
+ __isl_keep isl_term *term, unsigned pos);
+ void isl_term_free(__isl_take isl_term *term);
+
+Each term is a product of parameters, set variables and
+integer divisions. The function C<isl_term_get_exp>
+returns the exponent of a given dimensions in the given term.
+The C<isl_int>s in the arguments of C<isl_term_get_num>
+and C<isl_term_get_den> need to have been initialized
+using C<isl_int_init> before calling these functions.
+
+=head3 Properties of (Piecewise) Quasipolynomials
+
+To check whether a quasipolynomial is actually a constant,
+use the following function.
+
+ int isl_qpolynomial_is_cst(__isl_keep isl_qpolynomial *qp,
+ isl_int *n, isl_int *d);
+
+If C<qp> is a constant and if C<n> and C<d> are not C<NULL>
+then the numerator and denominator of the constant
+are returned in C<*n> and C<*d>, respectively.
+
+=head3 Operations on (Piecewise) Quasipolynomials
+
+ __isl_give isl_qpolynomial *isl_qpolynomial_neg(
+ __isl_take isl_qpolynomial *qp);
+ __isl_give isl_qpolynomial *isl_qpolynomial_add(
+ __isl_take isl_qpolynomial *qp1,
+ __isl_take isl_qpolynomial *qp2);
+ __isl_give isl_qpolynomial *isl_qpolynomial_mul(
+ __isl_take isl_qpolynomial *qp1,
+ __isl_take isl_qpolynomial *qp2);
+
+ __isl_give isl_pw_qpolynomial *isl_pw_qpolynomial_add(
+ __isl_take isl_pw_qpolynomial *pwqp1,
+ __isl_take isl_pw_qpolynomial *pwqp2);
+ __isl_give isl_pw_qpolynomial *isl_pw_qpolynomial_sub(
+ __isl_take isl_pw_qpolynomial *pwqp1,
+ __isl_take isl_pw_qpolynomial *pwqp2);
+ __isl_give isl_pw_qpolynomial *isl_pw_qpolynomial_add_disjoint(
+ __isl_take isl_pw_qpolynomial *pwqp1,
+ __isl_take isl_pw_qpolynomial *pwqp2);
+ __isl_give isl_pw_qpolynomial *isl_pw_qpolynomial_neg(
+ __isl_take isl_pw_qpolynomial *pwqp);
+ __isl_give isl_pw_qpolynomial *isl_pw_qpolynomial_mul(
+ __isl_take isl_pw_qpolynomial *pwqp1,
+ __isl_take isl_pw_qpolynomial *pwqp2);
+
+ __isl_give isl_qpolynomial *isl_pw_qpolynomial_eval(
+ __isl_take isl_pw_qpolynomial *pwqp,
+ __isl_take isl_point *pnt);
+
=head2 Dependence Analysis
C<isl> contains specialized functionality for performing
Although C<isl> is mainly meant to be used as a library,
it also contains some basic applications that use some
of the functionality of C<isl>.
-The input may specified either in the L<isl format>
+The input may be specified in either the L<isl format>
or the L<PolyLib format>.
=head2 C<isl_polyhedron_sample>