X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fuser.pod;h=69e962bf7f0f5a90866a27932af80fe43803ca52;hb=b9e709e0959c9edf7391b865281f20e48193b083;hp=b49d43dc75295a571152637fba6c64cae9829591;hpb=be01bd1cee8c2f95b846175a2dc6152e2d626f21;p=platform%2Fupstream%2Fisl.git

diff --git a/doc/user.pod b/doc/user.pod
index b49d43d..69e962b 100644
--- a/doc/user.pod
+++ b/doc/user.pod
@@ -205,6 +205,10 @@ after the last use.
 
 =item isl_int_set_si(r,i)
 
+=item isl_int_set_gmp(r,g)
+
+=item isl_int_get_gmp(i,g)
+
 =item isl_int_abs(r,i)
 
 =item isl_int_neg(r,i)
@@ -481,6 +485,26 @@ Conversely, the output of C<isl_dim_unwrap> is the dimension specification
 of a relation, while that of C<isl_dim_wrap> is the dimension specification
 of a set.
 
+Dimension specifications can be created from other dimension
+specifications using the following functions.
+
+	__isl_give isl_dim *isl_dim_domain(__isl_take isl_dim *dim);
+	__isl_give isl_dim *isl_dim_from_domain(__isl_take isl_dim *dim);
+	__isl_give isl_dim *isl_dim_range(__isl_take isl_dim *dim);
+	__isl_give isl_dim *isl_dim_from_range(__isl_take isl_dim *dim);
+	__isl_give isl_dim *isl_dim_reverse(__isl_take isl_dim *dim);
+	__isl_give isl_dim *isl_dim_join(__isl_take isl_dim *left,
+		__isl_take isl_dim *right);
+	__isl_give isl_dim *isl_dim_insert(__isl_take isl_dim *dim,
+		enum isl_dim_type type, unsigned pos, unsigned n);
+	__isl_give isl_dim *isl_dim_add(__isl_take isl_dim *dim,
+		enum isl_dim_type type, unsigned n);
+	__isl_give isl_dim *isl_dim_drop(__isl_take isl_dim *dim,
+		enum isl_dim_type type, unsigned first, unsigned n);
+
+Note that if dimensions are added or removed from a space, then
+the name and the internal structure are lost.
+
 =head2 Input and Output
 
 C<isl> supports its own input/output format, which is similar
@@ -526,6 +550,19 @@ 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 Extended C<PolyLib> format
+
+The extended C<PolyLib> format is nearly identical to the
+C<PolyLib> format.  The only difference is that the line
+containing the number of rows and columns of a constraint matrix
+also contains four additional numbers:
+the number of output dimensions, the number of input dimensions,
+the number of local dimensions (i.e., the number of existentially
+quantified variables) and the number of parameters.
+For sets, the number of ``output'' dimensions is equal
+to the number of set dimensions, while the number of ``input''
+dimensions is zero.
+
 =head3 Input
 
 	#include <isl_set.h>
@@ -581,8 +618,9 @@ The behavior of the printer can be modified in various ways
 	__isl_give isl_printer *isl_printer_set_suffix(
 		__isl_take isl_printer *p, const char *suffix);
 
-The C<output_format> may be either C<ISL_FORMAT_ISL>, C<ISL_FORMAT_OMEGA>
-or C<ISL_FORMAT_POLYLIB> and defaults to C<ISL_FORMAT_ISL>.
+The C<output_format> may be either C<ISL_FORMAT_ISL>, C<ISL_FORMAT_OMEGA>,
+C<ISL_FORMAT_POLYLIB>, C<ISL_FORMAT_EXT_POLYLIB> or C<ISL_FORMAT_LATEX>
+and defaults to C<ISL_FORMAT_ISL>.
 Each line in the output is indented by C<indent> spaces
 (default: 0), prefixed by C<prefix> and suffixed by C<suffix>.
 In the C<PolyLib> format output,
