The main features of the library are described in Section OCaml Interface Features. Section OCamldoc Documentation lists all the functions available to the default generated domains in the OCaml interface. Section Compilation and Installation explains how the OCaml interface is compiled and installed.
In the sequel, prefix
is the prefix under which you have installed the library (typically /usr
or /usr/local
).
The OCaml interface provides access to the numerical abstractions (convex polyhedra, BD shapes, octagonal shapes, etc.) implemented by the PPL library. A general introduction to the numerical abstractions, their representation in the PPL and the operations provided by the PPL is given in the main PPL user manual. Here we just describe those aspects that are specific to the OCaml interface.
First, here is a list of notes with general information and advice on the use of the OCaml interface.
prefix/lib/ppl
. Since this includes shared and dynamically loaded libraries, you must make your dynamic linker/loader aware of this fact. If you use a GNU/Linux system, try the commands man ld.so
and man ldconfig
for more information.ppl_new_C_Polyhedron_from_space_dimension, ppl_new_C_Polyhedron_from_C_Polyhedron, ppl_new_C_Polyhedron_from_constraints, ppl_new_C_Polyhedron_from_generators,
k
, the identifiers used for the PPL variables must lie between 0 and ppl_version_major/1, ppl_version_minor/1, ppl_version_revision/1, ppl_version_beta/1, ppl_version/1, ppl_banner.
Below is a short description of many of the interface functions. For full definitions of terminology used here, see the main PPL user manual.
First we describe some domain independent functions included with all instantiations of the OCaml interfaces.
ppl_version_major
Returns the major number of the PPL version.
ppl_version_minor
Returns the minor number of the PPL version.
ppl_version_revision
Returns the revision number of the PPL version.
ppl_version_beta
Returns the beta number of the PPL version.
ppl_version
Returns the PPL version.
ppl_banner
Returns information about the PPL version, the licensing, the lack of any warranty whatsoever, the C++ compiler used to build the library, where to report bugs and where to look for further information.
ppl_Coefficient_is_bounded
Returns true if and only if the Coefficients in the C++ interface are bounded.
ppl_Coefficient_max
Returns the maximum coefficient the C++ interface can handle.
ppl_Coefficient_min
Returns the minimum coefficient the C++ interface can handle.
ppl_max_space_dimension
Returns the maximum space dimension this library can handle.
ppl_set_timeout_exception_atom name
Sets the term to be thrown by timeout exceptions to name
. The default value is time_out
.
ppl_timeout_exception_atom
Returns the name to be thrown by timeout exceptions
ppl_set_timeout c_unsigned
Computations taking exponential time will be interrupted some time after c_unsigned
ms after that call. If the computation is interrupted that way, the current timeout exception atom will be thrown. c_unsigned
must be strictly greater than zero.
ppl_reset_timeout
Resets the timeout time so that the computation is not interrupted.
Here we describe some functions available for PPL objects defining mixed integer (linear) programming problems.
ppl_new_MIP_Problem_from_space_dimension dimension
Return a handle to an MIP Problem with the feasible region the vector space of dimension
dimension
, objective function and optimization mode
max
.
ppl_new_MIP_Problem constraint_system lin_expr optimization_mode
Return a handle to an MIP Problem with the feasible region represented by
constraint_system
, objective function lin_expr
and optimization mode optimization_mode
.
ppl_MIP_Problem_swap handle_1 handle_2
Swaps the MIP Problem referenced by handle_1
with the one referenced by handle_2
.
ppl_MIP_Problem_space_dimension handle
Returns the dimension of the vector space in which the MIP Problem referenced by handle
is embedded.
ppl_MIP_Problem_integer_space_dimensions handle
Returns a list of variables representing representing the integer space dimensions of the MIP Problem referenced by handle
.
ppl_MIP_Problem_constraints handle
Returns a list of the constraints in the constraints system representing the feasible region for the MIP Problem referenced by handle
.
ppl_MIP_Problem_objective_function handle
Returns the objective function for the MIP Problem referenced by handle
.
ppl_MIP_Problem_optimization_mode handle
Returns the optimization mode for the MIP Problem referenced by handle
.
ppl_MIP_Problem_clear handle
Resets the MIP problem referenced by handle
to be the trivial problem with the feasible region the -dimensional universe, objective function
and optimization mode
Maximization
.
ppl_MIP_Problem_add_space_dimensions_and_embed handle dimension
Embeds the MIP problem referenced by handle
in a space that is enlarged by dimension
dimensions,
ppl_MIP_Problem_add_to_integer_space_dimensions handle vars_list
Updates the MIP Problem referenced by handle
so that the variables in vars_list
are added to the set of integer space dimensions.
ppl_MIP_Problem_add_constraint handle constraint
Updates the MIP Problem referenced by handle
so that the feasible region is represented by the original constraint system together with the constraint constraint
.
ppl_MIP_Problem_add_constraints handle constraint_system
Updates the MIP Problem referenced by handle
so that the feasible region is represented by the original constraint system together with all the constraints in constraint_system
.
ppl_MIP_Problem_set_objective_function handle lin_expr
Updates the MIP Problem referenced by handle
so that the objective function is changed to lin_expr
.
ppl_MIP_Problem_set_optimization_mode handle optimization_mode
Updates the MIP Problem referenced by handle
so that the optimization mode is changed to optimization_mode
.
ppl_MIP_Problem_is_satisfiable handle
Returns true if the MIP Problem referenced by handle
is satisfiable and false otherwise.
ppl_MIP_Problem_solve handle
Solves the MIP problem referenced by handle
and returns 0, if the MIP problem is not satisfiable; 1, if the MIP problem is satisfiable but there is no finite bound to the value of the objective function; 2, if the MIP problem admits an optimal solution.
ppl_MIP_Problem_feasible_point handle
Returns a feasible point for the MIP problem referenced by handle
.
ppl_MIP_Problem_optimizing_point handle
Returns an optimizing point for the MIP problem referenced by handle
.
ppl_MIP_Problem_optimal_value handle
Returns a pair of numbers, the first being the numerator and the second the denominator, for the optimal value for the MIP problem referenced by handle
.
ppl_MIP_Problem_evaluate_objective_function handle generator
Evaluates the objective function of the MIP problem referenced by handle
at point generator
. Returns a pair of numbers, the first being the numerator and the second the denominator, for the objective function value for the MIP problem referenced by handle
.
ppl_MIP_Problem_OK handle
Returns true if the MIP Problem referenced by handle
is well formed, i.e., if it satisfies all its implementation invariants and false, otherwise. Useful for debugging purposes.
Here we describe the main functions available for PPL objects defining convex and closed polyhedra. A list of the available PPL functions for convex polyhedra for the OCaml interface is given in Section OCamldoc Documentation.
ppl_new_C_Polyhedron_from_space_dimension space_dimension universe_or_empty
Returns a handle to a C polyhedron with
space_dimension
dimensions; it is empty or the universe polyhedron depending on whether universe_or_empty
is empty
or universe
, respectively.
ppl_new_C_Polyhedron_from_C_Polyhedron handle
If handle
refers to a C polyhedron , then the expression will returns a handle to a copy
of
.
ppl_new_C_Polyhedron_from_NNC_Polyhedron handle
If handle
refers to an NNC polyhedron , then the expression returns a handle to a copy
of
.
When using ppl_new_C_Polyhedron_from_NNC_Polyhedron/2
, care must be taken that the source polyhedron referenced by handle
is topologically closed.
ppl_new_C_Polyhedron_from_constraints constraint_system
Returns a handle to a C polyhedron represented by
constraint_system
.
ppl_new_C_Polyhedron_from_generators generator_system
Returns a handle to a C polyhedron represented by
generator_system
.
ppl_Polyhedron_swap handle_1 handle_2
Swaps the polyhedron referenced by
handle_1
with the polyhedron referenced by
handle_2
. The polyhedra and
must have the same topology.
ppl_Polyhedron_space_dimension handle
Returns the dimension of the vector space in which the polyhedron referenced by handle
is embedded.
ppl_Polyhedron_affine_dimension handle
Returns the actual dimension of the polyhedron referenced by handle
.
ppl_Polyhedron_get_constraints handle
Return a list of the constraints in the constraints system representing the polyhedron referenced by handle
.
ppl_Polyhedron_get_minimized_constraints handle
Returns a minimized list of the constraints in the constraints system representing the polyhedron referenced by handle
.
ppl_Polyhedron_get_generators handle
Returns a list of the generators in the generators system representing the polyhedron referenced by handle
.
ppl_Polyhedron_get_minimized_generators handle
Returns a minimized list of the generators in the generators system representing the polyhedron referenced by handle
.
ppl_Polyhedron_relation_with_constraint handle constraint
Returns the list of relations the polyhedron referenced by handle
has with constraint
. The possible relations and their meaning is given in Section Relation-With Operators of the main PPL user manual.
ppl_Polyhedron_relation_with_generator handle generator
Returns the list of relations the polyhedron referenced by handle
has with generator
. The possible relations and their meaning is given in Section Relation-With Operators of the main PPL user manual.
ppl_Polyhedron_is_empty handle
Returns true if the polyhedron referenced by handle
is empty and false, otherwise.
ppl_Polyhedron_is_universe handle
Returns true if the polyhedron referenced by handle
is the universe and false, otherwise.
ppl_Polyhedron_is_bounded handle
Returns true if the polyhedron referenced by handle
is bounded and false, otherwise.
ppl_Polyhedron_contains_integer_point handle
Returns true if the polyhedron referenced by handle
contains at least one integer point and false, otherwise.
ppl_Polyhedron_bounds_from_above handle lin_expr
Returns true if the polyhedron referenced by handle
is bounded from above by lin_expr
and false, otherwise.
ppl_Polyhedron_bounds_from_below handle lin_expr
Returns true if the polyhedron referenced by handle
is bounded from below by lin_expr
and false, otherwise.
ppl_Polyhedron_maximize handle lin_expr
Returns a record bool_1 * coefficient_1 * coefficient_2 * bool_2
where: bool_1
is true if the polyhedron referenced by
handle
is not empty and lin_expr
is bounded from above in and false, otherwise.
coefficient_1
is the numerator of the supremum value and coefficient_2
the denominator of the supremum value. If the supremum is also the maximum, bool_2
is true and false, otherwise.
ppl_Polyhedron_maximize_with_point handle lin_expr
Returns a record bool_1 * coefficient_1 * coefficient_2 * bool_2 * Point
bool_1
is true if the polyhedron referenced by
handle
is not empty and lin_expr
is bounded from above in and false, otherwise.
coefficient_1
is the numerator of the supremum value and coefficient_2
the denominator of the supremum value. If the supremum is also the maximum, bool_2
is true and false, otherwise. Point
is the point or closure point where lin_expr
reaches the supremum.
ppl_Polyhedron_minimize handle lin_expr
Returns a record bool_1 * coefficient_1 * coefficient_2 * bool_2
bool_1
is true if the polyhedron referenced by
handle
is not empty and lin_expr
is bounded from below in and false, otherwise.
coefficient_1
is the numerator of the infinum value and coefficient_2
the denominator of the infinum value. If the infinum is also the minimum, bool_2
is true and false, otherwise.
ppl_Polyhedron_minimize_with_point handle lin_expr
Returns a record bool_1 * coefficient_1 * coefficient_2 * bool_2
bool_1
is true if the polyhedron referenced by
handle
is not empty and lin_expr
is bounded from below in and false, otherwise.
coefficient_1
is the numerator of the infinum value and coefficient_2
the denominator of the infinum value. If the infinum is also the minimum, bool_2
is true and false, otherwise. Point
is the point or closure point where lin_expr
reaches the infinum.
ppl_Polyhedron_is_topologically_closed handle
Returns true if the polyhedron referenced by handle
is topologically closed and false, otherwise.
ppl_Polyhedron_contains_Polyhedron handle_1 handle_2
Returns true if the polyhedron referenced by handle_2
is included in or equal to the polyhedron referenced by handle_1
and false, otherwise.
ppl_Polyhedron_strictly_contains_Polyhedron handle_1 handle_2
Returns true if the polyhedron referenced by handle_2
is included in but not equal to the polyhedron referenced by handle_1
and false, otherwise.
ppl_Polyhedron_is_disjoint_from_Polyhedron handle_1 handle_2
Returns true if the polyhedron referenced by handle_1
is disjoint from the polyhedron referenced by handle_2
and false, otherwise.
ppl_Polyhedron_equals_Polyhedron handle_1 handle_2
Returns true if the polyhedron referenced by handle_1
is equal to the polyhedron referenced by handle_2
and false, otherwise.
ppl_Polyhedron_OK handle
Returns true if the polyhedron referenced by handle
is well formed, i.e., if it satisfies all its implementation invariants and false, otherwise. Useful for debugging purposes.
ppl_Polyhedron_add_constraint handle constraint
Updates the polyhedron referenced by handle
to one obtained by adding constraint
to its constraint system.
ppl_Polyhedron_add_generator handle generator
Updates the polyhedron referenced by handle
to one obtained by adding generator
to its generator system.
ppl_Polyhedron_add_constraints handle constraint_system
Updates the polyhedron referenced by handle
to one obtained by adding to its constraint system the constraints in constraint_system
.
ppl_C_Polyhedron_add_generators handle generator_system
Updates the polyhedron referenced by handle
to one obtained by adding to its generator system the generators in generator_system
.
ppl_Polyhedron_intersection_assign handle_1 handle_2
Assigns to the polyhedron referenced by handle_1
its intersection with the polyhedron referenced by handle_2
.
ppl_Polyhedron_poly_hull_assign handle_1 handle_2
Assigns to the polyhedron referenced by handle_1
its poly-hull with the polyhedron referenced by handle_2
.
ppl_Polyhedron_poly_difference_assign handle_1 handle_2
Assigns to the polyhedron referenced by handle_1
its poly-difference with the polyhedron referenced by handle_2
.
ppl_Polyhedron_affine_image handle var lin_expr coefficient
Transforms the polyhedron referenced by handle
assigning the affine expression lin_expr
/coefficient
to var
.
ppl_Polyhedron_affine_preimage handle var lin_expr coefficient
This is the inverse transformation to that for ppl_affine_image
.
ppl_Polyhedron_bounded_affine_image handle var lin_expr_1 lin_expr_2 coefficient
Transforms the polyhedron referenced by handle
assigning the image with respect to the transfer relation lin_expr_1/coefficient <= var <= lin_expr_2/coefficient
.
ppl_Polyhedron_generalized_affine_image handle var Relation_Symbol lin_expr coefficient
Transforms the polyhedron referenced by handle
assigning the generalized affine image with respect to the transfer function var
Relation_Symbol
lin_expr
/coefficient
.
ppl_Polyhedron_generalized_affine_image_lhs_rhs handle lin_expr_1 Relation_Symbol lin_expr_2
Transforms the polyhedron referenced by handle
assigning the generalized affine image with respect to the transfer function lin_expr_1
Relation_Symbol
lin_expr_2
.
ppl_Polyhedron_time_elapse_assign handle_1 handle_2
Assigns to the polyhedron referenced by
handle_1
the time-elapse with the polyhedron
referenced by
handle_2
.
ppl_Polyhedron_BHRZ03_widening_assign handle_1 handle_2
If the polyhedron referenced by
handle_1
contains the polyhedron referenced by
handle_2
, then handle_1
will refer to the BHRZ03-widening of with
.
ppl_Polyhedron_BHRZ03_widening_assign_with_tokens handle_1 handle_2 c_unsigned_1
It is assumed that the polyhedron referenced by
handle_1
contains the polyhedron referenced by
handle_2
; let denote the BHRZ03-widening of
with
, Assuming that the quantity
given by
c_unsigned_1
is the number of tokens available, Then this function will return the number of tokens remaining at the end of the operation.
ppl_Polyhedron_limited_BHRZ03_extrapolation_assign handle_1 handle_2 constraint_system
If the polyhedron referenced by
handle_1
contains the polyhedron referenced by
handle_2
, then handle_1
will refer to the BHRZ03-extrapolation of with
improved by enforcing the constraints in
constraint_system
.
ppl_Polyhedron_limited_BHRZ03_extrapolation_assign_with_tokens handle_1 handle_2 constraint_system c_unsigned_1
It is assumed that the polyhedron referenced by
handle_1
contains the polyhedron referenced by
handle_2
; let denote the BHRZ03-extrapolation of
with
, improved by enforcing those constraints in
constraint_system
.
Assuming that the quantity given by
c_unsigned_1
is the number of tokens available, then this function will return the number of tokens remaining at the end of the operation.
ppl_Polyhedron_bounded_BHRZ03_extrapolation_assign handle_1 handle_2 constraint_system
If the polyhedron referenced by
handle_1
contains the polyhedron referenced by
handle_2
, then handle_1
will refer to the BHRZ03-extrapolation of with
improved by enforcing the constraints in
constraint_system
together with all constraints of the form and
that are satisfied by every point in
.
ppl_Polyhedron_bounded_BHRZ03_extrapolation_assign_with_tokens handle_1 handle_2 constraint_system c_unsigned_1
It is assumed that the polyhedron referenced by
handle_1
contains the polyhedron referenced by
handle_2
; let denote the BHRZ03-extrapolation of
with
improved by enforcing those constraints in
constraint_system
together with all constraints of the form and
that are satisfied by every point in
.
Assuming that the quantity given by
c_unsigned_1
is the number of tokens available, this function will return the number of tokens remaining at the end of the operation.
ppl_Polyhedron_H79_widening_assign handle_1 handle_2
If the polyhedron referenced by
handle_1
contains the polyhedron referenced by
handle_2
, then handle_1
will refer to the H79-widening of with
.
ppl_Polyhedron_H79_widening_assign_with_tokens handle_1 handle_2 c_unsigned_1
It is assumed that the polyhedron referenced by
handle_1
contains the polyhedron referenced by
handle_2
; let denote the H79-widening of
with
, Assuming that the quantity
given by
c_unsigned_1
is the number of tokens available, Then this function will return the number of tokens remaining at the end of the operation.
ppl_Polyhedron_limited_H79_extrapolation_assign handle_1 handle_2 constraint_system
If the polyhedron referenced by
handle_1
contains the polyhedron referenced by
handle_2
, then handle_1
will refer to the H79-extrapolation of with
improved by enforcing the constraints in
constraint_system
.
ppl_Polyhedron_limited_H79_extrapolation_assign_with_tokens handle_1 handle_2 constraint_system c_unsigned_1
It is assumed that the polyhedron referenced by
handle_1
contains the polyhedron referenced by
handle_2
; let denote the H79-extrapolation of
with
, improved by enforcing those constraints in
constraint_system
.
Assuming that the quantity given by
c_unsigned_1
is the number of tokens available, then this function will return the number of tokens remaining at the end of the operation.
ppl_Polyhedron_bounded_H79_extrapolation_assign handle_1 handle_2 constraint_system
If the polyhedron referenced by
handle_1
contains the polyhedron referenced by
handle_2
, then handle_1
will refer to the H79-extrapolation of with
improved by enforcing the constraints in
constraint_system
together with all constraints of the form and
that are satisfied by every point in
.
ppl_Polyhedron_bounded_H79_extrapolation_assign_with_tokens handle_1 handle_2 constraint_system c_unsigned_1
It is assumed that the polyhedron referenced by
handle_1
contains the polyhedron referenced by
handle_2
; let denote the H79-extrapolation of
with
, improved by enforcing those constraints in
constraint_system
together with all constraints of the form and
that are satisfied by every point in
.
Assuming that the quantity given by
c_unsigned_1
is the number of tokens available, this function will return the number of tokens remaining at the end of the operation.
ppl_Polyhedron_topological_closure_assign handle
Assigns to the polyhedron referenced by handle
its topological closure.
ppl_Polyhedron_add_space_dimensions_and_embed handle space_dimension
Embeds the polyhedron referenced by handle
in a space that is enlarged by space_dimension
dimensions,
ppl_Polyhedron_concatenate_assign handle_1 handle_2
Updates the polyhedron referenced by
handle_1
by first embedding in a new space enlarged by the space dimensions of the polyhedron
referenced by
handle_2
, and then adds to its system of constraints a renamed-apart version of the constraints of .
ppl_Polyhedron_add_space_dimensions_and_project handle space_dimension
Projects the polyhedron referenced by handle
onto a space that is enlarged by space_dimension
dimensions,
ppl_Polyhedron_remove_space_dimensions handle Int_List
Removes the space dimensions given by the identifiers of the PPL variables in list Int_List
from the polyhedron referenced by handle
. The identifiers for the remaining PPL variables are renumbered so that they are consecutive and the maximum index is less than the number of dimensions.
ppl_Polyhedron_remove_higher_space_dimensions handle space_dimension
Projects the polyhedron referenced to by handle
onto the first space_dimension
dimensions.
ppl_Polyhedron_expand_space_dimension handle var space_dimension
space_dimension
copies of the space dimension referenced by variable var
are added to the polyhedron referenced to by handle
.
ppl_Polyhedron_fold_space_dimensions handle list_of_vars var
The space dimensions referenced by the PPL variables in list list_of_vars
are folded into the dimension referenced by var
and removed. The result is undefined if list_of_vars
does not have the properties described in Section fold_space_dimensions Folding Multiple Dimensions of the Vector Space into One Dimension" of the main PPL user manual.
ppl_Polyhedron_map_space_dimensions handle p_func
Maps the space dimensions of the polyhedron referenced by handle
using the partial function defined by a list of pairs of integers p_func
. The result is undefined if p_func
does not encode a partial function with the properties described in Section Mapping_the_Dimensions_of_the_Vector_Space Mapping the Dimensions of the Vector Space" of the main PPL user manual.
When the Parma Polyhedra Library is configured, it tests for the existence of the OCaml system. If OCaml is correctly installed in a standard location, things are arranged so that the OCaml interface is built and installed.