add isl_set_gist_params

[platform/upstream/isl.git] / doc / user.pod

diff --git a/doc/user.pod b/doc/user.pod
index f382895..3c4402f 100644 (file)
--- a/doc/user.pod
+++ b/doc/user.pod
@@ -104,6 +104,23 @@ along with the associated functions.
 Some of the old names have been kept for backward compatibility,
 but they will be removed in the future.
 
 Some of the old names have been kept for backward compatibility,
 but they will be removed in the future.
 

+=item * Spaces of maps, sets and parameter domains are now
+treated differently.  The distinction between map spaces and set spaces
+has always been made on a conceptual level, but proper use of such spaces
+was never checked.  Furthermore, up until isl-0.07 there was no way
+of explicitly creating a parameter space.  These can now be created
+directly using C<isl_space_params_alloc> or from other spaces using
+C<isl_space_params>.
+
+=item * The space in which C<isl_aff>, C<isl_pw_aff>, C<isl_qpolynomial>,
+C<isl_pw_qpolynomial>, C<isl_qpolynomial_fold> and C<isl_pw_qpolynomial_fold>
+objects live is now a map space
+instead of a set space.  This means, for example, that the dimensions
+of the domain of an C<isl_aff> are now considered to be of type
+C<isl_dim_in> instead of C<isl_dim_set>.  Extra functions have been
+added to obtain the domain space.  Some of the constructors still
+take a domain space and have therefore been renamed.
+

 =back
 
 =head1 Installation
 =back
 
 =head1 Installation


@@ -466,6 +483,8 @@ the space in which it lives needs to be specified using an C<isl_space>.
        #include <isl/space.h>
        __isl_give isl_space *isl_space_alloc(isl_ctx *ctx,
                unsigned nparam, unsigned n_in, unsigned n_out);
        #include <isl/space.h>
        __isl_give isl_space *isl_space_alloc(isl_ctx *ctx,
                unsigned nparam, unsigned n_in, unsigned n_out);

+       __isl_give isl_space *isl_space_params_alloc(isl_ctx *ctx,
+               unsigned nparam);

        __isl_give isl_space *isl_space_set_alloc(isl_ctx *ctx,
                unsigned nparam, unsigned dim);
        __isl_give isl_space *isl_space_copy(__isl_keep isl_space *space);
        __isl_give isl_space *isl_space_set_alloc(isl_ctx *ctx,
                unsigned nparam, unsigned dim);
        __isl_give isl_space *isl_space_copy(__isl_keep isl_space *space);


@@ -473,9 +492,11 @@ the space in which it lives needs to be specified using an C<isl_space>.
        unsigned isl_space_dim(__isl_keep isl_space *space,
                enum isl_dim_type type);
 
        unsigned isl_space_dim(__isl_keep isl_space *space,
                enum isl_dim_type type);
 

-The space used for creating a set
+The space used for creating a parameter domain
+needs to be created using C<isl_space_params_alloc>.
+For other sets, the space

 needs to be created using C<isl_space_set_alloc>, while
 needs to be created using C<isl_space_set_alloc>, while

-that for creating a relation
+for a relation, the space

 needs to be created using C<isl_space_alloc>.
 C<isl_space_dim> can be used
 to find out the number of dimensions of each type in
 needs to be created using C<isl_space_alloc>.
 C<isl_space_dim> can be used
 to find out the number of dimensions of each type in


@@ -484,6 +505,13 @@ 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>.
 
 C<isl_dim_out> (only for relations), C<isl_dim_set>
 (only for sets) or C<isl_dim_all>.
 

+To check whether a given space is that of a set or a map
+or whether it is a parameter space, use these functions:
+
+       #include <isl/space.h>
+       int isl_space_is_params(__isl_keep isl_space *space);
+       int isl_space_is_set(__isl_keep isl_space *space);
+

 It is often useful to create objects that live in the
 same space as some other object.  This can be accomplished
 by creating the new objects
 It is often useful to create objects that live in the
 same space as some other object.  This can be accomplished
 by creating the new objects


