Update interface documentation

crates/ego/src/egor.rs

@@ -147,11 +147,15 @@ impl<O: GroupFunc, C: CstrFn> EgorFactory<O, C> {
         }
     }
 
+    /// Set configuration of the optimizer
     pub fn configure<F: FnOnce(EgorConfig) -> EgorConfig>(mut self, init: F) -> Self {
         self.config = init(self.config);
         self
     }
 
+    /// This function allows to define complex constraints on inputs using functions [CstrFn] trait.
+    /// Bounds constraints are better specified using `min_within()` or `min_within_mixint_space()`
+    /// arguments.
     pub fn subject_to(mut self, fcstrs: Vec<C>) -> Self {
         self.fcstrs = fcstrs;
         self

crates/ego/src/types.rs

@@ -161,24 +161,28 @@ pub trait SurrogateBuilder: Clone + Serialize + Sync {
     ) -> Result<Box<dyn MixtureGpSurrogate>>;
 }
 
-// A trait for functions used by internal optimizers
-pub trait ObjFn<U>: Fn(&[f64], Option<&mut [f64]>, &mut U) -> f64 {
-    //type Cstr;
-}
-impl<T, U> ObjFn<U> for T
-where
-    T: Fn(&[f64], Option<&mut [f64]>, &mut U) -> f64,
-{
-    //type Cstr = Cstr;
-}
-
+/// A trait for functions used by internal optimizers
+/// Functions are expected to be defined as `g(x, g, u)` where
+/// * `x` is the input information,
+/// * `g` an optional gradient information to be updated if present
+/// * `u` information provided by the user
+pub trait ObjFn<U>: Fn(&[f64], Option<&mut [f64]>, &mut U) -> f64 {}
+impl<T, U> ObjFn<U> for T where T: Fn(&[f64], Option<&mut [f64]>, &mut U) -> f64 {}
+
+/// A function trait for domain constraints used by the internal optimizer
+/// It is a specialized version of [`ObjFn`] with [`InfillObjData`] as user information
 pub trait CstrFn: Clone + ObjFn<InfillObjData<f64>> + Sync {}
 impl<T> CstrFn for T where T: Clone + ObjFn<InfillObjData<f64>> + Sync {}
 
-// A function type for domain constraints which will be used by the internal optimizer
+/// A function type for domain constraints which will be used by the internal optimizer
+/// which is the default value for [`EgorBuilder`] generic `C` parameter.
 pub type Cstr = fn(&[f64], Option<&mut [f64]>, &mut InfillObjData<f64>) -> f64;
 
 /// Data used by internal infill criteria optimization
+/// Internally this type is used to carry the information required to
+/// compute the various infill criteria implemented by [`Egor`].
+///
+/// See [`crate::criteria`]
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct InfillObjData<F: Float> {
     pub fmin: F,

python/egobox/egobox.pyi

@@ -123,13 +123,20 @@ class Egor:
             Random generator seed to allow computation reproducibility.
     """
     def __new__(cls,xspecs,n_cstr = ...,cstr_tol = ...,n_start = ...,n_doe = ...,doe = ...,regr_spec = ...,corr_spec = ...,infill_strategy = ...,q_points = ...,par_infill_strategy = ...,infill_optimizer = ...,kpls_dim = ...,trego = ...,n_clusters = ...,n_optmod = ...,target = ...,outdir = ...,warm_start = ...,hot_start = ...,seed = ...): ...
-    def minimize(self, fun,max_iters = ...) -> OptimResult:
+    def minimize(self, fun,max_iters = ..., fcstrs = ...) -> OptimResult:
         r"""
         This function finds the minimum of a given function `fun`
         
         # Parameters
             max_iters:
                 the iteration budget, number of fun calls is n_doe + q_points * max_iters.
+
+            fcstrs: 
+                list of constraints functions defined as g(x, return_grad): (ndarray[nx], bool) -> float or ndarray[nx,]
+                If the given `return_grad` boolean is `False` the function has to return the constraint float value
+                to be made negative by the optimizer (which drives the input array `x`).
+                Otherwise the function has to return the gradient (ndarray[nx,]) of the constraint funtion
+                wrt the `nx` components of `x`.
         
         # Returns
             optimization result

python/src/egor.rs

@@ -267,7 +267,14 @@ impl Egor {
     ///
     /// # Parameters
     ///     max_iters:
-    ///         the iteration budget, number of fun calls is n_doe + q_points * max_iters.
+    ///         the iteration budget, number of fun calls is `n_doe + q_points * max_iters`.
+    ///
+    ///     fcstrs:
+    ///         list of constraints functions defined as g(x, return_grad): (ndarray[nx], bool) -> float or ndarray[nx,]
+    ///         If the given `return_grad` boolean is `False` the function has to return the constraint float value
+    ///         to be made negative by the optimizer (which drives the input array `x`).
+    ///         Otherwise the function has to return the gradient (ndarray[nx,]) of the constraint funtion
+    ///         wrt the `nx` components of `x`.
     ///
     /// # Returns
     ///     optimization result