Towards tube documentation and official V2 release

README.md

@@ -1,6 +1,6 @@
-# [Codac: constraint-programming for robotics](http://codac.io/v2) [![Build Status](https://github.com/codac-team/codac/workflows/.github/workflows/tests.yml/badge.svg)](https://github.com/codac-team/codac/actions)
+# [Codac: constraint-programming for robotics](http://codac.io) [![Build Status](https://github.com/codac-team/codac/workflows/.github/workflows/tests.yml/badge.svg)](https://github.com/codac-team/codac/actions)
 
-See the official website: http://codac.io/v2
+See the official website: http://codac.io
 
 Codac (Catalog Of Domains And Contractors) is a C++/Python/Matlab library providing tools for interval computations and constraint programming over real numbers, trajectories and sets.
 It has numerous applications in parameter estimation, guaranteed integration, robot localization, and provides reliable outputs.

doc/manual/_static/css/custom.css

@@ -179,16 +179,21 @@ a .download:before {
 }
 
 /* Adding VIBes + IPE logos in the lateral menu */
-.sidebar-tree li.toctree-l1 > a.reference.internal:has(+ input#toctree-checkbox-8) {
+.sidebar-tree li.toctree-l1 > a.reference.internal:has(+ input#toctree-checkbox-9) {
   background:url("../logos/logos_vibes_ipe.png") no-repeat center / contain;
 }
 
-.sidebar-tree li.toctree-l1 > a.reference.internal:has(+ input#toctree-checkbox-8):hover {
+.sidebar-tree li.toctree-l1 > a.reference.internal:has(+ input#toctree-checkbox-9):hover {
   background: url("../logos/logos_vibes_ipe.png") no-repeat center / contain,
               var(--color-sidebar-item-background--hover);
 }
 
-.sidebar-tree li.toctree-l1 > a.reference.internal.current:has(+ input#toctree-checkbox-8) {
+.sidebar-tree li.toctree-l1 > a.reference.internal.current:has(+ input#toctree-checkbox-9) {
   background: url("../logos/logos_vibes_ipe.png") no-repeat center / contain,
               var(--color-sidebar-item-background--current);
+}
+
+figcaption .caption-text
+{
+  font-style: italic;
 }

doc/manual/conf.py.in

@@ -89,7 +89,7 @@ html_theme_options = {
         "color-toc-item-text--active": "#FFFFFF",
     },
 
-    "announcement": "You are currently reading the new Codac documentation, which is currently in preparation. <a href=\"http://codac.io\">See the v1 website</a>.",
+    #"announcement": "You are currently reading the new Codac documentation, which is currently in preparation. <a href=\"http://codac.io\">See the v1 website</a>.",
 }
 
 # See https://www.sympy.org/sphinx-math-dollar/

doc/manual/index.rst

@@ -213,10 +213,9 @@ User manual
       * The class SetMembershipFunction
       * Extension to custom expressions
 
-* Tubes
-   * What is a tube?
-   * Temporal domains
-   * The Tube classes
+* :ref:`sec-domains-tubes`
+   * :ref:`sec-domains-tubes-tdomain`
+   * :ref:`sec-domains-tubes-slicedtube`
    * The Trajectory classes
    * Increasing performances using views
 
@@ -401,6 +400,7 @@ Development
    manual/introduction/index.rst
    manual/installation/index.rst
    manual/intervals/index.rst
+   manual/tubes/index.rst
    manual/linear/index.rst
    manual/functions/index.rst
    manual/contractors/index.rst

doc/manual/manual/functions/analytic/analytic_operators.rst

@@ -321,6 +321,8 @@ Expressions involving a non-supported centered-form operation
 If an operator, for which the centered form is not defined, is involved in an expression, then this expression cannot be evaluated using the centered form (calculation is disabled for the entire operation). A simple natural evaluation will then be computed.
 
 
+.. _sec-functions-temporal-operator:
+
 Expressions involving a temporal operator
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -330,7 +332,7 @@ Temporal operations for involving trajectories or tubes in analytic expressions
 
   .. code-tab:: py
 
-    x = # some sampled trajectory...
+    x = # some tube or sampled trajectory...
     g = x.as_function() # intermediate operation
 
     t = ScalarVar()
@@ -340,7 +342,7 @@ Temporal operations for involving trajectories or tubes in analytic expressions
 
   .. code-tab:: c++
 
-    x = // some sampled trajectory...
+    x = // some tube or sampled trajectory...
     g = x.as_function(); // intermediate operation
 
     ScalarVar t;

doc/manual/manual/installation/cpp.rst

@@ -190,7 +190,7 @@ Optionally, for Python binding (*e.g.* ``choco install python --version=3.10.4``
 
 .. code-block:: bash
 
-  choco install doxygen.install --version=1.13
+  choco install doxygen.install --version=1.16
   choco install graphviz
   python -m pip install --upgrade pip
   pip install --upgrade wheel setuptools sphinx sphinx_rtd_theme furo sphinx-math-dollar sphinx_tabs breathe sphinx_togglebutton

doc/manual/manual/installation/matlab.rst

@@ -13,8 +13,7 @@ Since 2019, MATLAB allows you to import Python packages into its environment. Co
 
    .. code-block:: bash
 
-      pip install codac4matlab --pre
-      # Option --pre has to be set because Codac v2 is only available in pre-release
+      pip install codac4matlab
 
 Once Codac is installed, you can use it in your MATLAB scripts using the following import command:
 

doc/manual/manual/installation/python.rst

@@ -7,22 +7,20 @@ Python installation
 
 In case you want to use Codac only with Python, then the installation procedure is simply:
 
-1. **Dependencies**: Ensure you have a supported version of Python (>=3.6).
+1. **Dependencies**: Ensure you have a supported version of Python (>=3.8).
 2. **Install via pip**: Use the following command to install Codac:
 
    .. code-block:: bash
 
-      pip install codac --pre
-      # Option --pre has to be set because Codac v2 is only available in pre-release
+      pip install codac
 
 
-You can also update and test your Codac Python package.
+You can also update and test your Codac Python package:
 
 * **Update via pip**: Use the following command to update your already installed Codac package:
    .. code-block:: bash
 
-      pip install codac --upgrade --pre
-      # Option --pre has to be set because Codac v2 is only available in pre-release
+      pip install codac --upgrade
 
 
 * **Testing the installation**: In order to verify that your installation is working properly in Python, you can run:
@@ -42,7 +40,7 @@ Depending on your configuration, you may encounter difficulties when installing
 
   .. code-block:: bash
 
-    pip3 install --break-system-packages codac --pre
+    pip3 install --break-system-packages codac
 
 .. admonition:: macOS Big Sur and later (x86_64)
 

doc/manual/manual/tools/index.rst

@@ -8,4 +8,5 @@ Tools
 
   serialization.rst
   registration.rst
-  octasym.rst
+  octasym.rst
+  sampled_traj_npz.rst

doc/manual/manual/tools/sampled_traj_npz.rst

@@ -0,0 +1,66 @@
+.. _sec-trajectories-sampledtraj:
+
+Sampled trajectories
+====================
+
+In Python, the ``SampledTraj`` name is a convenience wrapper that mimics the
+C++ template deduction style. Depending on the provided samples, it builds and
+returns one of the following objects:
+
+- ``SampledTraj_Scalar``
+- ``SampledTraj_Vector``
+- ``SampledTraj_Matrix``
+
+This keeps the user-facing syntax short and consistent with ``AnalyticTraj``.
+
+
+Loading a sampled trajectory from a ``.npz`` file
+-------------------------------------------------
+
+A sampled trajectory cannot be constructed directly from a file path.
+The recommended workflow is:
+
+1. load the ``.npz`` file with ``numpy.load``;
+2. extract the arrays containing the sampling times and sampled values;
+3. call ``SampledTraj(t, x)``.
+
+The wrapper then deduces the appropriate trajectory type from ``x``.
+
+.. tabs::
+
+  .. group-tab:: Python
+
+    .. code-block:: python
+
+      import numpy as np
+      from codac import *
+
+      data = np.load("traj_vec.npz")
+      traj = SampledTraj(data["t"], data["x"])
+
+      print(type(traj))
+
+In the above example, if ``x`` is a 2D array of shape ``(N,n)``, then
+``traj`` is a ``SampledTraj_Vector``.
+
+Another example:
+
+.. tabs::
+
+  .. group-tab:: Python
+
+    .. code-block:: python
+
+      import numpy as np
+      from codac import *
+
+      t = np.array([0.0, 0.5, 1.0, 1.5])
+      x = np.array([
+          [0.0, 1.0],
+          [0.5, 1.5],
+          [1.0, 2.0],
+          [1.5, 2.5],
+      ])
+
+      traj = SampledTraj(t, x)
+      print(traj) # outputs: SampledTraj. [0, 1.5]↦[[0, 1.5][1, 2.5]], 4 pts

doc/manual/manual/tubes/index.rst

@@ -0,0 +1,66 @@
+.. _sec-domains-tubes:
+
+Tubes
+=====
+
+  Main author: `Simon Rohou <https://www.simon-rohou.fr/research/>`_
+
+Introduction
+------------
+
+A tube is a set of trajectories. More precisely, if :math:`\mathcal{F}(\mathbb{R}\to\mathbb{R}^n)` denotes the set of trajectories with values in :math:`\mathbb{R}^n`, a tube :math:`\mathbb{X}(\cdot)` is a set-valued map
+
+.. math::
+
+   \mathbb{X}(\cdot): \mathbb{R} \to \mathcal{P}(\mathbb{R}^n)
+
+such that
+
+.. math::
+
+   \mathbf{x}(\cdot)\in\mathbb{X}(\cdot)
+   \;\Longleftrightarrow\;
+   \forall t,\ \mathbf{x}(t)\in\mathbb{X}(t).
+
+In other words, a tube encloses trajectories pointwise in time: for every time :math:`t`, the value :math:`\mathbf{x}(t)` must belong to the set :math:`\mathbb{X}(t)`. This definition is intentionally general. It does not encode additional temporal information such as continuity, monotonicity, or derivative constraints. Such properties may be handled separately, for instance by contractors or by combining several tubes.
+
+This point of view naturally extends interval and box representations. In the most common cases, :math:`\mathbb{X}(t)` is an interval, a box, or a matrix of intervals, but in principle it may be any codomain type for which suitable set operations are available.
+
+In Codac C++, this generality is reflected by the template ``SlicedTube<T>``. In principle, ``T`` can be any codomain type compatible with the sliced-tube algorithms.
+The library naturally provides and primarily uses:
+
+* ``SlicedTube<Interval>``,
+* ``SlicedTube<IntervalVector>``,
+* ``SlicedTube<IntervalMatrix>``.
+
+These are the most common tube types in practice. In Python and Matlab, only these standard sliced-tube classes are currently exposed through the bindings.
+In C++, instantiations such as ``SlicedTube<ConvexPolygon>`` are allowed, provided the required tube operations are available for that domain.
+
+This chapter documents the *sliced tube* implementation currently available in Codac. In this implementation, a tube is represented over an explicit temporal partition stored in a :class:`~codac.TDomain`. Each temporal element is a :class:`~codac.TSlice`, and each application-level value over one temporal element is represented by a :class:`~codac.Slice`. The main user-facing object is therefore a :class:`~codac.SlicedTube`.
+
+.. figure:: ./tube_slices.png
+  :width: 70%
+
+  An example of sliced tube :math:`[x](\cdot)`, as implemented in Codac. The tube is made as a list of interval or box slices. In practice, the sampling :math:`\delta` is not necessarily constant.
+
+Compared with the previous Codac v1 implementation, these tubes are not only functions of time: they also have shared data structures built on a common temporal partition. Refining the time partition of one tube may therefore update the internal slice structure of all tubes attached to the same :class:`~codac.TDomain`. This design is central to the current implementation. It simplifies the user experience: a temporal modification applied to one tube is implicitly propagated to the others, so multi-tube operations such as arithmetic combinations or contractions can still be performed easily on a consistent shared time basis.
+
+Conceptually, the data model is:
+
+.. code-block:: text
+
+   TDomain
+     ├── TSlice #0  ----> Slice<X> for tube x
+     │                └-> Slice<Y> for tube y
+     ├── TSlice #1  ----> Slice<X> for tube x
+     │                └-> Slice<Y> for tube y
+     └── ...
+
+
+This chapter is organized as follows:
+
+.. toctree::
+  :maxdepth: 1
+
+  tdomain
+  slicedtube