bluemira.optimisation._optimise

Definition of the generic optimise function.

Attributes

EPS

Functions

optimise(, ineq_constraints, keep_history, ...)

Find the parameters that minimise the given objective function.

validate_constraints(→ bool)

Check the given parameterisation satisfies the given constraints.

_make_optimiser(, ineq_constraints, *, keep_history)

Make a new optimiser object.

_process_bounds(→ tuple[numpy.ndarray, numpy.ndarray])

_check_constraints(→ list[str])

Check if any of the given constraints are violated by the parameterisation.

_eq_constraint_condition(→ numpy.ndarray)

_ineq_constraint_condition(→ numpy.ndarray)

_set_default_termination_conditions(...)

Module Contents

bluemira.optimisation._optimise.EPS
bluemira.optimisation._optimise.optimise(f_objective: bluemira.optimisation.typed.ObjectiveCallable, df_objective: bluemira.optimisation.typed.OptimiserCallable | None = None, *, x0: numpy.ndarray | None = None, dimensions: int | None = None, algorithm: bluemira.optimisation._algorithm.AlgorithmType = Algorithm.SLSQP, opt_conditions: collections.abc.Mapping[str, int | float] | None = None, opt_parameters: collections.abc.Mapping[str, Any] | None = None, bounds: tuple[numpy.typing.ArrayLike, numpy.typing.ArrayLike] | None = None, eq_constraints: collections.abc.Iterable[bluemira.optimisation.typed.ConstraintT] = (), ineq_constraints: collections.abc.Iterable[bluemira.optimisation.typed.ConstraintT] = (), keep_history: bool = False, check_constraints: bool = True, check_constraints_warn: bool = True) → bluemira.optimisation._optimiser.OptimiserResult

Find the parameters that minimise the given objective function.

Parameters:

  • f_objective (bluemira.optimisation.typed.ObjectiveCallable) – The objective function to minimise.

  • dimensions (int | None) – The dimensionality of the problem. This or x0 must be given.

  • x0 (numpy.ndarray | None) – The initial guess for the optimisation parameters. This or dimensions must be given, if both are given, x0.size must be equal to dimensions.

  • df_objective (bluemira.optimisation.typed.OptimiserCallable | None) – The derivative of the objective function.

  • algorithm (bluemira.optimisation._algorithm.AlgorithmType) – The optimisation algorithm to use. See enum Algorithm for supported algorithms. (default: "SLSQP")

  • opt_conditions (collections.abc.Mapping[str, int | float] | None) –

    The stopping conditions for the optimiser. Supported conditions are:

    • ftol_abs: float

    • ftol_rel: float

    • xtol_abs: float

    • xtol_rel: float

    • max_eval: int

    • max_time: float

    • stop_val: float

    for defaults see AlgorithmDefaultConditions.

  • opt_parameters (collections.abc.Mapping[str, Any] | None) – The algorithm-specific optimisation parameters.

  • bounds (tuple[numpy.typing.ArrayLike, numpy.typing.ArrayLike] | None) – The upper and lower bounds for the optimisation parameters. The first array being the lower bounds, the second the upper. This can also be None, in which case the bounds are (-inf, inf) for each optimisation parameter. You can also specify scalars for either the upper or lower bounds or both, and those bound will be applied to every optimisation parameter.

  • eq_constraints (collections.abc.Iterable[bluemira.optimisation.typed.ConstraintT]) –

    The equality constraints for the optimiser. A dict with keys:

    • f_constraint: the constraint function.

    • tolerance: the tolerances in each constraint dimension.

    • df_constraint (optional): the derivative of the constraint function. If not given, a numerical approximation of the gradient is made (if a gradient is required).

    A constraint is a vector-valued, non-linear, equality constraint of the form \(f_{c}(x) = 0\).

    The constraint function should have the form \(f(x) \rightarrow y\), where:

    • \(x\) is a numpy array of the optimisation parameters.

    • \(y\) is a numpy array containing the values of the constraint at \(x\), with size \(m\), where \(m\) is the dimensionality of the constraint.

    The tolerance array must have the same dimensionality as the constraint.

    The gradient function should have the same form as the constraint function, however its output should have size \(n \times m\) where \(m\) is the dimensionality of the constraint and \(n\) is the number of optimisation parameters.

    Equality constraints are only supported by algorithms:

    • SLSQP

    • COBYLA

    • ISRES

  • ineq_constraints (collections.abc.Iterable[bluemira.optimisation.typed.ConstraintT]) –

    The inequality constraints for the optimiser. This argument has the same form as the eq_constraint argument, but each constraint is in the form \(f_{c}(x) \le 0\).

    Inequality constraints are only supported by algorithms:

    • SLSQP

    • COBYLA

    • ISRES

  • keep_history (bool) – Whether to record the history of each step of the optimisation. (default: False)

  • check_constraints (bool) – Whether to check all constraints have been satisfied at the end of the optimisation, and warn if they have not. Note that, if this is set to False, the result’s constraints_satisfied attribute will be set to None.

  • check_constraints_warn (bool) – Whether to print a warning that constraints have not been satisfied at the end of an optimisation. This argument has no effect if check_constraints is False.

