bluemira.optimisation._optimise =============================== .. py:module:: bluemira.optimisation._optimise .. autoapi-nested-parse:: Definition of the generic `optimise` function. Attributes ---------- .. autoapisummary:: bluemira.optimisation._optimise.EPS Functions --------- .. autoapisummary:: bluemira.optimisation._optimise.optimise bluemira.optimisation._optimise.validate_constraints bluemira.optimisation._optimise._make_optimiser bluemira.optimisation._optimise._process_bounds bluemira.optimisation._optimise._check_constraints bluemira.optimisation._optimise._eq_constraint_condition bluemira.optimisation._optimise._ineq_constraint_condition bluemira.optimisation._optimise._set_default_termination_conditions Module Contents --------------- .. py:data:: EPS .. py:function:: 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. :param f_objective: The objective function to minimise. :param dimensions: The dimensionality of the problem. This or ``x0`` must be given. :param x0: The initial guess for the optimisation parameters. This or `dimensions` must be given, if both are given, ``x0.size`` must be equal to ``dimensions``. :param df_objective: The derivative of the objective function. :param algorithm: The optimisation algorithm to use. See enum :class:`~bluemira.optimisation._algorithm.Algorithm` for supported algorithms. (default: ``"SLSQP"``) :param opt_conditions: 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 :class:`~bluemira.optimisation._algorithm.AlgorithmDefaultConditions`. :param opt_parameters: The algorithm-specific optimisation parameters. :param bounds: 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. :param eq_constraints: 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 :math:`f_{c}(x) = 0`. The constraint function should have the form :math:`f(x) \rightarrow y`, where: * :math:`x` is a numpy array of the optimisation parameters. * :math:`y` is a numpy array containing the values of the constraint at :math:`x`, with size :math:`m`, where :math:`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 :math:`n \times m` where :math:`m` is the dimensionality of the constraint and :math:`n` is the number of optimisation parameters. Equality constraints are only supported by algorithms: * SLSQP * COBYLA * ISRES :param ineq_constraints: The inequality constraints for the optimiser. This argument has the same form as the ``eq_constraint`` argument, but each constraint is in the form :math:`f_{c}(x) \le 0`. Inequality constraints are only supported by algorithms: * SLSQP * COBYLA * ISRES :param keep_history: Whether to record the history of each step of the optimisation. (default: False) :param check_constraints: 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``. :param check_constraints_warn: 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 .. py:function:: 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. :param x_star: The parameterisation to check the constraints against. :param eq_constraints: The list of equality constraints to check. :param ineq_constraints: The list of inequality constraints to check. :param warn: Whether to print warnings if constraints are violated. Default is true. :rtype: True if no constraints are violated by the parameterisation. .. py:function:: _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 .. py:function:: _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 .. py:function:: _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. .. py:function:: _eq_constraint_condition(c_value: numpy.ndarray, tols: numpy.ndarray) -> numpy.ndarray :returns: Condition under which an equality constraint is violated. .. py:function:: _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. .. py:function:: _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