FAQ: Frequently Asked Questions

Ask for help

How to access the documentation of the functions?

You have three supports:

Basic operations (arithmetic)

The vector arguments are not supported for \(\cos\), \(\exp\), \(\sin\), etc.

Example of error (using Python):

TypeError: cos(): incompatible function arguments. The following argument types are supported:
    1. (arg0: float) -> float
    2. (arg0: pyibex.pyibex.Interval) -> pyibex.pyibex.Interval
    3. (arg0: tubex::Tube) -> tubex::Tube
    4. (arg0: tubex::Trajectory) -> tubex::Trajectory

The computation of cos, sqrt, sqr, etc. are allowed only on scalar values. They are not available for vector objects such as IntervalVector, TrajectoryVector, TubeVector.

Domains (intervals, boxes, tubes)

How to concatenate two IntervalVectors?

Use the cart_prod() method:

a = IntervalVector([[0,1],[2,3]])
b = IntervalVector([[4,5],[6,7]])
c = cart_prod(a,b)
# c: ([0, 1] ; [2, 3] ; [4, 5] ; [6, 7])
IntervalVector a({{0,1},{2,3}});
IntervalVector b({{4,5},{6,7}});
IntervalVector c = cart_prod(a,b);
// c: ([0, 1] ; [2, 3] ; [4, 5] ; [6, 7])


I don’t have accurate results with my own \(\mathcal{C}_{\textrm{dist}}\) contractor

You may prefer to build your own \(\mathcal{C}_{\textrm{dist}}\) contractor from a Function object, instead of using the contractor already defined in the library. However, note that the following two distance equations are mathematically equivalent but will not lead to same outputs:

\[ \begin{align}\begin{aligned}\sqrt{(x_1-b_1)^2+(x_2-b_2)^2}=d\\\sqrt{(x_1-b_1)\cdot(x_1-b_1)+(x_2-b_2)\cdot(x_2-b_2)}=d\end{aligned}\end{align} \]

Indeed, with:

f_dist = Function("x[2]", "b[2]", "d",
                  "sqrt((x[0]-b[0])*(x[0]-b[0])+(x[1]-b[1])*(x[1]-b[1])) - d")
ctc_dist = CtcFunction(f_dist, Interval(0))
Function f_dist("x[2]", "b[2]", "d",
                "sqrt((x[0]-b[0])*(x[0]-b[0])+(x[1]-b[1])*(x[1]-b[1])) - d");
CtcFunction ctc_dist(f_dist, Interval(0));

You will obtain less efficient results than by defining:

f_dist = Function("x[2]", "b[2]", "d",
                  "sqrt((x[0]-b[0])^2+(x[1]-b[1])^2) - d")
ctc_dist = CtcFunction(f_dist, Interval(0))
Function f_dist("x[2]", "b[2]", "d",
                "sqrt((x[0]-b[0])^2+(x[1]-b[1])^2) - d");
CtcFunction ctc_dist(f_dist, Interval(0));

In both cases the contraction will be correct (no feasible solution will be lost), but the first one will be less accurate.

This is due to the dependency problem in interval analysis. For instance, the multiplication of two intervals \([a]\cdot[a]\) is less accurate than its equivalent \([a]^2\). Indeed, from the following example with values, we realize that \([-2,2]\cdot[-2,2]=[-4,4]\) whereas \([-2,2]^2=[0,4]\). For this reason, it is often important to use appropriate symbols when expressing a function, in order to avoid as much as possible this dependency effect.

How many times should a contractor be called?

A contractor is an operator that contracts (reduces) a domain (a box, for instance), according to some constraint. When it is used together with other contractors, there may be interactions between the contractors: a contraction from one contractor may activate another one. It becomes necessary to call all the contractors several times in order to converge to the best contraction of the domains.

This number of contracting iterations cannot be known in advance. It depends on the contractors at stake, their efficiency and their sequencing. One can implement a loop of contractions in order to process the contractors as long as their is a contraction on one of the domains. The iteration stops when a fixed point has been reached: when nothing can be contracted anymore.

Because a computer computes with floating point numbers, the fixed point will be reached in a finite number of steps. In practice, we may stop the iteration as soon as the contractions are not significant anymore. Anyway, even if the algorithm stops before reaching the fixed point, the actual solution will always be enclosed in the domains.

Since the new version of the library, the user does not have to implement his contracting loops and to manage fixed points. He can directly use Contractor Networks that will manage the propagation process automatically. This simplifies the use of contractors.

Contractor Networks (solving problems)

How to initialize the domains of a CN

If you do not have prior values for the domains (i.e. pre-defined sets), then the best is to set them as infinite domains (with infinite bounds). For intervals: \([-\infty,\infty]\).

If the problem is defined with a sufficient set of constraints, then the CN will solve the problem for us automatically.

I have an empty set result

If the CN contracts the domains to empty sets, then it has two reasons:

  • your domains are ill-defined, for instance the lower bound is higher than the upper bound: \([12,3]=\varnothing\).

  • the problem has no solution according to the constraints at stake: there exists no vector (or trajectory) that complies with all the related constraints.

I am confused about how to apply a static contractor to a tube

A static contractor does not depend on time and only involves static domains such as intervals and boxes. When one wants to apply a static contractor on a tube, the goal is to apply it for each time \(t\) in \([t_0,t_f]\).

Consider for instance a robot (the position of which is enclosed in \([\mathbf{x}](\cdot)\)) moving around a landmark represented by the box \([\mathbf{b}]\). The evolution of the distances between the robot and the landmark is enclosed in a tube \([y](\cdot)\).

Using the static \(\mathcal{C}_{\textrm{dist}}\) contractor for the distance constraint, we would naturally come to the following infinite sequence:

… continuously and for any time \(t\) in \([t_0,t_f]\).
Since \([\mathbf{b}]\) is not a tube, its value is repeated for each contractor.

A CN can manage the static constraint for any time in an efficient way. This can be implemented in one line only:

cn.add(ctc.dist, [x,b,y])
cn.add(ctc.dist, {x,b,y});

Assertion y.size() == z.size() failed

This means that the contractor requires the domains y and z to be of same dimension.

The error may be raised with the \(\mathcal{C}_{\textrm{eval}}\) contractor, when the tube to evaluate is not of the same dimension as the evaluation box or its derivative tube.