[ The ECLiPSe Libraries | Reference Manual | Alphabetic Index ]

# library(ic)

Hybrid integer/real interval arithmetic constraint solver

## Predicates

> ?Vars #:: ++Domain
>   Constrain Vars to be integral and have the domain Domain.
> #::(?Var, ++Domain, ?Bool)
>   Reflect into Bool the truth of Var having the domain Domain.
> ?ExprX #< ?ExprY
>   ExprX is less than ExprY (with integrality constraints).
> #<(?ExprX, ?ExprY, ?Bool)
>   Reified ExprX is less than ExprY (with integrality constraints).
> ?ExprX #= ?ExprY
>   ExprX is equal to ExprY (with integrality constraints).
> #=(?ExprX, ?ExprY, ?Bool)
>   Reified ExprX is equal to ExprY (with integrality constraints).
> ?ExprX #=< ?ExprY
>   ExprX is less than or equal to ExprY (with integrality constraints).
> #=<(?ExprX, ?ExprY, ?Bool)
>   Reified ExprX is less than or equal to ExprY (with integrality constraints).
> ?ExprX #> ?ExprY
>   ExprX is strictly greater than ExprY (with integrality constraints).
> #>(?ExprX, ?ExprY, ?Bool)
>   Reified ExprX is strictly greater than ExprY (with integrality constraints).
> ?ExprX #>= ?ExprY
>   ExprX is greater than or equal to ExprY (with integrality constraints).
> #>=(?ExprX, ?ExprY, ?Bool)
>   Reified ExprX is greater than or equal to ExprY (with integrality constraints).
> ?ExprX #\= ?ExprY
>   ExprX is not equal to ExprY (with integrality constraints).
> #\=(?ExprX, ?ExprY, ?Bool)
>   Reified ExprX is not equal to ExprY (with integrality constraints).
> ?Vars $:: ++Domain
>   Constrain Vars to have the domain Domain.
> $::(?Var, ++Domain, ?Bool)
>   Reflect into Bool the truth of Var having the domain Domain. Does not impose integrality.
> ?ExprX $< ?ExprY
>   ExprX is strictly less than ExprY.
> ?ExprX $= ?ExprY
>   ExprX is equal to ExprY.
> ?ExprX $=< ?ExprY
>   ExprX is less than or equal to ExprY.
> ?ExprX $> ?ExprY
>   ExprX is strictly greater than ExprY.
> ?ExprX $>= ?ExprY
>   ExprX is greater than or equal to ExprY.
> ?ExprX $\= ?ExprY
>   ExprX is not equal to ExprY.
> ?Vars :: ++Domain
>   Constrain Vars to have the domain Domain.
> ::(?Var, ++Domain, ?Bool)
>   Reflect into Bool the truth of Var having the domain Domain.
> ic:(?ExprX < ?ExprY)
>   ExprX is strictly less than ExprY.
> <(?ExprX, ?ExprY, ?Bool)
>   Reified ExprX is strictly less than ExprY.
> ic:(?ExprX =:= ?ExprY)
>   ExprX is equal to ExprY.
> =:=(?ExprX, ?ExprY, ?Bool)
>   Reified ExprX is equal to ExprY.
> ic:(?ExprX =< ?ExprY)
>   ExprX is less than or equal to ExprY.
> =<(?ExprX, ?ExprY, ?Bool)
>   Reified ExprX is less than or equal to ExprY.
> +ConX => +ConY
>   Constraint ConX being true implies ConY must both be true.
> =>(+ConX,+ConY,Bool)
>   Bool is the reified truth of constraint ConX implying the truth of ConY.
> ic:(?ExprX =\= ?ExprY)
>   ExprX is not equal to ExprY.
> =\=(?ExprX, ?ExprY, ?Bool)
>   Reified ExprX is not equal to ExprY.
> ic:(?ExprX > ?ExprY)
>   ExprX is strictly greater than ExprY.
> >(?ExprX, ?ExprY, ?Bool)
>   Reified ExprX is strictly greater than ExprY.
> ic:(?ExprX >= ?ExprY)
>   ExprX is greater than or equal to ExprY.
> >=(?ExprX, ?ExprY, ?Bool)
>   Reified ExprX is greater than or equal to ExprY.
> ac_eq(?X, ?Y, ++C)
>   Arc-consistent implementation of X #= Y + C.
> alldifferent(+Vars)
>   Constrains all elements of a list to be pairwise different.
> +ConX and +ConY
>   Constraints ConX and ConY must both be true.
> and(+ConX,+ConY,Bool)
>   Bool is the reified truth of both constraints ConX and ConY being true.
> delayed_goals_number(?Var, -Number)
>   Returns the number of goals delayed on the ic attribute of Var.
> delete(-X, +List, -R, ++Arg, ++Select)
>   Choose a domain variable from a list according to selection criteria.
> element(?Index, ++List, ?Value)
>   Value is the Index'th element of the integer list List.
> get_bounds(?Var, -Lo, -Hi)
>   Retrieve the current bounds of Var.
> get_delta(?Var, -Width)
>   Returns the width of the interval of Var.
> get_domain(?Var, ?Domain)
>   Returns a ground representation of the current IC domain of a variable.
> get_domain_as_list(?Var, ?DomainList)
>   List of all the elements in the IC domain of Var
> get_domain_size(?Var, ?Size)
>   Size is the number of integer elements in the IC domain for Var
> get_finite_integer_bounds(?Var, -Lo, -Hi)
>   Retrieve the current (finite, integral) bounds of Var.
> get_float_bounds(?Var, -Lo, -Hi)
>   Retrieve the current bounds of Var as floats.
> get_integer_bounds(?Var, -Lo, -Hi)
>   Retrieve the current bounds of (integral) Var.
> get_max(?Var, -Hi)
>   Retrieve the current upper bound of Var.
> get_median(?Var, -Median)
>   Returns the median of the interval of the IC variable Var.
> get_min(?Var, -Lo)
>   Retrieve the current lower bound of Var.
> get_solver_type(?Var, -Type)
>   Retrieve the type of a variable.
> get_threshold(-Threshold)
>   Returns the current propagation threshold.
> indomain(?Var)
>   Instantiates an integer IC variable to an element of its domain.
> indomain(?Var, ++Method)
>   a flexible way to assign values to finite domain variables
> integers(?Vars)
>   Vars' domain is the integer numbers.
> is_exact_solver_var(?Term)
>   Succeeds iff Term is an IC integer variable.
> is_in_domain(++Val, ?Var)
>   Succeeds iff Val is in the domain of Var
> is_in_domain(++Val, ?Var, ?Result)
>   Binds Result to indicate presence of Val in domain of Var
> is_solver_type(?Term)
>   Succeeds iff Term is an IC variable or a number.
> is_solver_var(?Term)
>   Succeeds iff Term is an IC variable.
> labeling(+Vars)
>   Instantiates all variables in a collection to elements of their domains.
> locate(+Vars, ++Precision)
>   Locate solution intervals for Vars by splitting and search.
> locate(+Vars, ++Precision, ++LinLog)
>   Locate solution intervals for Vars by splitting and search.
> locate(+LocateVars, +SquashVars, ++Precision, ++LinLog)
>   Locate solution intervals for LocateVars, interleaving search with squashing.
> max(+Vars, ?Max)
>   Constrains Max to be the largest element in Vars.
> maxlist(+Vars, ?Max)
>   Constrains Max to be the largest element in Vars.
> min(+Vars, ?Min)
>   Constrains Min to be the smallest element in Vars.
> minlist(+Vars, ?Min)
>   Constrains Min to be the smallest element in Vars.
> neg(+Con)
>   Constraints Con is negated.
> neg(+Con,Bool)
>   Bool is the logical negation of the reified truth constraints Con.
> nth_value(+Domain, ++N, -Value)
>   return the nth value in a domain
> +ConX or +ConY
>   At least one of the constraints ConX or ConY must be true.
> or(+ConX,+ConY,Bool)
>   Bool is the reified truth of at least one of the constraints ConX or ConY being true.
> piecewise_linear(?X, ++Points, ?Y)
>   Relates X and Y according to a piecewise linear function.
> print_solver_var(?Var, -Printed)
>   Returns a representation of the IC variable Var suitable for printing.
> reals(?Vars)
>   Vars' domain is the real numbers.
> search(+L, ++Arg, ++Select, +Choice, ++Method, +Option)
>   A generic search routine for finite domains or IC which implements different partial search methods (complete, credit, lds, bbs, dbs, sbds, gap_sbds, gap_sbdd)
> set_threshold(++Threshold)
>   Sets the propagation threshold.
> set_threshold(++Threshold, +WakeVars)
>   Sets the propagation threshold with recomputation.
> squash(+Vars, ++Precision, ++LinLog)
>   Refine the intervals of Vars by the squashing algorithm.