@@ -806,6 +844,29 @@ Or, alternatively,
 	bset = isl_basic_set_read_from_str(ctx,
 		"{[i] : exists (a : i = 2a and i >= 10 and i <= 42)}", -1);
 
+A basic set or relation can also be constructed from two matrices
+describing the equalities and the inequalities.
+
+	__isl_give isl_basic_set *isl_basic_set_from_constraint_matrices(
+		__isl_take isl_dim *dim,
+		__isl_take isl_mat *eq, __isl_take isl_mat *ineq,
+		enum isl_dim_type c1,
+		enum isl_dim_type c2, enum isl_dim_type c3,
+		enum isl_dim_type c4);
+	__isl_give isl_basic_map *isl_basic_map_from_constraint_matrices(
+		__isl_take isl_dim *dim,
+		__isl_take isl_mat *eq, __isl_take isl_mat *ineq,
+		enum isl_dim_type c1,
+		enum isl_dim_type c2, enum isl_dim_type c3,
+		enum isl_dim_type c4, enum isl_dim_type c5);
+
+The C<isl_dim_type> arguments indicate the order in which
+different kinds of variables appear in the input matrices
+and should be a permutation of C<isl_dim_cst>, C<isl_dim_param>,
+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.
+
 =head2 Inspecting Sets and Relations
 
 Usually, the user should not have to care about the actual constraints
@@ -840,6 +901,16 @@ either of the following functions.
 	__isl_give isl_map *isl_map_align_divs(
 		__isl_take isl_map *map);
 
+Alternatively, the existentially quantified variables can be removed
+using the following functions, which compute an overapproximation.
+
+	__isl_give isl_basic_set *isl_basic_set_remove_divs(
+		__isl_take isl_basic_set *bset);
+	__isl_give isl_basic_map *isl_basic_map_remove_divs(
+		__isl_take isl_basic_map *bmap);
+	__isl_give isl_set *isl_set_remove_divs(
+		__isl_take isl_set *set);
+
 To iterate over all the sets or maps in a union set or map, use
 
 	int isl_union_set_foreach_set(__isl_keep isl_union_set *uset,
@@ -849,6 +920,22 @@ To iterate over all the sets or maps in a union set or map, use
 		int (*fn)(__isl_take isl_map *map, void *user),
 		void *user);
 
+The number of sets or maps in a union set or map can be obtained
+from
+
+	int isl_union_set_n_set(__isl_keep isl_union_set *uset);
+	int isl_union_map_n_map(__isl_keep isl_union_map *umap);
+
+To extract the set or map from a union with a given dimension
+specification, use
+
+	__isl_give isl_set *isl_union_set_extract_set(
+		__isl_keep isl_union_set *uset,
+		__isl_take isl_dim *dim);
+	__isl_give isl_map *isl_union_map_extract_map(
+		__isl_keep isl_union_map *umap,
+		__isl_take isl_dim *dim);
+
 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,
@@ -872,6 +959,11 @@ the following functions first.
 	__isl_give isl_map *isl_map_make_disjoint(
 		__isl_take isl_map *map);
 
+The number of basic sets in a set can be obtained
+from
+
+	int isl_set_n_basic_set(__isl_keep isl_set *set);
+
 To iterate over the constraints of a basic set or map, use
 
 	#include <isl_constraint.h>
@@ -916,6 +1008,58 @@ to C<isl_set_compute_divs> or C<isl_map_compute_divs>.
 	void isl_div_get_coefficient(__isl_keep isl_div *div,
 		enum isl_dim_type type, int pos, isl_int *v);
 
