add isl_mat_insert_cols

[isl.git] / doc / user.pod

=head1 Introduction

C<isl> is a thread-safe C library for manipulating
sets and relations of integer points bounded by affine constraints.
The descriptions of the sets and relations may involve
both parameters and existentially quantified variables.
All computations are performed in exact integer arithmetic
using C<GMP>.
The C<isl> library offers functionality that is similar
to that offered by the C<Omega> and C<Omega+> libraries,
but the underlying algorithms are in most cases completely different.

The library is by no means complete and some fairly basic
functionality is still missing.
Still, even in its current form, the library has been successfully
used as a backend polyhedral library for the polyhedral
scanner C<CLooG> and as part of an equivalence checker of
static affine programs.

=head1 Installation

The source of C<isl> can be obtained either as a tarball
or from the git repository.  Both are available from
L<http://freshmeat.net/projects/isl/>.
The installation process depends on how you obtained
the source.

=head2 Installation from the git repository

=over

=item 1 Clone or update the repository

The first time the source is obtained, you need to clone
the repository.

        git clone git://repo.or.cz/isl.git

To obtain updates, you need to pull in the latest changes

        git pull

=item 2 Get submodule (optional)

C<isl> can optionally use the C<piplib> library and provides
this library as a submodule.  If you want to use it, then
after you have cloned C<isl>, you need to grab the submodules

        git submodule init
        git submodule update

To obtain updates, you only need

        git submodule update

Note that C<isl> currently does not use any C<piplib>
functionality by default.

=item 3 Generate C<configure>

        ./autogen.sh

=back

After performing the above steps, continue
with the L<Common installation instructions>.

=head2 Common installation instructions

=over

=item 1 Obtain C<GMP>

Building C<isl> requires C<GMP>, including its headers files.
Your distribution may not provide these header files by default
and you may need to install a package called C<gmp-devel> or something
similar.  Alternatively, C<GMP> can be built from
source, available from L<http://gmplib.org/>.

=item 2 Configure

C<isl> uses the standard C<autoconf> C<configure> script.
To run it, just type

        ./configure

optionally followed by some configure options.
A complete list of options can be obtained by running

        ./configure --help

Below we discuss some of the more common options.

C<isl> can optionally use C<piplib>, but no
C<piplib> functionality is currently used by default.
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>)
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>.

=over

=item C<--prefix>

Installation prefix for C<isl>

=item C<--with-gmp-prefix>

Installation prefix for C<GMP> (architecture-independent files).

=item C<--with-gmp-exec-prefix>

Installation prefix for C<GMP> (architecture-dependent files).

=item C<--with-piplib>

Which copy of C<piplib> to use, either C<no> (default), C<system> or C<build>.

=item C<--with-piplib-prefix>

Installation prefix for C<system> C<piplib> (architecture-independent files).

=item C<--with-piplib-exec-prefix>

Installation prefix for C<system> C<piplib> (architecture-dependent files).

=item C<--with-piplib-builddir>

Location where C<build> C<piplib> was built.

=back

=item 3 Compile

        make

=item 4 Install (optional)

        make install

=back

=head1 Library

=head2 Initialization

All manipulations of integer sets and relations occur within
the context of an C<isl_ctx>.
A given C<isl_ctx> can only be used within a single thread.
All arguments of a function are required to have been allocated
within the same context.
There are currently no functions available for moving an object
from one C<isl_ctx> to another C<isl_ctx>.  This means that
there is currently no way of safely moving an object from one
thread to another, unless the whole C<isl_ctx> is moved.

An C<isl_ctx> can be allocated using C<isl_ctx_alloc> and
freed using C<isl_ctx_free>.
All objects allocated within an C<isl_ctx> should be freed
before the C<isl_ctx> itself is freed.

        isl_ctx *isl_ctx_alloc();
        void isl_ctx_free(isl_ctx *ctx);

=head2 Integers

All operations on integers, mainly the coefficients
of the constraints describing the sets and relations,
are performed in exact integer arithmetic using C<GMP>.
However, to allow future versions of C<isl> to optionally
support fixed integer arithmetic, all calls to C<GMP>
are wrapped inside C<isl> specific macros.
The basic type is C<isl_int> and the following operations
are available on this type.
The meanings of these operations are essentially the same
as their C<GMP> C<mpz_> counterparts.
As always with C<GMP> types, C<isl_int>s need to be
initialized with C<isl_int_init> before they can be used
and they need to be released with C<isl_int_clear>
after the last use.

=over

=item isl_int_init(i)

=item isl_int_clear(i)

