sphere2: API documentation

src/constraints/sphere2.rs

@@ -1,8 +1,8 @@
 use super::Constraint;
 
 #[derive(Copy, Clone)]
-/// A Euclidean sphere, that is, a set given by $B_2^r = \\{x \in \mathbb{R}^n {}:{} \Vert{}x{}\Vert = r\\}$
-/// or a Euclidean sphere centered at a point $x_c$, that is, $B_2^{x_c, r} = \\{x \in \mathbb{R}^n {}:{} \Vert{}x-x_c{}\Vert = r\\}$
+/// A Euclidean sphere, that is, a set given by $S_2^r = \\{x \in \mathbb{R}^n {}:{} \Vert{}x{}\Vert = r\\}$
+/// or a Euclidean sphere centered at a point $x_c$, that is, $S_2^{x_c, r} = \\{x \in \mathbb{R}^n {}:{} \Vert{}x-x_c{}\Vert = r\\}$
 pub struct Sphere2<'a> {
     center: Option<&'a [f64]>,
     radius: f64,
@@ -18,13 +18,16 @@ impl<'a> Sphere2<'a> {
 }
 
 impl<'a> Constraint for Sphere2<'a> {
-    /// Projection onto the set, that is,
+    /// Projection onto the sphere, $S_{r, c}$ with radius $r$ and center $c$.
+    /// If $x\neq c$, the projection is uniquely defined by
     ///
     /// $$
-    /// \Pi_C(v) = \mathrm{argmin}_{z\in C}\Vert{}z-v{}\Vert
+    /// P_{S_{r, c}}(x) = c + r\frac{x-c}{\Vert{}x-c\Vert_2},
     /// $$
     ///
-    ///
+    /// but for $x=c$, the projection is multi-valued. In particular, let
+    /// $y = P_{S_{r, c}}(c)$. Then $y_1 = c_1 + r$ and $y_i = c_i$ for
+    /// $i=2,\ldots, n$.
     ///
     /// ## Arguments
     ///
@@ -53,6 +56,8 @@ impl<'a> Constraint for Sphere2<'a> {
         }
     }
 
+    /// Returns false (the sphere is not a convex set)
+    ///
     fn is_convex(&self) -> bool {
         false
     }