+To obtain the constraints of a basic map in matrix
+form, use the following functions.
+
+	__isl_give isl_mat *isl_basic_map_equalities_matrix(
+			__isl_keep isl_basic_map *bmap,
+			enum isl_dim_type c1,
+			enum isl_dim_type c2, enum isl_dim_type c3,
+			enum isl_dim_type c4, enum isl_dim_type c5);
+	__isl_give isl_mat *isl_basic_map_inequalities_matrix(
+			__isl_keep isl_basic_map *bmap,
+			enum isl_dim_type c1,
+			enum isl_dim_type c2, enum isl_dim_type c3,
+			enum isl_dim_type c4, enum isl_dim_type c5);
+
+The C<isl_dim_type> arguments dictate the order in which
+different kinds of variables appear in the resulting matrix
+and should be a permutation of C<isl_dim_cst>, C<isl_dim_param>,
+C<isl_dim_in>, C<isl_dim_out> and C<isl_dim_div>.
+
+The names of the domain and range spaces of a set or relation can be
+read off using the following functions.
+
+	const char *isl_set_get_tuple_name(
+		__isl_keep isl_set *set);
+	const char *isl_basic_map_get_tuple_name(
+		__isl_keep isl_basic_map *bmap,
+		enum isl_dim_type type);
+	const char *isl_map_get_tuple_name(
+		__isl_keep isl_map *map,
+		enum isl_dim_type type);
+
+As with C<isl_dim_get_tuple_name>, the value returned points to
+an internal data structure.
+The names of individual dimensions can be read off using
+the following functions.
+
+	const char *isl_constraint_get_dim_name(
+		__isl_keep isl_constraint *constraint,
+		enum isl_dim_type type, unsigned pos);
+	const char *isl_set_get_dim_name(
+		__isl_keep isl_set *set,
+		enum isl_dim_type type, unsigned pos);
+	const char *isl_basic_map_get_dim_name(
+		__isl_keep isl_basic_map *bmap,
+		enum isl_dim_type type, unsigned pos);
+	const char *isl_map_get_dim_name(
+		__isl_keep isl_map *map,
+		enum isl_dim_type type, unsigned pos);
+
+These functions are mostly useful to obtain the names
+of the parameters.
+
 =head2 Properties
 
 =head3 Unary Properties
@@ -1061,6 +1205,29 @@ The followning functions check whether the domain of the given
 	__isl_give isl_union_set *isl_union_map_range(
 		__isl_take isl_union_map *umap);
 