=item isl_int_set(r,i)

=item isl_int_set_si(r,i)

=item isl_int_abs(r,i)

=item isl_int_neg(r,i)

=item isl_int_swap(i,j)

=item isl_int_swap_or_set(i,j)

=item isl_int_add_ui(r,i,j)

=item isl_int_sub_ui(r,i,j)

=item isl_int_add(r,i,j)

=item isl_int_sub(r,i,j)

=item isl_int_mul(r,i,j)

=item isl_int_mul_ui(r,i,j)

=item isl_int_addmul(r,i,j)

=item isl_int_submul(r,i,j)

=item isl_int_gcd(r,i,j)

=item isl_int_lcm(r,i,j)

=item isl_int_divexact(r,i,j)

=item isl_int_cdiv_q(r,i,j)

=item isl_int_fdiv_q(r,i,j)

=item isl_int_fdiv_r(r,i,j)

=item isl_int_fdiv_q_ui(r,i,j)

=item isl_int_read(r,s)

=item isl_int_print(out,i,width)

=item isl_int_sgn(i)

=item isl_int_cmp(i,j)

=item isl_int_cmp_si(i,si)

=item isl_int_eq(i,j)

=item isl_int_ne(i,j)

=item isl_int_lt(i,j)

=item isl_int_le(i,j)

=item isl_int_gt(i,j)

=item isl_int_ge(i,j)

=item isl_int_abs_eq(i,j)

=item isl_int_abs_ne(i,j)

=item isl_int_abs_lt(i,j)

=item isl_int_abs_gt(i,j)

=item isl_int_abs_ge(i,j)

=item isl_int_is_zero(i)

=item isl_int_is_one(i)

=item isl_int_is_negone(i)

=item isl_int_is_pos(i)

=item isl_int_is_neg(i)

=item isl_int_is_nonpos(i)

=item isl_int_is_nonneg(i)

=item isl_int_is_divisible_by(i,j)

=back

=head2 Sets and Relations

C<isl> uses four types of objects for representing sets and relations,
C<isl_basic_set>, C<isl_basic_map>, C<isl_set> and C<isl_map>.
C<isl_basic_set> and C<isl_basic_map> represent sets and relations that
can be described as a conjunction of affine constraints, while
C<isl_set> and C<isl_map> represent unions of
C<isl_basic_set>s and C<isl_basic_map>s, respectively.
The difference between sets and relations (maps) is that sets have
one set of variables, while relations have two sets of variables,
input variables and output variables.

=head2 Memory Management

Since a high-level operation on sets and/or relations usually involves
several substeps and since the user is usually not interested in
the intermediate results, most functions that return a new object
will also release all the objects passed as arguments.
If the user still wants to use one or more of these arguments
after the function call, she should pass along a copy of the
object rather than the object itself.
The user is then responsible for make sure that the original
object gets used somewhere else or is explicitly freed.

The arguments and return values of all documents functions are
annotated to make clear which arguments are released and which
arguments are preserved.  In particular, the following annotations
are used

=over

=item C<__isl_give>

C<__isl_give> means that a new object is returned.
The user should make sure that the returned pointer is
used exactly once as a value for an C<__isl_take> argument.
In between, it can be used as a value for as many
C<__isl_keep> arguments as the user likes.
There is one exception, and that is the case where the
pointer returned is C<NULL>.  Is this case, the user
is free to use it as an C<__isl_take> argument or not.

=item C<__isl_take>

C<__isl_take> means that the object the argument points to
is taken over by the function and may no longer be used
by the user as an argument to any other function.
The pointer value must be one returned by a function
returning an C<__isl_give> pointer.
If the user passes in a C<NULL> value, then this will
be treated as an error in the sense that the function will
not perform its usual operation.  However, it will still
make sure that all the the other C<__isl_take> arguments
are released.

=item C<__isl_keep>

C<__isl_keep> means that the function will only use the object
temporarily.  After the function has finished, the user
can still use it as an argument to other functions.
A C<NULL> value will be treated in the same way as
a C<NULL> value for an C<__isl_take> argument.

=back

=head2 Dimension Specifications

Whenever a new set or relation is created from scratch,
its dimension needs to be specified using an C<isl_dim>.

        #include <isl_dim.h>
        __isl_give isl_dim *isl_dim_alloc(isl_ctx *ctx,
                unsigned nparam, unsigned n_in, unsigned n_out);
        __isl_give isl_dim *isl_dim_set_alloc(isl_ctx *ctx,
                unsigned nparam, unsigned dim);
        __isl_give isl_dim *isl_dim_copy(__isl_keep isl_dim *dim);
        void isl_dim_free(__isl_take isl_dim *dim);
        unsigned isl_dim_size(__isl_keep isl_dim *dim,
                enum isl_dim_type type);