@@ -514,20 +542,32 @@ of the original object.
                __isl_keep isl_constraint *constraint);
 
        #include <isl/polynomial.h>
                __isl_keep isl_constraint *constraint);
 
        #include <isl/polynomial.h>

+       __isl_give isl_space *isl_qpolynomial_get_domain_space(
+               __isl_keep isl_qpolynomial *qp);

        __isl_give isl_space *isl_qpolynomial_get_space(
                __isl_keep isl_qpolynomial *qp);
        __isl_give isl_space *isl_qpolynomial_fold_get_space(
                __isl_keep isl_qpolynomial_fold *fold);
        __isl_give isl_space *isl_qpolynomial_get_space(
                __isl_keep isl_qpolynomial *qp);
        __isl_give isl_space *isl_qpolynomial_fold_get_space(
                __isl_keep isl_qpolynomial_fold *fold);

+       __isl_give isl_space *isl_pw_qpolynomial_get_domain_space(
+               __isl_keep isl_pw_qpolynomial *pwqp);

        __isl_give isl_space *isl_pw_qpolynomial_get_space(
                __isl_keep isl_pw_qpolynomial *pwqp);
        __isl_give isl_space *isl_pw_qpolynomial_get_space(
                __isl_keep isl_pw_qpolynomial *pwqp);

+       __isl_give isl_space *isl_pw_qpolynomial_fold_get_domain_space(
+               __isl_keep isl_pw_qpolynomial_fold *pwf);
+       __isl_give isl_space *isl_pw_qpolynomial_fold_get_space(
+               __isl_keep isl_pw_qpolynomial_fold *pwf);

        __isl_give isl_space *isl_union_pw_qpolynomial_get_space(
                __isl_keep isl_union_pw_qpolynomial *upwqp);
        __isl_give isl_space *isl_union_pw_qpolynomial_fold_get_space(
                __isl_keep isl_union_pw_qpolynomial_fold *upwf);
 
        #include <isl/aff.h>
        __isl_give isl_space *isl_union_pw_qpolynomial_get_space(
                __isl_keep isl_union_pw_qpolynomial *upwqp);
        __isl_give isl_space *isl_union_pw_qpolynomial_fold_get_space(
                __isl_keep isl_union_pw_qpolynomial_fold *upwf);
 
        #include <isl/aff.h>

+       __isl_give isl_space *isl_aff_get_domain_space(
+               __isl_keep isl_aff *aff);

        __isl_give isl_space *isl_aff_get_space(
                __isl_keep isl_aff *aff);
        __isl_give isl_space *isl_aff_get_space(
                __isl_keep isl_aff *aff);

+       __isl_give isl_space *isl_pw_aff_get_domain_space(
+               __isl_keep isl_pw_aff *pwaff);

        __isl_give isl_space *isl_pw_aff_get_space(
                __isl_keep isl_pw_aff *pwaff);
 
        __isl_give isl_space *isl_pw_aff_get_space(
                __isl_keep isl_pw_aff *pwaff);
 


@@ -622,6 +662,8 @@ using the following functions.
        __isl_give isl_space *isl_space_from_domain(__isl_take isl_space *space);
        __isl_give isl_space *isl_space_range(__isl_take isl_space *space);
        __isl_give isl_space *isl_space_from_range(__isl_take isl_space *space);
        __isl_give isl_space *isl_space_from_domain(__isl_take isl_space *space);
        __isl_give isl_space *isl_space_range(__isl_take isl_space *space);
        __isl_give isl_space *isl_space_from_range(__isl_take isl_space *space);

