Clearer docs on Cartesian product in Rust and Python

About:
- Clarification re Cartesian product in Rust/python
- Additional unit tests

Issues:
- Addresses #345

Author: alphaville

docs/content/openrust-basic.md

@@ -88,6 +88,22 @@ Constraints implement the namesake trait, [`Constraint`]. Implementations of [`C
 
 These are the most common constraints in practice.
 
+:::note Cartesian products in Rust
+The Rust API for [`CartesianProduct`] uses cumulative lengths, equivalently
+exclusive end indices.
+
+For example, if `x0 = x[0..3]` and `x1 = x[3..5]`, then you would write:
+
+```rust
+let cart_prod = constraints::CartesianProduct::new()
+    .add_constraint(3, c0)
+    .add_constraint(5, c1);
+```
+
+This differs from the Python API, which uses inclusive last indices such as
+`[2, 4]` for the same two segments.
+:::
+
 The construction of a constraint is very easy. Here is an example of a Euclidean ball centered at the origin with given radius:
 
 ```rust

docs/content/python-interface.md

@@ -99,6 +99,14 @@ following types of constraints:
 
 A Cartesian product is a set $C = C_0 \times C_1 \times \ldots \times C_{s}$. In $\mathbb{R}^n$, a vector $x$ can be segmented as $$x=(x_{(0)}, x_{(1)}, \ldots, x_{(s)}),$$ into $s$ segments, $x_{(i)}\in\mathbb{R}^{m_i}$. The constraint $x \in C$ means $$x_{(i)} \in C_i,$$ for all $i=0,\ldots, s$. For example, consider the vector $x = ({\color{blue}{x_0}}, {\color{blue}{x_1}}, {\color{red}{x_2}}, {\color{red}{x_3}}, {\color{red}{x_4}})$; define the segments $$x_{(0)} = ({\color{blue}{x_0}}, {\color{blue}{x_1}}),\ x_{(1)} = ({\color{red}{x_2}}, {\color{red}{x_3}}, {\color{red}{x_4}})$$ These can be identified by the indices `1` and `4` (last indices of segments). 
 
+:::note
+In Python, `CartesianProduct` uses inclusive last indices for each segment.
+For example, `segment_ids = [1, 4]` means the segments `x[0:2]` and `x[2:5]`.
+
+This is different from the Rust API, where Cartesian products are specified
+using cumulative lengths / exclusive end indices.
+:::
+
 
 Let us give an example: we will define the Cartesian product of a ball with a rectangle. 
 Suppose that $U$ is a Euclidean ball with radius $r=1.5$ centered at

python/opengen/constraints/cartesian.py

@@ -19,6 +19,15 @@ def __init__(self, segments: List[int], constraints: List[constraint.Constraint]
         We can associate with :math:`x_{[1]}` the indices [0, 1] and with :math:`x_{[2]}` the indices [2, 3, 4].
         The *segment ids* are the indices 1 and 4.
 
+        Important:
+            In Python, `segments` uses inclusive last indices. For example,
+            `segments=[1, 4]` means that the first segment is `x[0:2]` and the
+            second segment is `x[2:5]`.
+
+            This convention is different from the Rust API, where Cartesian
+            products are specified using cumulative lengths / exclusive end
+            indices.
+
         Example:
             In this example we shall define the set :math:`X = \mathcal{B}_{1.5} \\times R \\times {\\rm I\!R}^{5}`, 
             where :math:`\mathcal{B}_{1.5}` is a Euclidean ball of dimension 2 with radius 1.5, :math:`R` is a  
@@ -31,7 +40,7 @@ def __init__(self, segments: List[int], constraints: List[constraint.Constraint]
             >>> segment_ids = [1, 4, 9]
             >>> my_set = og.constraints.CartesianProduct(segment_ids, [ball, rect, free])
 
-        :param segments: ids of segments
+        :param segments: inclusive last indices of segments
         :param constraints: list of sets
         """
 
@@ -44,7 +53,7 @@ def __init__(self, segments: List[int], constraints: List[constraint.Constraint]
 
         if segments[0] < 0:
             raise ValueError(
-                "the first element of segment must be a positive integer")
+                "the first element of segment must be a non-negative integer")
 
         if len(segments) != len(constraints):
             raise ValueError(

python/test/test_constraints.py

@@ -345,6 +345,20 @@ def test_cartesian_segments_empty_args(self):
         with self.assertRaises(ValueError) as __context:
             og.constraints.CartesianProduct([], sets)
 
+    def test_cartesian_segment_ids_are_inclusive_last_indices(self):
+        cartesian = og.constraints.CartesianProduct(
+            [0, 2, 5],
+            [
+                og.constraints.NoConstraints(),
+                og.constraints.NoConstraints(),
+                og.constraints.NoConstraints(),
+            ],
+        )
+
+        self.assertEqual(1, cartesian.segment_dimension(0))
+        self.assertEqual(2, cartesian.segment_dimension(1))
+        self.assertEqual(3, cartesian.segment_dimension(2))
+
     def test_cartesian_convex(self):
         ball_inf = og.constraints.BallInf(None, 1)
         ball_eucl = og.constraints.Ball2(None, 1)

rust/src/constraints/cartesian_product.rs

@@ -22,6 +22,17 @@ use crate::FunctionCallResult;
 /// The constraint $x \in C$ is interpreted as $x_i \in C_i$
 /// for all $i=0,\ldots, n-1$.
 ///
+/// # Indexing convention
+///
+/// In Rust, Cartesian products are defined using cumulative lengths
+/// (equivalently, exclusive end indices).
+///
+/// For example, `.add_constraint(2, c0).add_constraint(5, c1)` means that
+/// `c0` acts on `x[0..2]` and `c1` acts on `x[2..5]`.
+///
+/// This differs from the Python API, which uses inclusive last indices such
+/// as `[1, 4]` for the same two segments.
+///
 #[derive(Default)]
 pub struct CartesianProduct<'a, T = f64> {
     idx: Vec<usize>,
@@ -91,7 +102,8 @@ impl<'a, T> CartesianProduct<'a, T> {
     ///
     /// # Arguments
     ///
-    /// - `ni`: total length of the vector `(x_0, \ldots, x_i)` (see example below)
+    /// - `ni`: total length of the vector `(x_0, \ldots, x_i)` (that is, the
+    ///   exclusive end index of the `i`-th segment; see example below)
     /// - `constraint`: constraint to add; it must implement the trait `Constraint`
     ///
     ///

rust/src/constraints/tests.rs

@@ -634,6 +634,21 @@ fn t_cartesian_product_dimension() {
     );
 }
 
+#[test]
+fn t_cartesian_product_indices_are_cumulative_lengths() {
+    let cartesian = CartesianProduct::new()
+        .add_constraint(1, NoConstraints::new())
+        .add_constraint(3, NoConstraints::new())
+        .add_constraint(6, NoConstraints::new());
+
+    assert_eq!(6, cartesian.dimension());
+
+    let mut x = [10.0, 20.0, 30.0, 40.0, 50.0, 60.0];
+    let original = x;
+    cartesian.project(&mut x).unwrap();
+    assert_eq!(original, x);
+}
+
 #[test]
 fn t_cartesian_ball_no_constraint() {
     let xc = [1., 0., 0.];