The dimension specification used for creating a set
needs to be created using C<isl_dim_set_alloc>, while
that for creating a relation
needs to be created using C<isl_dim_alloc>.
C<isl_dim_size> can be used
to find out the number of dimensions of each type in
a dimension specification, where type may be
C<isl_dim_param>, C<isl_dim_in> (only for relations),
C<isl_dim_out> (only for relations), C<isl_dim_set>
(only for sets) or C<isl_dim_all>.

=head2 Input and Output

C<isl> supports its own input/output format, which is similar
to the C<Omega> format, but also supports the C<PolyLib> format
in some cases.

=head3 C<isl> format

The C<isl> format is similar to that of C<Omega>, but has a different
syntax for describing the parameters and allows for the definition
of an existentially quantified variable as the integer division
of an affine expression.
For example, the set of integers C<i> between C<0> and C<n>
such that C<i % 10 <= 6> can be described as

        [n] -> { [i] : exists (a = [i/10] : 0 <= i and i <= n and
                                i - 10 a <= 6) }

A set or relation can have several disjuncts, separated
by the keyword C<or>.  Each disjunct is either a conjunction
of constraints or a projection (C<exists>) of a conjunction
of constraints.  The constraints are separated by the keyword
C<and>.

=head3 C<PolyLib> format

If the represented set is a union, then the first line
contains a single number representing the number of disjuncts.
Otherwise, a line containing the number C<1> is optional.

Each disjunct is represented by a matrix of constraints.
The first line contains two numbers representing
the number of rows and columns,
where the number of rows is equal to the number of constraints
and the number of columns is equal to two plus the number of variables.
The following lines contain the actual rows of the constraint matrix.
In each row, the first column indicates whether the constraint
is an equality (C<0>) or inequality (C<1>).  The final column
corresponds to the constant term.

If the set is parametric, then the coefficients of the parameters
appear in the last columns before the constant column.
The coefficients of any existentially quantified variables appear
between those of the set variables and those of the parameters.

=head3 Input

        #include <isl_set.h>
        __isl_give isl_basic_set *isl_basic_set_read_from_file(
                isl_ctx *ctx, FILE *input, int nparam);
        __isl_give isl_basic_set *isl_basic_set_read_from_str(
                isl_ctx *ctx, const char *str, int nparam);
        __isl_give isl_set *isl_set_read_from_file(isl_ctx *ctx,
                FILE *input, int nparam);
        __isl_give isl_set *isl_set_read_from_str(isl_ctx *ctx,
                const char *str, int nparam);

        #include <isl_map.h>
        __isl_give isl_basic_map *isl_basic_map_read_from_file(
                isl_ctx *ctx, FILE *input, int nparam);
        __isl_give isl_basic_map *isl_basic_map_read_from_str(
                isl_ctx *ctx, const char *str, int nparam);
        __isl_give isl_map *isl_map_read_from_file(
                struct isl_ctx *ctx, FILE *input, int nparam);
        __isl_give isl_map *isl_map_read_from_str(isl_ctx *ctx,
                const char *str, int nparam);

The input format is autodetected and may be either the C<PolyLib> format
or the C<isl> format.
C<nparam> specifies how many of the final columns in
the C<PolyLib> format correspond to parameters.
If input is given in the C<isl> format, then the number
of parameters needs to be equal to C<nparam>.
If C<nparam> is negative, then any number of parameters
is accepted in the C<isl> format and zero parameters
are assumed in the C<PolyLib> format.

=head3 Output

        #include <isl_set.h>
        void isl_basic_set_print(__isl_keep isl_basic_set *bset,
                FILE *out, int indent,
                const char *prefix, const char *suffix,
                unsigned output_format);
        void isl_set_print(__isl_keep struct isl_set *set,
                FILE *out, int indent, unsigned output_format);

        #include <isl_map.h>
        void isl_basic_map_print(__isl_keep isl_basic_map *bmap,
                FILE *out, int indent,
                const char *prefix, const char *suffix,
                unsigned output_format);
        void isl_map_print(__isl_keep struct isl_map *map,
                FILE *out, int indent, unsigned output_format);

The C<output_format> may be either C<ISL_FORMAT_ISL>, C<ISL_FORMAT_OMEGA>
or C<ISL_FORMAT_POLYLIB>.
Each line in the output is indented by C<indent> spaces,
prefixed by C<prefix> and suffixed by C<suffix>.
In the C<PolyLib> format output,
the coefficients of the existentially quantified variables
appear between those of the set variables and those
of the parameters.

