blackboxopt.base

call_functions_with_evaluations_and_collect_errors(functions, evaluations)

The given evaluations are passed to all given functions in order and the first Exception that occurrs for an evaluation is recorded alongside the evaluation and raised together with all erroneous evaluations as part of an EvaluationsError.

NOTE: Even if reporting some evaluations fails, all that can be are successfully reported. Also, if an evaluation passes through some of the functions before causing issues, the effect the evaluation had on the previous functions can't be reverted.

Exceptions:

Type	Description
EvaluationsError	In case exceptions occurred when calling the functions with the evaluations.

Source code in blackboxopt/base.py

def call_functions_with_evaluations_and_collect_errors(
    functions: Iterable[Callable[[Evaluation], None]],
    evaluations: Iterable[Evaluation],
) -> None:
    """The given evaluations are passed to all given functions in order and the first
    Exception that occurrs for an evaluation is recorded alongside the evaluation and
    raised together with all erroneous evaluations as part of an `EvaluationsError`.

    NOTE: Even if reporting some evaluations fails, all that can be are successfully
    reported. Also, if an evaluation passes through some of the functions before causing
    issues, the effect the evaluation had on the previous functions can't be reverted.

    Raises:
        EvaluationsError: In case exceptions occurred when calling the functions with
            the evaluations.
    """
    evaluations_with_errors = []
    for evaluation in evaluations:
        for func in functions:
            try:
                func(evaluation)
            except EvaluationsError as e:
                evaluations_with_errors.extend(e.evaluations_with_errors)
                break
            except Exception as e:
                evaluations_with_errors.append((evaluation, e))
                break

    if evaluations_with_errors:
        raise EvaluationsError(evaluations_with_errors)

ConstraintsError

Raised on incomplete or missing constraints.

ContextError

Raised on incomplete or missing context information.

EvaluationsError

Raised on invalid evaluations.

The problematic evaluations and their respective exceptions are passed in the evaluations_with_errors attribute.

MultiObjectiveOptimizer

get_evaluation_specification(self) inherited

Get next configuration and settings to evaluate.

Exceptions:

Type	Description
OptimizationComplete	When the optimization run is finished, e.g. when the budget has been exhausted.
OptimizerNotReady	When the optimizer is not ready to propose a new evaluation specification.

Source code in blackboxopt/base.py

@abc.abstractmethod
def get_evaluation_specification(self) -> EvaluationSpecification:
    """Get next configuration and settings to evaluate.

    Raises:
        OptimizationComplete: When the optimization run is finished, e.g. when the
            budget has been exhausted.
        OptimizerNotReady: When the optimizer is not ready to propose a new
            evaluation specification.
    """

report(self, evaluations)

Report one or more evaluated evaluation specifications.

NOTE: Not all optimizers support reporting results for evaluation specifications that were not proposed by the optimizer.

Parameters:

Name	Type	Description	Default
evaluations	Union[blackboxopt.evaluation.Evaluation, Iterable[blackboxopt.evaluation.Evaluation]]	A single evaluated evaluation specifications, or an iterable	required

Source code in blackboxopt/base.py

def report(self, evaluations: Union[Evaluation, Iterable[Evaluation]]) -> None:
    _evals = [evaluations] if isinstance(evaluations, Evaluation) else evaluations

    call_functions_with_evaluations_and_collect_errors(
        [functools.partial(validate_objectives, objectives=self.objectives)],
        _evals,
    )

Objective dataclass

Objective(name: str, greater_is_better: bool)

ObjectivesError

Raised on incomplete or missing objectives.

OptimizationComplete

Exception that is raised when the optimization run is finished, e.g. when the budget has been exhausted.

Optimizer

Abstract base class for blackbox optimizer implementations.

get_evaluation_specification(self)

Get next configuration and settings to evaluate.

Exceptions:

Type	Description
OptimizationComplete	When the optimization run is finished, e.g. when the budget has been exhausted.
OptimizerNotReady	When the optimizer is not ready to propose a new evaluation specification.

Source code in blackboxopt/base.py