## Reexports

> reexport msg / 3 from ic_kernel
> reexport struct(ic(_, _, _, _, _, _, _, _)) from ic_kernel
> reexport ic_constraints
> reexport ic_search

## Description

The IC (Interval Constraint) library is a hybrid integer/real interval arithmetic constraint solver. Its aim is to make it convenient for programmers to write hybrid solutions to problems, mixing together integer and real constraints and variables.

The integer constraints and variables are similar to those available in the old finite domain library `fd'. The real constraints are similar to those that were available in the old real interval arithmetic library `ria'. Constraints which are not specifically integer constraints can be applied to either real or integer variables (or a mix) seamlessly, and any real variable can be converted to an integer variable at any time by imposing an integrality constraint on it.

The IC library replaces the `fd', `ria' and `range' libraries (with a new symbolic solver library providing the non-numeric functionality of `fd').

For more information, see the IC section of the constraint library manual or the documentation for the individual IC predicates.

The IC library solves constraint problems over the reals. It is not limited to linear constraints, so it can be used to solve general problems like:

       [eclipse 2]: ln(X) $>= sin(X).

       X = X{0.36787944117144228 .. 1.0Inf}
       yes.

The IC library handles linear and non-linear, reified constraints and user defined functions.

User-defined functions/constraints are treated in a similar manner to user defined functions found in expressions handled by is/2. Note, however, that user defined constraints/functions, when used in IC, should be (semi-)deterministic. User defined constraints/functions which leave choice points may not behave as expected.

Linear constraints are handled by a single propagator, whereas non-linear constraints are broken down into simpler ternary/binary/unary propagators. The value of any constraint found in an expression is its reified truth value (0..1).

Variables appearing in arithmetic IC constraints at compile-time are assumed to be IC variables unless they are wrapped in an eval/1 term. The eval/1 wrapper inside arithmetic constraints is used to indicate that a variable will be bound to an expression at run-time. This feature will only be used by programs which generate their constraints dynamically at run-time, for example.

       broken_sum(Xs,Sum):-
           (
    	   foreach(X,Xs),
    	   fromto(Expr,S1,S2,0)
           do
    	   S1 = X + S2
           ),
           Sum $= Expr.

The above implementation of a summation constraint will not work as intended because the variable `Expr` will be treated like an IC variable when it is in fact the term `+(X1,+(X2,+(...)))` which is constructed in the for-loop. In order to get the desired functionality, one must wrap the variable `Expr` in an eval/1.

       working_sum(Xs,Sum):-
           (
    	   foreach(X,Xs),
    	   fromto(Expr,S1,S2,0)
           do
    	   S1 = X + S2
           ),
           Sum $= eval(Expr).

The following arithmetic expression can be used inside the constraints:

X
  Variables. If X is not yet an interval variable, it is turned into one.
123
  Integer constants.
0.1
  Floating point constants. These are assumed to be exact and are converted to zero-width bounded reals.
0.1__0.2
  Bounded real constants.
pi, e
  Intervals enclosing the constants pi and e respectively.
inf
  Floating point infinity.
+Expr
  Identity.
-Expr
  Sign change.
+-Expr
  Expr or -Expr. The result is an interval enclosing both.
abs(Expr)
  The absolute value of Expr.
E1+E2
  Addition.
E1-E2
  Subtraction.
E1*E2
  Multiplication.
E1/E2
  Division.
E1^E2
  Exponentiation.
min(E1,E2)
  Minimum.
max(E1,E2)
  Maximum.
sqr(Expr)
  Square. Logically equivalent to Expr*Expr, but with better operational behaviour.
sqrt(Expr)
  Square root (always positive).
exp(Expr)
  Same as e^Expr.
ln(Expr)
  Natural logarithm, the reverse of the exp function.
sin(Expr)
  Sine.
cos(Expr)
  Cosine.
atan(Expr)
  Arcus tangens. (Returns value between -pi/2 and pi/2.)
rsqr(Expr)
  Reverse of the sqr function. The same as +-sqrt(Expr).
rpow(E1,E2)
  Reverse of exponentiation. i.e. finds X in E1 = X^E2.
sub(Expr)
  A subinterval of Expr.
sum(ExprList)
  Sum of a list of expressions.
min(ExprList)
  Minimum of a list of expressions.
max(ExprList)
  Maximum of a list of expressions.
and
  Reified constraint conjunction. e.g. X>3 and Y<8
or
  Reified constraint disjunction. e.g. X>3 or Y<8
=>
  Reified constraint implication. e.g. X>3 => Y<8
neg
  Reified constraint negation. e.g. neg X>3
$=, $\=, $>, $>=, $<, $=<, #=, #\=, #>, #>=, #<, #=<, =:=, =\=, >, >=, <, =<, and, or, =>, neg
  Constraints whose value is taken as their reified truth value (0..1).
foo(Arg1, Arg2 ... ArgN), module:foo(Arg1, Arg2 ... ArgN)
Call user-defined constraint/function foo.
eval(Var)
  Var will be an expression at run-time.

## About

- Author: Warwick Harvey, Andrew Sadler, Andrew Cheadle

Generated from ic.eci on Sat Nov 8 06:57:23 2008