=head2 Creating New Sets and Relations

C<isl> has functions for creating some standard sets and relations.

=over

=item * Empty sets and relations

        __isl_give isl_basic_set *isl_basic_set_empty(
                __isl_take isl_dim *dim);
        __isl_give isl_basic_map *isl_basic_map_empty(
                __isl_take isl_dim *dim);
        __isl_give isl_set *isl_set_empty(
                __isl_take isl_dim *dim);
        __isl_give isl_map *isl_map_empty(
                __isl_take isl_dim *dim);

=item * Universe sets and relations

        __isl_give isl_basic_set *isl_basic_set_universe(
                __isl_take isl_dim *dim);
        __isl_give isl_basic_map *isl_basic_map_universe(
                __isl_take isl_dim *dim);
        __isl_give isl_set *isl_set_universe(
                __isl_take isl_dim *dim);
        __isl_give isl_map *isl_map_universe(
                __isl_take isl_dim *dim);

=item * Identity relations

        __isl_give isl_basic_map *isl_basic_map_identity(
                __isl_take isl_dim *set_dim);
        __isl_give isl_map *isl_map_identity(
                __isl_take isl_dim *set_dim);

These functions take a dimension specification for a B<set>
and return an identity relation between two such sets.

=item * Lexicographic order

        __isl_give isl_map *isl_map_lex_lt(
                __isl_take isl_dim *set_dim);
        __isl_give isl_map *isl_map_lex_le(
                __isl_take isl_dim *set_dim);
        __isl_give isl_map *isl_map_lex_gt(
                __isl_take isl_dim *set_dim);
        __isl_give isl_map *isl_map_lex_ge(
                __isl_take isl_dim *set_dim);

These functions take a dimension specification for a B<set>
and return relations that express that the elements in the domain
are lexicographically less
(C<isl_map_lex_lt>), less or equal (C<isl_map_lex_le>),
greater (C<isl_map_lex_gt>) or greater or equal (C<isl_map_lex_ge>)
than the elements in the range.

=back

A basic set or relation can be converted to a set or relation
using the following functions.

        __isl_give isl_set *isl_set_from_basic_set(
                __isl_take isl_basic_set *bset);
        __isl_give isl_map *isl_map_from_basic_map(
                __isl_take isl_basic_map *bmap);

Sets and relations can be copied and freed again using the following
functions.

        __isl_give isl_basic_set *isl_basic_set_copy(
                __isl_keep isl_basic_set *bset);
        __isl_give isl_set *isl_set_copy(__isl_keep isl_set *set);
        __isl_give isl_basic_map *isl_basic_map_copy(
                __isl_keep isl_basic_map *bmap);
        __isl_give isl_map *isl_map_copy(__isl_keep isl_map *map);
        void isl_basic_set_free(__isl_take isl_basic_set *bset);
        void isl_set_free(__isl_take isl_set *set);
        void isl_basic_map_free(__isl_take isl_basic_map *bmap);
        void isl_map_free(__isl_take isl_map *map);

Other sets and relations can be constructed by starting
from a universe set or relation, adding equality and/or
inequality constraints and then projecting out the
existentially quantified variables, if any.
Constraints can be constructed, manipulated and
added to basic sets and relations using the following functions.

        #include <isl_constraint.h>
        __isl_give isl_constraint *isl_equality_alloc(
                __isl_take isl_dim *dim);
        __isl_give isl_constraint *isl_inequality_alloc(
                __isl_take isl_dim *dim);
        void isl_constraint_set_constant(
                __isl_keep isl_constraint *constraint, isl_int v);
        void isl_constraint_set_coefficient(
                __isl_keep isl_constraint *constraint,
                enum isl_dim_type type, int pos, isl_int v);
        __isl_give isl_basic_map *isl_basic_map_add_constraint(
                __isl_take isl_basic_map *bmap,
                __isl_take isl_constraint *constraint);
        __isl_give isl_basic_set *isl_basic_set_add_constraint(
                __isl_take isl_basic_set *bset,
                __isl_take isl_constraint *constraint);

