.. _sec-manual-ctcfunction: ************************************************************** Generic CtcFunction: :math:`\mathbf{f}(\mathbf{x})=\mathbf{0}` ************************************************************** Lot of constraints can be expressed under the form :math:`\mathbf{f}(\mathbf{x})=\mathbf{0}` with :math:`\mathbf{f}` an analytic function possibly non-linear. The goal is to estimate the set of feasible vectors :math:`\mathbf{x}` of a domain :math:`[\mathbf{x}]` that satisfy this constraint. A dedicated contractor can be built from :math:`\mathbf{f}` in order to contract boxes. Note that the other form :math:`\mathbf{f}(\mathbf{x})\in[\mathbf{y}]` can also be treated by this contractor. .. contents:: Definition ---------- .. important:: .. math:: \mathbf{f}(\mathbf{x})=\mathbf{0} \longrightarrow \mathcal{C}_{\mathbf{f}}\big([\mathbf{x}]\big) \mathrm{~~~~or~~~~} \mathbf{f}(\mathbf{x})\in[\mathbf{y}] \longrightarrow \mathcal{C}_{\mathbf{f},[\mathbf{y}]}\big([\mathbf{x}]\big) .. tabs:: .. code-tab:: py # For the constraint f(x)=0 ctc_f = CtcFunction(Function("", "", ..., "")) ctc_f.contract(x) # For the constraint f(x)ϵ[y] y = Interval(...) # or IntervalVector if f is a vector function ctc_f = CtcFunction(Function("", "", ..., ""), y) ctc_f.contract(x) .. code-tab:: c++ // For the constraint f(x)=0 CtcFunction ctc_f(Function("", "", ..., "")); ctc_f.contract(x); // For the constraint f(x)ϵ[y] Interval y(...); // or IntervalVector if f is a vector function CtcFunction ctc_f(Function("", "", ..., ""), y); ctc_f.contract(x); .. note:: .. Figure:: ../../img/logo_ibex.jpg :align: right This contractor originates from the `IBEX library `_. It is briefly presented here for the sake of consistency. For more information, please refer to the `IBEX documentation `_ for C++. .. rubric:: Optimality This contractor is not necessarily optimal, depending on the expression of :math:`\mathbf{f}`. Example ------- The constraint: .. math:: x_1+x_2=x_3 is equivalent to: .. math:: f(\mathbf{x})=0 \mathrm{~~~with~~~} f(\mathbf{x})=x_1+x_2-x_3 We can then build the contractor with: .. tabs:: .. code-tab:: py ctc_f = CtcFunction(Function("x1", "x2", "x3", "x1+x2-x3")) .. code-tab:: c++ CtcFunction ctc_f(Function("x1", "x2", "x3", "x1+x2-x3")); Another example --------------- Let us consider the following non-linear function: .. math:: f(\mathbf{x}) = x_1\cos(x_1-x_2)\sin(x_1)+x_2 A contractor for the constraint :math:`f(\mathbf{x})=0` can be built by: .. tabs:: .. code-tab:: py ctc_f = CtcFunction(Function("x1", "x2", "x1*cos(x1-x2)*sin(x1)+x2")) .. code-tab:: c++ CtcFunction ctc_f(Function("x1", "x2", "x1*cos(x1-x2)*sin(x1)+x2")); | The first parameters are the variables names. The last one is the expression of :math:`f`. | Note that it is also possible to write vector variables: .. tabs:: .. code-tab:: py ctc_f = CtcFunction(Function("x[2]", "x[0]*cos(x[0]-x[1])*sin(x[0])+x[1]")) .. code-tab:: c++ CtcFunction ctc_f(Function("x[2]", "x[0]*cos(x[0]-x[1])*sin(x[0])+x[1]")); Then, a box :math:`[\mathbf{x}]` can be contracted by: .. tabs:: .. code-tab:: py x = IntervalVector([[-2,-1],[1,2.5]]) ctc_f.contract(x) .. code-tab:: c++ IntervalVector x({{-2.,-1.},{1.,2.5}}); ctc_f.contract(x); The boxes are contracted in order to remove some vectors that are not consistent with :math:`f(\mathbf{x})=0`. In the following figure, the exact solution for :math:`f(\mathbf{x})=0` is black painted. The initial boxes are depicted in blue, their contraction is represented in red. .. figure:: img/CtcFunction.png Illustration of several contracted boxes with the above ``ctc_f`` contractor. .. #include .. #include .. #include "ibex_CtcHC4.h" .. #include "ibex_SystemFactory.h" .. #include "ibex_Ctc3BCid.h" .. .. using namespace std; .. using namespace codac; .. using namespace ibex; .. .. int main() .. { .. SIVIAPaving p({{-3.,3.},{-3.,3.}}); .. p.compute(Function("x1", "x2", "x1*cos(x1-x2)*sin(x1)+x2"), {{0.}}, 0.01); .. CtcFunction ctc_f(Function("x1", "x2", "x1*cos(x1-x2)*sin(x1)+x2")); .. .. vibes::beginDrawing(); .. .. VIBesFigPaving fig_pav("test", &p); .. .. vector v_x; .. v_x.push_back({{-2.,-1.},{1.,2.5}}); .. v_x.push_back({{-1.7,-1.4},{-2.5,-0.8}}); .. v_x.push_back({{1.,2.},{-2.,2.}}); .. v_x.push_back({{-0.5,0.5},{-2.,2.}}); .. v_x.push_back({{-2.5,-1.},{0.,0.5}}); .. .. for(auto& x : v_x) .. { .. fig_pav.draw_box(x, "#006EA9"); .. ctc_f.contract(x); .. fig_pav.draw_box(x, "#D14F06[#E2E2E2]"); .. } .. .. map color_map; .. color_map[SetValue::MAYBE] = "black[black]"; .. color_map[SetValue::OUT] = "#ffffff00[#ffffff00]"; .. color_map[SetValue::IN] = "#ffffff00[#ffffff00]"; .. .. fig_pav.set_color_map(color_map); .. fig_pav.show(); .. .. vibes::endDrawing(); .. } Dealing with inequalities ------------------------- For constraints under the form :math:`\mathbf{f}(\mathbf{x})\in[\mathbf{y}]` (instead of :math:`\mathbf{f}(\mathbf{x})=\mathbf{0}` as in the previous section), one can specify :math:`[\mathbf{y}]` as last optional argument of ``CtcFunction``. A constraint :math:`\mathbf{f}(\mathbf{x})\leqslant 0` is equivalent to :math:`\mathbf{f}(\mathbf{x})\in[-\infty,0]` and so the related contractor becomes: .. tabs:: .. code-tab:: py ctc_f = CtcFunction(Function("x[2]", "x[0]*cos(x[0]-x[1])*sin(x[0])+x[1]"), Interval(-oo,0)) .. code-tab:: c++ CtcFunction ctc_f(Function("x[2]", "x[0]*cos(x[0]-x[1])*sin(x[0])+x[1]"), Interval(-oo,0)); |pic1| |pic2| .. |pic1| image:: img/CtcFunction_inequalities.png :width: 300 .. |pic2| image:: img/CtcFunction_inequalities_paving.png :width: 300 The above illustration reveals several contracted boxes with the new ``ctc_f`` contractor, in the case of inequalities. The actual solution set :math:`\mathbb{X}=\{\mathbf{x}\mid\mathbf{f}(\mathbf{x})\leqslant 0\}` is green painted. Going further ------------- This ``CtcFunction`` class is a generic shortcut to deal with :math:`\mathbf{f}(\mathbf{x})=\mathbf{0}` or :math:`\mathbf{f}(\mathbf{x})\in[\mathbf{y}]`. However, several algorithms exist to optimally deal with different classes of problems. A list of static contractors is provided in the IBEX library: `see more `_. The user is invited to use an appropriate tool to deal with the constraint at stake. The IBEX contractor behind ``CtcFunction`` is a ``CtcFwdBwd`` coupled with a ``Ctc3BCid``. .. admonition:: Technical documentation See the `C++ API documentation of this class <../../../api/html/classcodac_1_1_ctc_function.html>`_.