API Reference

An implementation of SCE-UA Algorithm for single-objective optimization.

References

• Duan, Q., Sorooshian, S., & Gupta, V. K. (1992). Effective and efficient global optimization for conceptual rainfall-runoff models. Water Resources Research, 28(4), 1015-1031. doi:10.1029/91WR02985
• Duan, Q., Gupta, V. K., & Sorooshian, S. (1994). Optimal use of the SCE-UA global optimization method for calibrating watershed models. Journal of Hydrology, 158(3-4), 265-284. doi:10.1016/0022-1694(94)90057-4
• Duan, Q., Sorooshian, S., & Gupta, V. K. (1994). A shuffled complex evolution approach for effective and efficient global minimization. Journal of optimization theory and applications, 76(3), 501-521. doi:10.1007/BF00939380
• Muttil, N., & Jayawardena, A. W. (2008). Shuffled Complex Evolution model calibrating algorithm: enhancing its robustness and efficiency. Hydrological Processes, 22(23), 4628-4638. Portico. doi:10.1002/hyp.7082
• Chu, W., Gao, X., & Sorooshian, S. (2010). Improving the shuffled complex evolution scheme for optimization of complex nonlinear hydrological systems: Application to the calibration of the Sacramento soil-moisture accounting model. Water Resources Research, 46(9). Portico. doi:10.1029/2010wr009224

Result dataclass

Result(x, fun, nit, nfev, message, success, xv, funv)

Result object for the optimization.

Attributes:

• x (ndarray) –

  Best parameters found.

• fun (float) –

  Best function value corresponding to the best parameters.

• nit (int) –

  Number of iterations.

• nfev (int) –

  Number of function evaluations.

• message (str) –

  Message describing the termination reason.

• success (bool) –

  Whether the optimization was successful.

• xv (ndarray) –

  All evaluated parameter sets.

• funv (ndarray) –

  Function values for all evaluated parameter sets.

minimize

minimize(
    func,
    bounds,
    *,
    args=(),
    n_complexes=None,
    n_points_complex=None,
    alpha=1.0,
    beta=0.5,
    max_evals=50000,
    max_iter=1000,
    max_tolerant_iter=30,
    tolerance=1e-06,
    x_tolerance=1e-08,
    seed=None,
    pca_freq=1,
    pca_tol=0.001,
    x0=None,
    max_workers=1
)

Minimize a function using an improved SCE-UA algorithm.

Parameters:

• func (callable) –

  The objective function to be minimized. func(x, *args) -> float where x is an 1-D array with shape (n,) and args are positional arguments.

• bounds (sequence of tuples) –

  Bounds for variables, (min, max) pairs for each element in x.

• args (tuple, default: () ) –

  Extra arguments passed to the objective function, defaults to ().

• n_complexes (int, default: None ) –

  Number of complexes, defaults to None (adaptive based on dimensionality).

• n_points_complex (int, default: None ) –

  Number of points in each complex. If None, calculated automatically.

• alpha (float, default: 1.0 ) –

  Reflection coefficient, defaults to 1.0.

• beta (float, default: 0.5 ) –

  Contraction coefficient, defaults to 0.5.

• max_evals (int, default: 50000 ) –

  Maximum number of function evaluations, defaults to 50000.

• max_iter (int, default: 1000 ) –

  Maximum number of iterations, defaults to 1000.

• max_tolerant_iter (int, default: 30 ) –

  Maximum number of tolerated iterations without improvement, defaults to 30.

• tolerance (float, default: 1e-06 ) –

  Tolerance for improvement in function value, defaults to 1e-6.

• x_tolerance (float, default: 1e-08 ) –

  Tolerance for parameter convergence (parameter space), defaults to 1e-8.

• seed (int, default: None ) –

  Random seed for reproducibility, defaults to None.

• pca_freq (int, default: 1 ) –

  Frequency of PCA recovery, defaults to 1, i.e., every iterations.

• pca_tol (float, default: 0.001 ) –

  Tolerance for PCA recovery, defaults to 1e-3. This is the threshold for eigenvalues to be considered significant. This threshold is used to apply PCA recovery based on the ratio of eigenvalues to the maximum eigenvalue, i.e., eig / max(eig) < pca_tol.

• x0 (ndarray, default: None ) –

  Initial parameter sets to evaluate, defaults to None.

• max_workers (int, default: 1 ) –

  Number of workers for parallel execution, defaults to 1 (no parallelism). This is passed to the ThreadPoolExecutor.

Returns:

• result ( Result ) –

  The optimization result with the following fields:

  • x : numpy.ndarray The optimal parameters found.
  • fun : float Best function value corresponding to the best parameters.
  • nit : int Number of iterations.
  • nfev : int Number of function evaluations.
  • message : str Description of the termination reason.
  • success : bool Whether the optimizer exited successfully.
  • xv : numpy.ndarray All parameter vectors that were evaluated.
  • funv : numpy.ndarray Function values for all evaluated parameter vectors.