For example, to create a set containing the even integers
between 10 and 42, you would use the following code.

        isl_int v;
        struct isl_dim *dim;
        struct isl_constraint *c;
        struct isl_basic_set *bset;

        isl_int_init(v);
        dim = isl_dim_set_alloc(ctx, 0, 2);
        bset = isl_basic_set_universe(isl_dim_copy(dim));

        c = isl_equality_alloc(isl_dim_copy(dim));
        isl_int_set_si(v, -1);
        isl_constraint_set_coefficient(c, isl_dim_set, 0, v);
        isl_int_set_si(v, 2);
        isl_constraint_set_coefficient(c, isl_dim_set, 1, v);
        bset = isl_basic_set_add_constraint(bset, c);

        c = isl_inequality_alloc(isl_dim_copy(dim));
        isl_int_set_si(v, -10);
        isl_constraint_set_constant(c, v);
        isl_int_set_si(v, 1);
        isl_constraint_set_coefficient(c, isl_dim_set, 0, v);
        bset = isl_basic_set_add_constraint(bset, c);

        c = isl_inequality_alloc(dim);
        isl_int_set_si(v, 42);
        isl_constraint_set_constant(c, v);
        isl_int_set_si(v, -1);
        isl_constraint_set_coefficient(c, isl_dim_set, 0, v);
        bset = isl_basic_set_add_constraint(bset, c);

        bset = isl_basic_set_project_out(bset, isl_dim_set, 1, 1);

        isl_int_clear(v);

Or, alternatively,

        struct isl_basic_set *bset;
        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

=over

=item Emptiness

The following functions test whether the given set or relation
contains any integer points.  The ``fast'' variants do not perform
any computations, but simply check if the given set or relation
is already known to be empty.

        int isl_basic_set_fast_is_empty(__isl_keep isl_basic_set *bset);
        int isl_basic_set_is_empty(__isl_keep isl_basic_set *bset);
        int isl_set_is_empty(__isl_keep isl_set *set);
        int isl_basic_map_fast_is_empty(__isl_keep isl_basic_map *bmap);
        int isl_basic_map_is_empty(__isl_keep isl_basic_map *bmap);
        int isl_map_fast_is_empty(__isl_keep isl_map *map);
        int isl_map_is_empty(__isl_keep isl_map *map);

=item * Universality

        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

=head3 Binary Properties

=over

=item * Equality

        int isl_set_fast_is_equal(__isl_keep isl_set *set1,
                __isl_keep isl_set *set2);
        int isl_set_is_equal(__isl_keep isl_set *set1,
                __isl_keep isl_set *set2);
        int isl_map_is_equal(__isl_keep isl_map *map1,
                __isl_keep isl_map *map2);
        int isl_map_fast_is_equal(__isl_keep isl_map *map1,
                __isl_keep isl_map *map2);
        int isl_basic_map_is_equal(
                __isl_keep isl_basic_map *bmap1,
                __isl_keep isl_basic_map *bmap2);

=item * Disjointness

        int isl_set_fast_is_disjoint(__isl_keep isl_set *set1,
                __isl_keep isl_set *set2);

=item * Subset

        int isl_set_is_subset(__isl_keep isl_set *set1,
                __isl_keep isl_set *set2);
        int isl_set_is_strict_subset(
                __isl_keep isl_set *set1,
                __isl_keep isl_set *set2);
        int isl_basic_map_is_subset(
                __isl_keep isl_basic_map *bmap1,
                __isl_keep isl_basic_map *bmap2);
        int isl_basic_map_is_strict_subset(
                __isl_keep isl_basic_map *bmap1,
                __isl_keep isl_basic_map *bmap2);
        int isl_map_is_subset(
                __isl_keep isl_map *map1,
                __isl_keep isl_map *map2);
        int isl_map_is_strict_subset(
                __isl_keep isl_map *map1,
                __isl_keep isl_map *map2);

=back

=head2 Unary Operations

=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_basic_set *bset,
                enum isl_dim_type type, unsigned first, unsigned n);
        __isl_give isl_basic_map *isl_basic_map_project_out(
                __isl_take isl_basic_map *bmap,
                enum isl_dim_type type, unsigned first, unsigned n);
        __isl_give isl_set *isl_set_project_out(__isl_take isl_set *set,
                enum isl_dim_type type, unsigned first, unsigned n);
        __isl_give isl_map *isl_map_project_out(__isl_take isl_map *map,
                enum isl_dim_type type, unsigned first, unsigned n);
        __isl_give isl_basic_set *isl_basic_map_domain(
                __isl_take isl_basic_map *bmap);
        __isl_give isl_basic_set *isl_basic_map_range(
                __isl_take isl_basic_map *bmap);
        __isl_give isl_set *isl_map_domain(
                __isl_take isl_map *bmap);
        __isl_give isl_set *isl_map_range(
                __isl_take isl_map *map);

=item * Coalescing