@abc.abstractmethod
def get_evaluation_specification(self) -> EvaluationSpecification:
    """Get next configuration and settings to evaluate.

    Raises:
        OptimizationComplete: When the optimization run is finished, e.g. when the
            budget has been exhausted.
        OptimizerNotReady: When the optimizer is not ready to propose a new
            evaluation specification.
    """

report(self, evaluations)

Report one or more evaluated evaluation specifications.

NOTE: Not all optimizers support reporting results for evaluation specifications that were not proposed by the optimizer.

Parameters:

Name	Type	Description	Default
evaluations	Union[blackboxopt.evaluation.Evaluation, Iterable[blackboxopt.evaluation.Evaluation]]	A single evaluated evaluation specifications, or an iterable	required

Source code in blackboxopt/base.py

@abc.abstractmethod
def report(self, evaluations: Union[Evaluation, Iterable[Evaluation]]) -> None:
    """Report one or more evaluated evaluation specifications.

    NOTE: Not all optimizers support reporting results for evaluation specifications
    that were not proposed by the optimizer.

    Args:
        evaluations: A single evaluated evaluation specifications, or an iterable
        of many.
    """

OptimizerNotReady

Exception that is raised when the optimizer is not ready to propose a new evaluation specification.

raise_on_unknown_or_incomplete(exception, known, reported)

Raise the given exception if not all known strings are contained in reported or the other way around.

Source code in blackboxopt/base.py

def raise_on_unknown_or_incomplete(
    exception: Type[ValueError], known: Iterable[str], reported: Iterable[str]
) -> None:
    """Raise the given exception if not all known strings are contained in reported or
    the other way around.
    """
    known_set = set(known)
    reported_set = set(reported)

    unknown = reported_set - known_set
    if unknown:
        raise exception(
            f"Unknown reported: {list(unknown)}. Valid are only: {list(known_set)}"
        )
    missing = known_set - reported_set
    if missing:
        raise exception(f"Missing: {list(missing)}")

SingleObjectiveOptimizer

get_evaluation_specification(self) inherited

Get next configuration and settings to evaluate.

Exceptions:

Type	Description
OptimizationComplete	When the optimization run is finished, e.g. when the budget has been exhausted.
OptimizerNotReady	When the optimizer is not ready to propose a new evaluation specification.

Source code in blackboxopt/base.py

@abc.abstractmethod
def get_evaluation_specification(self) -> EvaluationSpecification:
    """Get next configuration and settings to evaluate.

    Raises:
        OptimizationComplete: When the optimization run is finished, e.g. when the
            budget has been exhausted.
        OptimizerNotReady: When the optimizer is not ready to propose a new
            evaluation specification.
    """

report(self, evaluations)

Report one or multiple evaluations to the optimizer.

All valid evaluations are processed. Faulty evaluations are not processed, instead an EvaluationsError is raised, which includes the problematic evaluations with their respective Exceptions in the evaluations_with_errors attribute.

Parameters:

Name	Type	Description	Default
evaluations	Union[blackboxopt.evaluation.Evaluation, Iterable[blackboxopt.evaluation.Evaluation]]	A single evaluated evaluation specifications, or an iterable	required

Exceptions:

Type	Description
EvaluationsError	Raised when an evaluation could not be processed.

Source code in blackboxopt/base.py

def report(self, evaluations: Union[Evaluation, Iterable[Evaluation]]) -> None:
    """Report one or multiple evaluations to the optimizer.

    All valid evaluations are processed. Faulty evaluations are not processed,
    instead an `EvaluationsError` is raised, which includes the problematic
    evaluations with their respective Exceptions in the `evaluations_with_errors`
    attribute.

    Args:
        evaluations: A single evaluated evaluation specifications, or an iterable
        of many.

    Raises:
        EvaluationsError: Raised when an evaluation could not be processed.
    """
    _evals = [evaluations] if isinstance(evaluations, Evaluation) else evaluations

    call_functions_with_evaluations_and_collect_errors(
        [functools.partial(validate_objectives, objectives=[self.objective])],
        _evals,
    )