Returns:

  • The result of the optimisation; including the optimised parameters

  • and the number of iterations.

Raises:

ValueError – x0 or dimension not provided or sizes differ

Return type:

bluemira.optimisation._optimiser.OptimiserResult

bluemira.optimisation._optimise.validate_constraints(x_star: numpy.ndarray, eq_constraints: list[bluemira.optimisation.typed.ConstraintT], ineq_constraints: list[bluemira.optimisation.typed.ConstraintT], *, warn: bool = True) → bool

Check the given parameterisation satisfies the given constraints.

Additionally, print warnings listing constraints that are not satisfied.

Parameters:

  • x_star (numpy.ndarray) – The parameterisation to check the constraints against.

  • eq_constraints (list[bluemira.optimisation.typed.ConstraintT]) – The list of equality constraints to check.

  • ineq_constraints (list[bluemira.optimisation.typed.ConstraintT]) – The list of inequality constraints to check.

  • warn (bool) – Whether to print warnings if constraints are violated. Default is true.

Return type:

True if no constraints are violated by the parameterisation.

bluemira.optimisation._optimise._make_optimiser(f_objective: bluemira.optimisation.typed.ObjectiveCallable, dimensions: int, df_objective: bluemira.optimisation.typed.OptimiserCallable | None = None, algorithm: bluemira.optimisation._algorithm.AlgorithmType = Algorithm.SLSQP, opt_conditions: collections.abc.Mapping[str, int | float] | None = None, opt_parameters: collections.abc.Mapping[str, Any] | None = None, bounds: tuple[numpy.ndarray, numpy.ndarray] | None = None, eq_constraints: collections.abc.Iterable[bluemira.optimisation.typed.ConstraintT] = (), ineq_constraints: collections.abc.Iterable[bluemira.optimisation.typed.ConstraintT] = (), *, keep_history: bool = False) → bluemira.optimisation._optimiser.Optimiser

Make a new optimiser object.

Returns:

Configured optimiser.

Raises:

OptimisationError – Unknown Algorithm

Parameters:
Return type:

bluemira.optimisation._optimiser.Optimiser

bluemira.optimisation._optimise._process_bounds(bounds: tuple[numpy.typing.ArrayLike, numpy.typing.ArrayLike] | None, dims: int) → tuple[numpy.ndarray, numpy.ndarray]
Returns:

bounds converting None to +/-inf and expanding scalar bounds.

Raises:

ValueError – Length of bounds is not 2

Parameters:

  • bounds (tuple[numpy.typing.ArrayLike, numpy.typing.ArrayLike] | None)

  • dims (int)

Return type:

tuple[numpy.ndarray, numpy.ndarray]

bluemira.optimisation._optimise._check_constraints(x_star: numpy.ndarray, constraints: list[bluemira.optimisation.typed.ConstraintT], constraint_type: Literal['inequality', 'equality']) → list[str]

Check if any of the given constraints are violated by the parameterisation.

Returns:

a list of formatted warnings. If there are no warnings, there are no violations.

Parameters:
Return type:

list[str]

bluemira.optimisation._optimise._eq_constraint_condition(c_value: numpy.ndarray, tols: numpy.ndarray) → numpy.ndarray
Returns:

Condition under which an equality constraint is violated.

Parameters:

  • c_value (numpy.ndarray)

  • tols (numpy.ndarray)

Return type:

numpy.ndarray

bluemira.optimisation._optimise._ineq_constraint_condition(c_value: numpy.ndarray, tols: numpy.ndarray) → numpy.ndarray
Returns:

Condition under which an inequality constraint is violated, accounding for machine epsilon.

Parameters:

  • c_value (numpy.ndarray)

  • tols (numpy.ndarray)

Return type:

numpy.ndarray

bluemira.optimisation._optimise._set_default_termination_conditions(algorithm: bluemira.optimisation._algorithm.AlgorithmType, opt_conditions: collections.abc.Mapping[str, int | float] | None = None) → collections.abc.Mapping[str, int | float] | None
Returns:

The termination conditions, either provided or default

Parameters:

  • algorithm (bluemira.optimisation._algorithm.AlgorithmType)

  • opt_conditions (collections.abc.Mapping[str, int | float] | None)

Return type:

collections.abc.Mapping[str, int | float] | None