Simplify the representation of a set or relation by trying
to combine pairs of basic sets or relations into a single
basic set or relation.

        __isl_give isl_set *isl_set_coalesce(__isl_take isl_set *set);
        __isl_give isl_map *isl_map_coalesce(__isl_take isl_map *map);

=item * Convex hull

        __isl_give isl_basic_set *isl_set_convex_hull(
                __isl_take isl_set *set);
        __isl_give isl_basic_map *isl_map_convex_hull(
                __isl_take isl_map *map);

If the input set or relation has any existentially quantified
variables, then the result of these operations is currently undefined.

=item * Affine hull

        __isl_give isl_basic_set *isl_basic_set_affine_hull(
                __isl_take isl_basic_set *bset);
        __isl_give isl_basic_set *isl_set_affine_hull(
                __isl_take isl_set *set);
        __isl_give isl_basic_map *isl_basic_map_affine_hull(
                __isl_take isl_basic_map *bmap);
        __isl_give isl_basic_map *isl_map_affine_hull(
                __isl_take isl_map *map);

=item * Power

        __isl_give isl_map *isl_map_power(__isl_take isl_map *map,
                unsigned param, int *exact);

Compute a parametric representation for all positive powers I<k> of C<map>.
The power I<k> is equated to the parameter at position C<param>.
The result may be an overapproximation.  If the result is 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).

=item * Transitive closure

        __isl_give isl_map *isl_map_transitive_closure(
                __isl_take isl_map *map, int *exact);

Compute the transitive closure of C<map>.
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).

=back

=head2 Binary Operations

The two arguments of a binary operation not only need to live
in the same C<isl_ctx>, they currently also need to have
the same (number of) parameters.

=head3 Basic Operations

=over

=item * Intersection

        __isl_give isl_basic_set *isl_basic_set_intersect(
                __isl_take isl_basic_set *bset1,
                __isl_take isl_basic_set *bset2);
        __isl_give isl_set *isl_set_intersect(
                __isl_take isl_set *set1,
                __isl_take isl_set *set2);
        __isl_give isl_basic_map *isl_basic_map_intersect_domain(
                __isl_take isl_basic_map *bmap,
                __isl_take isl_basic_set *bset);
        __isl_give isl_basic_map *isl_basic_map_intersect_range(
                __isl_take isl_basic_map *bmap,
                __isl_take isl_basic_set *bset);
        __isl_give isl_basic_map *isl_basic_map_intersect(
                __isl_take isl_basic_map *bmap1,
                __isl_take isl_basic_map *bmap2);
        __isl_give isl_map *isl_map_intersect_domain(
                __isl_take isl_map *map,
                __isl_take isl_set *set);
        __isl_give isl_map *isl_map_intersect_range(
                __isl_take isl_map *map,
                __isl_take isl_set *set);
        __isl_give isl_map *isl_map_intersect(
                __isl_take isl_map *map1,
                __isl_take isl_map *map2);

=item * Union

        __isl_give isl_set *isl_basic_set_union(
                __isl_take isl_basic_set *bset1,
                __isl_take isl_basic_set *bset2);
        __isl_give isl_map *isl_basic_map_union(
                __isl_take isl_basic_map *bmap1,
                __isl_take isl_basic_map *bmap2);
        __isl_give isl_set *isl_set_union(
                __isl_take isl_set *set1,
                __isl_take isl_set *set2);
        __isl_give isl_map *isl_map_union(
                __isl_take isl_map *map1,
                __isl_take isl_map *map2);

=item * Set difference

        __isl_give isl_set *isl_set_subtract(
                __isl_take isl_set *set1,
                __isl_take isl_set *set2);
        __isl_give isl_map *isl_map_subtract(
                __isl_take isl_map *map1,
                __isl_take isl_map *map2);

=item * Application

        __isl_give isl_basic_set *isl_basic_set_apply(
                __isl_take isl_basic_set *bset,
                __isl_take isl_basic_map *bmap);
        __isl_give isl_set *isl_set_apply(
                __isl_take isl_set *set,
                __isl_take isl_map *map);
        __isl_give isl_basic_map *isl_basic_map_apply_domain(
                __isl_take isl_basic_map *bmap1,
                __isl_take isl_basic_map *bmap2);
        __isl_give isl_basic_map *isl_basic_map_apply_range(
                __isl_take isl_basic_map *bmap1,
                __isl_take isl_basic_map *bmap2);
        __isl_give isl_map *isl_map_apply_domain(
                __isl_take isl_map *map1,
                __isl_take isl_map *map2);
        __isl_give isl_map *isl_map_apply_range(
                __isl_take isl_map *map1,
                __isl_take isl_map *map2);