+	__isl_give isl_basic_map *isl_basic_map_domain_map(
+		__isl_take isl_basic_map *bmap);
+	__isl_give isl_basic_map *isl_basic_map_range_map(
+		__isl_take isl_basic_map *bmap);
+	__isl_give isl_map *isl_map_domain_map(__isl_take isl_map *map);
+	__isl_give isl_map *isl_map_range_map(__isl_take isl_map *map);
+	__isl_give isl_union_map *isl_union_map_domain_map(
+		__isl_take isl_union_map *umap);
+	__isl_give isl_union_map *isl_union_map_range_map(
+		__isl_take isl_union_map *umap);
+
+The functions above construct a (basic, regular or union) relation
+that maps (a wrapped version of) the input relation to its domain or range.
+
+=item * Identity
+
+	__isl_give isl_map *isl_set_identity(
+		__isl_take isl_set *set);
+	__isl_give isl_union_map *isl_union_set_identity(
+		__isl_take isl_union_set *uset);
+
+Construct an identity relation on the given (union) set.
+
 =item * Deltas
 
 	__isl_give isl_basic_set *isl_basic_map_deltas(
@@ -1131,6 +1298,23 @@ of the constraints describing the basic sets or relations in the input.
 In case of union sets and relations, the affine hull is computed
 per space.
 
+=item * Polyhedral hull
+
+	__isl_give isl_basic_set *isl_set_polyhedral_hull(
+		__isl_take isl_set *set);
+	__isl_give isl_basic_map *isl_map_polyhedral_hull(
+		__isl_take isl_map *map);
+	__isl_give isl_union_set *isl_union_set_polyhedral_hull(
+		__isl_take isl_union_set *uset);
+	__isl_give isl_union_map *isl_union_map_polyhedral_hull(
+		__isl_take isl_union_map *umap);
+
+These functions compute a single basic set or relation
+not involving any existentially quantified variables
+that contains the whole input set or relation.
+In case of union sets and relations, the polyhedral hull is computed
+per space.
+
 =item * Power
 
 	__isl_give isl_map *isl_map_power(__isl_take isl_map *map,
@@ -1190,6 +1374,37 @@ the overapproximation), then you will get an error message.
 	__isl_give isl_union_map *isl_union_set_unwrap(
 		__isl_take isl_union_set *uset);
 
+=item * Flattening
+
+Remove any internal structure of domain (and range) of the given
+set or relation.  If there is any such internal structure in the input,
+then the name of the space is also removed.
+
+	__isl_give isl_set *isl_set_flatten(
+		__isl_take isl_set *set);
+	__isl_give isl_map *isl_map_flatten(
+		__isl_take isl_map *map);
+
+	__isl_give isl_map *isl_set_flatten_map(
+		__isl_take isl_set *set);
+
+The function above constructs a relation
+that maps the input set to a flattened version of the set.
+
+=item * Dimension manipulation
+
+	__isl_give isl_set *isl_set_add_dims(
+		__isl_take isl_set *set,
+		enum isl_dim_type type, unsigned n);
+	__isl_give isl_map *isl_map_add_dims(
+		__isl_take isl_map *map,
+		enum isl_dim_type type, unsigned n);
+
+It is usually not advisable to directly change the (input or output)
+space of a set or a relation as this removes the name and the internal
+structure of the space.  However, the above functions can be useful
+to add new parameters.
+
 =back
 
 =head2 Binary Operations
@@ -1234,6 +1449,9 @@ the same (number of) parameters.
 	__isl_give isl_union_map *isl_union_map_intersect_domain(
 		__isl_take isl_union_map *umap,
 		__isl_take isl_union_set *uset);
+	__isl_give isl_union_map *isl_union_map_intersect_range(
+		__isl_take isl_union_map *umap,
+		__isl_take isl_union_set *uset);
 	__isl_give isl_union_map *isl_union_map_intersect(
 		__isl_take isl_union_map *umap1,
 		__isl_take isl_union_map *umap2);
@@ -1294,6 +1512,9 @@ the same (number of) parameters.
 	__isl_give isl_map *isl_map_apply_domain(
 		__isl_take isl_map *map1,
 		__isl_take isl_map *map2);
+	__isl_give isl_union_map *isl_union_map_apply_domain(
+		__isl_take isl_union_map *umap1,
+		__isl_take isl_union_map *umap2);
 	__isl_give isl_map *isl_map_apply_range(
 		__isl_take isl_map *map1,
 		__isl_take isl_map *map2);
@@ -1423,6 +1644,42 @@ In case of union relations, the optimum is computed per space.
 	__isl_give isl_union_map *isl_union_map_lexmax(
 		__isl_take isl_union_map *umap);
 
+=head2 Matrices
+
+Matrices can be created, copied and freed using the following functions.
+
+	#include <isl_mat.h>
+	__isl_give isl_mat *isl_mat_alloc(struct isl_ctx *ctx,
+		unsigned n_row, unsigned n_col);
+	__isl_give isl_mat *isl_mat_copy(__isl_keep isl_mat *mat);
+	void isl_mat_free(__isl_take isl_mat *mat);
+
+Note that the elements of a newly created matrix may have arbitrary values.
+The elements can be changed and inspected using the following functions.
+
+	int isl_mat_rows(__isl_keep isl_mat *mat);
+	int isl_mat_cols(__isl_keep isl_mat *mat);
+	int isl_mat_get_element(__isl_keep isl_mat *mat,
+		int row, int col, isl_int *v);
+	__isl_give isl_mat *isl_mat_set_element(__isl_take isl_mat *mat,
+		int row, int col, isl_int v);
+
+C<isl_mat_get_element> will return a negative value if anything went wrong.
+In that case, the value of C<*v> is undefined.
+
+The following function can be used to compute the (right) inverse
+of a matrix, i.e., a matrix such that the product of the original
+and the inverse (in that order) is a multiple of the identity matrix.
+The input matrix is assumed to be of full row-rank.
+
+	__isl_give isl_mat *isl_mat_right_inverse(__isl_take isl_mat *mat);
+
+The following function can be used to compute the (right) kernel
+(or null space) of a matrix, i.e., a matrix such that the product of
+the original and the kernel (in that order) is the zero matrix.
+
+	__isl_give isl_mat *isl_mat_right_kernel(__isl_take isl_mat *mat);
+
 =head2 Points
 
 Points are elements of a set.  They can be used to construct
@@ -1484,8 +1741,10 @@ 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
+To obtain a single point of a (basic) set, use
 
+	__isl_give isl_point *isl_basic_set_sample_point(
+		__isl_take isl_basic_set *bset);
 	__isl_give isl_point *isl_set_sample_point(
 		__isl_take isl_set *set);
 
@@ -1543,6 +1802,18 @@ The output format of the printer
 needs to be set to either C<ISL_FORMAT_ISL> or C<ISL_FORMAT_C>.
 For C<isl_printer_print_union_pw_qpolynomial>, only C<ISL_FORMAT_ISL>
 is supported.
+In case of printing in C<ISL_FORMAT_C>, the user may want
+to set the names of all dimensions
+
+	__isl_give isl_qpolynomial *isl_qpolynomial_set_dim_name(
+		__isl_take isl_qpolynomial *qp,
+		enum isl_dim_type type, unsigned pos,
+		const char *s);
+	__isl_give isl_pw_qpolynomial *
+	isl_pw_qpolynomial_set_dim_name(
+		__isl_take isl_pw_qpolynomial *pwqp,
+		enum isl_dim_type type, unsigned pos,
+		const char *s);
 
 =head3 Creating New (Piecewise) Quasipolynomials
 
@@ -1553,6 +1824,8 @@ on the resulting quasipolynomials
 
 	__isl_give isl_qpolynomial *isl_qpolynomial_zero(
 		__isl_take isl_dim *dim);
+	__isl_give isl_qpolynomial *isl_qpolynomial_one(
+		__isl_take isl_dim *dim);
 	__isl_give isl_qpolynomial *isl_qpolynomial_infty(
 		__isl_take isl_dim *dim);
 	__isl_give isl_qpolynomial *isl_qpolynomial_neginfty(
@@ -1614,6 +1887,14 @@ piecewise quasipolynomial, use the following function
 		int (*fn)(__isl_take isl_pw_qpolynomial *pwqp, void *user),
 		void *user);
 
+To extract the piecewise quasipolynomial from a union with a given dimension
+specification, use
+
+	__isl_give isl_pw_qpolynomial *
+	isl_union_pw_qpolynomial_extract_pw_qpolynomial(
+		__isl_keep isl_union_pw_qpolynomial *upwqp,
+		__isl_take isl_dim *dim);
+
 To iterate over the cells in a piecewise quasipolynomial,
 use either of the following two functions
 
@@ -1755,9 +2036,20 @@ are returned in C<*n> and C<*d>, respectively.
 
 The gist operation applies the gist operation to each of
 the cells in the domain of the input piecewise quasipolynomial.
-In future, the operation will also exploit the context
+The context is also exploited
 to simplify the quasipolynomials associated to each cell.
 
+	__isl_give isl_pw_qpolynomial *isl_pw_qpolynomial_to_polynomial(
+		__isl_take isl_pw_qpolynomial *pwqp, int sign);
+	__isl_give isl_union_pw_qpolynomial *
+	isl_union_pw_qpolynomial_to_polynomial(
+		__isl_take isl_union_pw_qpolynomial *upwqp, int sign);
+
+Approximate each quasipolynomial by a polynomial.  If C<sign> is positive,
+the polynomial will be an overapproximation.  If C<sign> is negative,
+it will be an underapproximation.  If C<sign> is zero, the approximation
+will lie somewhere in between.
+
 =head2 Bounds on Piecewise Quasipolynomials and Piecewise Quasipolynomial Reductions
 
 A piecewise quasipolynomial reduction is a piecewise
@@ -1819,7 +2111,15 @@ output format of the printer
 needs to be set to either C<ISL_FORMAT_ISL> or C<ISL_FORMAT_C>.
 For C<isl_printer_print_union_pw_qpolynomial_fold>,
 output format of the printer
-needs to be set to either C<ISL_FORMAT_ISL>.
+needs to be set to C<ISL_FORMAT_ISL>.
+In case of printing in C<ISL_FORMAT_C>, the user may want
+to set the names of all dimensions
+
+	__isl_give isl_pw_qpolynomial_fold *
+	isl_pw_qpolynomial_fold_set_dim_name(
+		__isl_take isl_pw_qpolynomial_fold *pwf,
+		enum isl_dim_type type, unsigned pos,
+		const char *s);
 
 =head3 Inspecting (Piecewise) Quasipolynomial Reductions
 
@@ -1857,6 +2157,10 @@ To iterate over all quasipolynomials in a reduction, use
 
 =head3 Operations on Piecewise Quasipolynomial Reductions
 
+	__isl_give isl_pw_qpolynomial_fold *isl_pw_qpolynomial_fold_add(
+		__isl_take isl_pw_qpolynomial_fold *pwf1,
+		__isl_take isl_pw_qpolynomial_fold *pwf2);
+
 	__isl_give isl_pw_qpolynomial_fold *isl_pw_qpolynomial_fold_fold(
 		__isl_take isl_pw_qpolynomial_fold *pwf1,
 		__isl_take isl_pw_qpolynomial_fold *pwf2);
@@ -1939,6 +2243,8 @@ then value based dependence analysis is performed.
 
 	#include <isl_flow.h>
 
+	typedef int (*isl_access_level_before)(void *first, void *second);
+
 	__isl_give isl_access_info *isl_access_info_alloc(
 		__isl_take isl_map *sink,
 		void *sink_user, isl_access_level_before fn,
@@ -1947,6 +2253,7 @@ then value based dependence analysis is performed.
 		__isl_take isl_access_info *acc,
 		__isl_take isl_map *source, int must,
 		void *source_user);
+	void isl_access_info_free(__isl_take isl_access_info *acc);
 
 	__isl_give isl_flow *isl_access_info_compute_flow(
 		__isl_take isl_access_info *acc);
@@ -1988,6 +2295,9 @@ 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 C<isl_access_info_free> function should usually not be
+called explicitly, because it is called implicitly by
+C<isl_access_info_compute_flow>.
 
 The result of the dependence analysis is collected in an
 C<isl_flow>.  There may be elements in the domain of
@@ -2015,6 +2325,28 @@ source and if it is not followed by any I<may> sources.
 After finishing with an C<isl_flow>, the user should call
 C<isl_flow_free> to free all associated memory.
 
+A higher-level interface to dependence analysis is provided
+by the following function.
+
+	#include <isl_flow.h>
+
+	int isl_union_map_compute_flow(__isl_take isl_union_map *sink,
+		__isl_take isl_union_map *must_source,
+		__isl_take isl_union_map *may_source,
+		__isl_take isl_union_map *schedule,
+		__isl_give isl_union_map **must_dep,
+		__isl_give isl_union_map **may_dep,
+		__isl_give isl_union_set **must_no_source,
+		__isl_give isl_union_set **may_no_source);
+
+The arrays are identified by the tuple names of the ranges
+of the accesses.  The iteration domains by the tuple names
+of the domains of the accesses and of the schedule.
+The relative order of the iteration domains is given by the
+schedule.  Any of C<must_dep>, C<may_dep>, C<must_no_source>
+or C<may_no_source> may be C<NULL>, but a C<NULL> value for
+any of the other arguments is treated as an error.
+
 =head2 Parametric Vertex Enumeration
 
 The parametric vertex enumeration described in this section