+       __isl_give isl_space *isl_space_params(
+               __isl_take isl_space *space);

        __isl_give isl_space *isl_space_reverse(__isl_take isl_space *space);
        __isl_give isl_space *isl_space_join(__isl_take isl_space *left,
                __isl_take isl_space *right);
        __isl_give isl_space *isl_space_reverse(__isl_take isl_space *space);
        __isl_give isl_space *isl_space_join(__isl_take isl_space *left,
                __isl_take isl_space *right);


@@ -670,6 +712,7 @@ They can be inspected, copied and freed using the following functions.
        #include <isl/local_space.h>
        isl_ctx *isl_local_space_get_ctx(
                __isl_keep isl_local_space *ls);
        #include <isl/local_space.h>
        isl_ctx *isl_local_space_get_ctx(
                __isl_keep isl_local_space *ls);

+       int isl_local_space_is_set(__isl_keep isl_local_space *ls);

        int isl_local_space_dim(__isl_keep isl_local_space *ls,
                enum isl_dim_type type);
        const char *isl_local_space_get_dim_name(
        int isl_local_space_dim(__isl_keep isl_local_space *ls,
                enum isl_dim_type type);
        const char *isl_local_space_get_dim_name(


@@ -694,6 +737,8 @@ Two local spaces can be compared using
 Local spaces can be created from other local spaces
 using the following functions.
 
 Local spaces can be created from other local spaces
 using the following functions.
 

+       __isl_give isl_local_space *isl_local_space_domain(
+               __isl_take isl_local_space *ls);

        __isl_give isl_local_space *isl_local_space_from_domain(
                __isl_take isl_local_space *ls);
        __isl_give isl_local_space *isl_local_space_add_dims(
        __isl_give isl_local_space *isl_local_space_from_domain(
                __isl_take isl_local_space *ls);
        __isl_give isl_local_space *isl_local_space_add_dims(


@@ -1126,11 +1171,14 @@ C<isl_dim_set> and C<isl_dim_div> for sets and
 of C<isl_dim_cst>, C<isl_dim_param>,
 C<isl_dim_in>, C<isl_dim_out> and C<isl_dim_div> for relations.
 
 of C<isl_dim_cst>, C<isl_dim_param>,
 C<isl_dim_in>, C<isl_dim_out> and C<isl_dim_div> for relations.
 

-A (basic) relation can also be constructed from a (piecewise) affine expression
+A (basic) set or relation can also be constructed from a (piecewise)
+affine expression

 or a list of affine expressions (See L<"Piecewise Quasi Affine Expressions">).
 
        __isl_give isl_basic_map *isl_basic_map_from_aff(
                __isl_take isl_aff *aff);
 or a list of affine expressions (See L<"Piecewise Quasi Affine Expressions">).
 
        __isl_give isl_basic_map *isl_basic_map_from_aff(
                __isl_take isl_aff *aff);

+       __isl_give isl_set *isl_set_from_pw_aff(
+               __isl_take isl_pw_aff *pwaff);

        __isl_give isl_map *isl_map_from_pw_aff(
                __isl_take isl_pw_aff *pwaff);
        __isl_give isl_basic_map *isl_basic_map_from_aff_list(
        __isl_give isl_map *isl_map_from_pw_aff(
                __isl_take isl_pw_aff *pwaff);
        __isl_give isl_basic_map *isl_basic_map_from_aff_list(


@@ -1492,6 +1540,12 @@ is already known to be empty.
 Check if the relation obviously lies on a hyperplane where the given dimension
 has a fixed value and if so, return that value in C<*val>.
 
 Check if the relation obviously lies on a hyperplane where the given dimension
 has a fixed value and if so, return that value in C<*val>.
 

+=item * Space
+
+To check whether a set is a parameter domain, use this function:
+
+       int isl_set_is_params(__isl_keep isl_set *set);
+

 =item * Wrapping
 
 The following functions check whether the domain of the given
 =item * Wrapping
 
 The following functions check whether the domain of the given


@@ -1606,10 +1660,13 @@ i.e., whether both domain and range are nested relations.
                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);
                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_set_params(
+               __isl_take isl_basic_set *bset);

        __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_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_set_params(__isl_take isl_set *set);

        __isl_give isl_set *isl_map_domain(
                __isl_take isl_map *bmap);
        __isl_give isl_set *isl_map_range(
        __isl_give isl_set *isl_map_domain(
                __isl_take isl_map *bmap);
        __isl_give isl_set *isl_map_range(


@@ -1940,10 +1997,14 @@ then the name of the space is also removed.
                __isl_take isl_basic_set *bset);
        __isl_give isl_set *isl_set_flatten(
                __isl_take isl_set *set);
                __isl_take isl_basic_set *bset);
        __isl_give isl_set *isl_set_flatten(
                __isl_take isl_set *set);

+       __isl_give isl_basic_map *isl_basic_map_flatten_domain(
+               __isl_take isl_basic_map *bmap);

        __isl_give isl_basic_map *isl_basic_map_flatten_range(
                __isl_take isl_basic_map *bmap);
        __isl_give isl_map *isl_map_flatten_range(
                __isl_take isl_map *map);
        __isl_give isl_basic_map *isl_basic_map_flatten_range(
                __isl_take isl_basic_map *bmap);
        __isl_give isl_map *isl_map_flatten_range(
                __isl_take isl_map *map);

+       __isl_give isl_map *isl_map_flatten_domain(
+               __isl_take isl_map *map);

        __isl_give isl_basic_map *isl_basic_map_flatten(
                __isl_take isl_basic_map *bmap);
        __isl_give isl_map *isl_map_flatten(
        __isl_give isl_basic_map *isl_basic_map_flatten(
                __isl_take isl_basic_map *bmap);
        __isl_give isl_map *isl_map_flatten(


@@ -2149,9 +2210,15 @@ the same (number of) parameters.
        __isl_give isl_union_set *isl_union_set_product(
                __isl_take isl_union_set *uset1,
                __isl_take isl_union_set *uset2);
        __isl_give isl_union_set *isl_union_set_product(
                __isl_take isl_union_set *uset1,
                __isl_take isl_union_set *uset2);

+       __isl_give isl_basic_map *isl_basic_map_domain_product(
+               __isl_take isl_basic_map *bmap1,
+               __isl_take isl_basic_map *bmap2);

        __isl_give isl_basic_map *isl_basic_map_range_product(
                __isl_take isl_basic_map *bmap1,
                __isl_take isl_basic_map *bmap2);
        __isl_give isl_basic_map *isl_basic_map_range_product(
                __isl_take isl_basic_map *bmap1,
                __isl_take isl_basic_map *bmap2);

+       __isl_give isl_map *isl_map_domain_product(
+               __isl_take isl_map *map1,
+               __isl_take isl_map *map2);

        __isl_give isl_map *isl_map_range_product(
                __isl_take isl_map *map1,
                __isl_take isl_map *map2);
        __isl_give isl_map *isl_map_range_product(
                __isl_take isl_map *map1,
                __isl_take isl_map *map2);


@@ -2180,6 +2247,9 @@ instead.
        __isl_give isl_basic_map *isl_basic_map_flat_range_product(
                __isl_take isl_basic_map *bmap1,
                __isl_take isl_basic_map *bmap2);
        __isl_give isl_basic_map *isl_basic_map_flat_range_product(
                __isl_take isl_basic_map *bmap1,
                __isl_take isl_basic_map *bmap2);

+       __isl_give isl_map *isl_map_flat_domain_product(
+               __isl_take isl_map *map1,
+               __isl_take isl_map *map2);

        __isl_give isl_map *isl_map_flat_range_product(
                __isl_take isl_map *map1,
                __isl_take isl_map *map2);
        __isl_give isl_map *isl_map_flat_range_product(
                __isl_take isl_map *map1,
                __isl_take isl_map *map2);


@@ -2200,6 +2270,9 @@ instead.
                __isl_take isl_basic_set *context);
        __isl_give isl_set *isl_set_gist(__isl_take isl_set *set,
                __isl_take isl_set *context);
                __isl_take isl_basic_set *context);
        __isl_give isl_set *isl_set_gist(__isl_take isl_set *set,
                __isl_take isl_set *context);

+       __isl_give isl_set *isl_set_gist_params(
+               __isl_take isl_set *set,
+               __isl_take isl_set *context);

        __isl_give isl_union_set *isl_union_set_gist(
                __isl_take isl_union_set *uset,
                __isl_take isl_union_set *context);
        __isl_give isl_union_set *isl_union_set_gist(
                __isl_take isl_union_set *uset,
                __isl_take isl_union_set *context);


@@ -2208,6 +2281,9 @@ instead.
                __isl_take isl_basic_map *context);
        __isl_give isl_map *isl_map_gist(__isl_take isl_map *map,
                __isl_take isl_map *context);
                __isl_take isl_basic_map *context);
        __isl_give isl_map *isl_map_gist(__isl_take isl_map *map,
                __isl_take isl_map *context);

+       __isl_give isl_map *isl_map_gist_params(
+               __isl_take isl_map *map,
+               __isl_take isl_set *context);

        __isl_give isl_union_map *isl_union_map_gist(
                __isl_take isl_union_map *umap,
                __isl_take isl_union_map *context);
        __isl_give isl_union_map *isl_union_map_gist(
                __isl_take isl_union_map *umap,
                __isl_take isl_union_map *context);


@@ -2400,11 +2476,14 @@ the original and the kernel (in that order) is the zero matrix.
 
 =head2 Piecewise Quasi Affine Expressions
 
 
 =head2 Piecewise Quasi Affine Expressions
 

-The zero quasi affine expression can be created using
+The zero quasi affine expression on a given domain can be created using

 
 

-       __isl_give isl_aff *isl_aff_zero(
+       __isl_give isl_aff *isl_aff_zero_on_domain(

                __isl_take isl_local_space *ls);
 
                __isl_take isl_local_space *ls);
 

+Note that the space in which the resulting object lives is a map space
+with the given space as domain and a one-dimensional range.
+

 A quasi affine expression can also be initialized from an C<isl_div>:
 
        #include <isl/div.h>
 A quasi affine expression can also be initialized from an C<isl_div>:
 
        #include <isl/div.h>


@@ -2463,6 +2542,8 @@ The expression can be inspected using
        isl_ctx *isl_aff_get_ctx(__isl_keep isl_aff *aff);
        int isl_aff_dim(__isl_keep isl_aff *aff,
                enum isl_dim_type type);
        isl_ctx *isl_aff_get_ctx(__isl_keep isl_aff *aff);
        int isl_aff_dim(__isl_keep isl_aff *aff,
                enum isl_dim_type type);

+       __isl_give isl_local_space *isl_aff_get_domain_local_space(
+               __isl_keep isl_aff *aff);

        __isl_give isl_local_space *isl_aff_get_local_space(
                __isl_keep isl_aff *aff);
        const char *isl_aff_get_dim_name(__isl_keep isl_aff *aff,
        __isl_give isl_local_space *isl_aff_get_local_space(
                __isl_keep isl_aff *aff);
        const char *isl_aff_get_dim_name(__isl_keep isl_aff *aff,


@@ -2883,27 +2964,31 @@ More complicated quasipolynomials can be created by applying
 operations such as addition and multiplication
 on the resulting quasipolynomials
 
 operations such as addition and multiplication
 on the resulting quasipolynomials
 

-       __isl_give isl_qpolynomial *isl_qpolynomial_zero(
-               __isl_take isl_space *dim);
-       __isl_give isl_qpolynomial *isl_qpolynomial_one(
-               __isl_take isl_space *dim);
-       __isl_give isl_qpolynomial *isl_qpolynomial_infty(
-               __isl_take isl_space *dim);
-       __isl_give isl_qpolynomial *isl_qpolynomial_neginfty(
-               __isl_take isl_space *dim);
-       __isl_give isl_qpolynomial *isl_qpolynomial_nan(
-               __isl_take isl_space *dim);
-       __isl_give isl_qpolynomial *isl_qpolynomial_rat_cst(
-               __isl_take isl_space *dim,
+       __isl_give isl_qpolynomial *isl_qpolynomial_zero_on_domain(
+               __isl_take isl_space *domain);
+       __isl_give isl_qpolynomial *isl_qpolynomial_one_on_domain(
+               __isl_take isl_space *domain);
+       __isl_give isl_qpolynomial *isl_qpolynomial_infty_on_domain(
+               __isl_take isl_space *domain);
+       __isl_give isl_qpolynomial *isl_qpolynomial_neginfty_on_domain(
+               __isl_take isl_space *domain);
+       __isl_give isl_qpolynomial *isl_qpolynomial_nan_on_domain(
+               __isl_take isl_space *domain);
+       __isl_give isl_qpolynomial *isl_qpolynomial_rat_cst_on_domain(
+               __isl_take isl_space *domain,

                const isl_int n, const isl_int d);
        __isl_give isl_qpolynomial *isl_qpolynomial_div(
                __isl_take isl_div *div);
                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_space *dim,
+       __isl_give isl_qpolynomial *isl_qpolynomial_var_on_domain(
+               __isl_take isl_space *domain,

                enum isl_dim_type type, unsigned pos);
        __isl_give isl_qpolynomial *isl_qpolynomial_from_aff(
                __isl_take isl_aff *aff);
 
                enum isl_dim_type type, unsigned pos);
        __isl_give isl_qpolynomial *isl_qpolynomial_from_aff(
                __isl_take isl_aff *aff);
 

+Note that the space in which a quasipolynomial lives is a map space
+with a one-dimensional range.  The C<domain> argument in some of
+the functions above corresponds to the domain of this map space.
+

 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
 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


@@ -3099,6 +3184,11 @@ are returned in C<*n> and C<*d>, respectively.
                __isl_take isl_qpolynomial *qp,
                __isl_take isl_space *model);
 
                __isl_take isl_qpolynomial *qp,
                __isl_take isl_space *model);
 

+       __isl_give isl_qpolynomial *isl_qpolynomial_project_domain_on_params(
+               __isl_take isl_qpolynomial *qp);
+       __isl_give isl_pw_qpolynomial *isl_pw_qpolynomial_project_domain_on_params(
+               __isl_take isl_pw_qpolynomial *pwqp);
+

        __isl_give isl_union_pw_qpolynomial *isl_union_pw_qpolynomial_coalesce(
                __isl_take isl_union_pw_qpolynomial *upwqp);
 
        __isl_give isl_union_pw_qpolynomial *isl_union_pw_qpolynomial_coalesce(
                __isl_take isl_union_pw_qpolynomial *upwqp);
 


@@ -3266,6 +3356,9 @@ To iterate over all quasipolynomials in a reduction, use
                __isl_take isl_union_pw_qpolynomial_fold *upwf,
                __isl_take isl_union_set *uset);
 
                __isl_take isl_union_pw_qpolynomial_fold *upwf,
                __isl_take isl_union_set *uset);
 

+       __isl_give isl_pw_qpolynomial_fold *isl_pw_qpolynomial_fold_project_domain_on_params(
+               __isl_take isl_pw_qpolynomial_fold *pwf);
+

        __isl_give isl_pw_qpolynomial_fold *isl_pw_qpolynomial_fold_coalesce(
                __isl_take isl_pw_qpolynomial_fold *pwf);
 
        __isl_give isl_pw_qpolynomial_fold *isl_pw_qpolynomial_fold_coalesce(
                __isl_take isl_pw_qpolynomial_fold *pwf);