=back

=head3 Lexicographic Optimization

Given a (basic) set C<set> (or C<bset>) and a zero-dimensional domain C<dom>,
the following functions
compute a set that contains the lexicographic minimum or maximum
of the elements in C<set> (or C<bset>) for those values of the parameters
that satisfy C<dom>.
If C<empty> is not C<NULL>, then C<*empty> is assigned a set
that contains the parameter values in C<dom> for which C<set> (or C<bset>)
has no elements.
In other words, the union of the parameter values
for which the result is non-empty and of C<*empty>
is equal to C<dom>.

        __isl_give isl_set *isl_basic_set_partial_lexmin(
                __isl_take isl_basic_set *bset,
                __isl_take isl_basic_set *dom,
                __isl_give isl_set **empty);
        __isl_give isl_set *isl_basic_set_partial_lexmax(
                __isl_take isl_basic_set *bset,
                __isl_take isl_basic_set *dom,
                __isl_give isl_set **empty);
        __isl_give isl_set *isl_set_partial_lexmin(
                __isl_take isl_set *set, __isl_take isl_set *dom,
                __isl_give isl_set **empty);
        __isl_give isl_set *isl_set_partial_lexmax(
                __isl_take isl_set *set, __isl_take isl_set *dom,
                __isl_give isl_set **empty);

Given a (basic) set C<set> (or C<bset>), the following functions simply
return a set containing the lexicographic minimum or maximum
of the elements in C<set> (or C<bset>).

        __isl_give isl_set *isl_basic_set_lexmin(
                __isl_take isl_basic_set *bset);
        __isl_give isl_set *isl_basic_set_lexmax(
                __isl_take isl_basic_set *bset);
        __isl_give isl_set *isl_set_lexmin(
                __isl_take isl_set *set);
        __isl_give isl_set *isl_set_lexmax(
                __isl_take isl_set *set);

Given a (basic) relation C<map> (or C<bmap>) and a domain C<dom>,
the following functions
compute a relation that maps each element of C<dom>
to the single lexicographic minimum or maximum
of the elements that are associated to that same
element in C<map> (or C<bmap>).
If C<empty> is not C<NULL>, then C<*empty> is assigned a set
that contains the elements in C<dom> that do not map
to any elements in C<map> (or C<bmap>).
In other words, the union of the domain of the result and of C<*empty>
is equal to C<dom>.

        __isl_give isl_map *isl_basic_map_partial_lexmax(
                __isl_take isl_basic_map *bmap,
                __isl_take isl_basic_set *dom,
                __isl_give isl_set **empty);
        __isl_give isl_map *isl_basic_map_partial_lexmin(
                __isl_take isl_basic_map *bmap,
                __isl_take isl_basic_set *dom,
                __isl_give isl_set **empty);
        __isl_give isl_map *isl_map_partial_lexmax(
                __isl_take isl_map *map, __isl_take isl_set *dom,
                __isl_give isl_set **empty);
        __isl_give isl_map *isl_map_partial_lexmin(
                __isl_take isl_map *map, __isl_take isl_set *dom,
                __isl_give isl_set **empty);

Given a (basic) map C<map> (or C<bmap>), the following functions simply
return a map mapping each element in the domain of
C<map> (or C<bmap>) to the lexicographic minimum or maximum
of all elements associated to that element.

        __isl_give isl_map *isl_basic_map_lexmin(
                __isl_take isl_basic_map *bmap);
        __isl_give isl_map *isl_basic_map_lexmax(
                __isl_take isl_basic_map *bmap);
        __isl_give isl_map *isl_map_lexmin(
                __isl_take isl_map *map);
        __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 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
array dataflow analysis.  That is, given a I<sink> access relation
and a collection of possible I<source> access relations,
C<isl> can compute relations that describe
for each iteration of the sink access, which iteration
of which of the source access relations was the last
to access the same data element before the given iteration
of the sink access.
To compute standard flow dependences, the sink should be
a read, while the sources should be writes.

        #include <isl_flow.h>

        __isl_give isl_access_info *isl_access_info_alloc(
                __isl_take isl_map *sink,
                void *sink_user, isl_access_level_before fn,
                int max_source);
        __isl_give isl_access_info *isl_access_info_add_source(
                __isl_take isl_access_info *acc,
                __isl_take isl_map *source, void *source_user);

        __isl_give isl_flow *isl_access_info_compute_flow(
                __isl_take isl_access_info *acc);

        int isl_flow_foreach(__isl_keep isl_flow *deps,
                int (*fn)(__isl_take isl_map *dep, void *dep_user,
                          void *user),
                void *user);
        __isl_give isl_set *isl_flow_get_no_source(
                __isl_keep isl_flow *deps);
        void isl_flow_free(__isl_take isl_flow *deps);

The function C<isl_access_info_compute_flow> performs the actual
dependence analysis.  The other functions are used to construct
the input for this function or to read off the output.

The input is collected in an C<isl_access_info>, which can
be created through a call to C<isl_access_info_alloc>.
The arguments to this functions are the sink access relation
C<sink>, a token C<sink_user> used to identify the sink
access to the user, a callback function for specifying the
relative order of source and sink accesses, and the number
of source access relations that will be added.
The callback function has type C<int (*)(void *first, void *second)>.
The function is called with two user supplied tokens identifying
either a source or the sink and it should return the shared nesting
level and the relative order of the two accesses.
In particular, let I<n> be the number of loops shared by
the two accesses.  If C<first> precedes C<second> textually,
then the function should return I<2 * n + 1>; otherwise,
it should return I<2 * n>.
The sources can be added to the C<isl_access_info> by performing
(at most) C<max_source> calls to C<isl_access_info_add_source>.
The C<source_user> token is again used to identify
the source access.  The range of the source access relation
C<source> should have the same dimension as the range
of the sink access relation.

The result of the dependence analysis is collected in an
C<isl_flow>.  There may be elements in the domain of
the sink access for which no preceding source access could be
find.  The set of these elements can be obtained through
a call to C<isl_flow_get_no_source>.
In the case of standard flow dependence analysis,
this set corresponds to the reads from uninitialized
array elements.
The actual flow dependences can be extracted using
C<isl_flow_foreach>.  This function will call the user-specified
callback function C<fn> for each B<non-empty> dependence between
a source and the sink.  The callback function is called
with three arguments, the actual flow dependence relation
mapping source iterations to sink iterations, a token
identifying the source and an additional C<void *> with value
equal to the third argument of the C<isl_flow_foreach> call.

After finishing with an C<isl_flow>, the user should call
C<isl_flow_free> to free all associated memory.

=head1 Applications

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 be specified in either the L<isl format>
or the L<PolyLib format>.

=head2 C<isl_polyhedron_sample>

C<isl_polyhedron_sample> takes a polyhedron as input and prints
an integer element of the polyhedron, if there is any.
The first column in the output is the denominator and is always
equal to 1.  If the polyhedron contains no integer points,
then a vector of length zero is printed.

=head2 C<isl_pip>

C<isl_pip> takes the same input as the C<example> program
from the C<piplib> distribution, i.e., a set of constraints
on the parameters, a line contains only -1 and finally a set
of constraints on a parametric polyhedron.
The coefficients of the parameters appear in the last columns
(but before the final constant column).
The output is the lexicographic minimum of the parametric polyhedron.
As C<isl> currently does not have its own output format, the output
is just a dump of the internal state.

=head2 C<isl_polyhedron_minimize>

C<isl_polyhedron_minimize> computes the minimum of some linear
or affine objective function over the integer points in a polyhedron.
If an affine objective function
is given, then the constant should appear in the last column.

=head2 C<isl_polytope_scan>

Given a polytope, C<isl_polytope_scan> prints
all integer points in the polytope.

=head1 C<isl-polylib>

The C<isl-polylib> library provides the following functions for converting
between C<isl> objects and C<PolyLib> objects.
The library is distributed separately for licensing reasons.

        #include <isl_set_polylib.h>
        __isl_give isl_basic_set *isl_basic_set_new_from_polylib(
                Polyhedron *P, __isl_take isl_dim *dim);
        Polyhedron *isl_basic_set_to_polylib(
                __isl_keep isl_basic_set *bset);
        __isl_give isl_set *isl_set_new_from_polylib(Polyhedron *D,
                __isl_take isl_dim *dim);
        Polyhedron *isl_set_to_polylib(__isl_keep isl_set *set);

        #include <isl_map_polylib.h>
        __isl_give isl_basic_map *isl_basic_map_new_from_polylib(
                Polyhedron *P, __isl_take isl_dim *dim);
        __isl_give isl_map *isl_map_new_from_polylib(Polyhedron *D,
                __isl_take isl_dim *dim);
        Polyhedron *isl_basic_map_to_polylib(
                __isl_keep isl_basic_map *bmap);
        Polyhedron *isl_map_to_polylib(__isl_keep isl_map *map);