Types

class optimagic.typing.AggregationLevel

Enum to specify the aggregation level of objective functions and solvers.

SCALAR = 'scalar'

LEAST_SQUARES = 'least_squares'

LIKELIHOOD = 'likelihood'

class optimagic.typing.Direction

Enum to specify the direction of optimization.

MINIMIZE = 'minimize'

MAXIMIZE = 'maximize'

__new__(value)

class optimagic.typing.DictLikeAccess

Useful base class for replacing string-based dictionaries with dataclass instances and keeping backward compatability regarding read access to the data structure.

keys() → KeysView[str]

items() → ItemsView[str, Any]

values() → ValuesView[str]

class optimagic.typing.TupleLikeAccess

Useful base class for replacing tuples with dataclass instances and keeping backward compatability regarding read access to the data structure.

class optimagic.typing.ErrorHandling

Enum to specify the error handling strategy of the optimization algorithm.

RAISE = 'raise'

RAISE_STRICT = 'raise_strict'

CONTINUE = 'continue'

class optimagic.typing.EvalTask

Enum to specify the task of the evaluation function.

FUN = 'fun'

JAC = 'jac'

FUN_AND_JAC = 'fun_and_jac'

EXPLORATION = 'exploration'

class optimagic.typing.BatchEvaluator

optimagic.typing.PositiveInt

Type alias for positive integers (greater than 0).

alias of Annotated[int, Gt(gt=0)]

optimagic.typing.NonNegativeInt

Type alias for non-negative integers (greater than or equal to 0).

alias of Annotated[int, Ge(ge=0)]

optimagic.typing.PositiveFloat

Type alias for positive floats (greater than 0).

alias of Annotated[float, Gt(gt=0)]

optimagic.typing.NonNegativeFloat

Type alias for non-negative floats (greater than or equal to 0).

alias of Annotated[float, Ge(ge=0)]

optimagic.typing.ProbabilityFloat

Type alias for probability floats (between 0 and 1, inclusive).

alias of Annotated[float, Ge(ge=0), Le(le=1)]

optimagic.typing.NegativeFloat

Type alias for negative floats (less than 0).

alias of Annotated[float, Lt(lt=0)]

optimagic.typing.GtOneFloat

Type alias for floats greater than 1.

alias of Annotated[float, Gt(gt=1)]

optimagic.typing.UnitIntervalFloat

Type alias for floats in (0, 1].

alias of Annotated[float, Gt(gt=0), Le(le=1)]

optimagic.typing.YesNoBool = typing.Literal['yes', 'no'] | bool

Type alias for boolean values represented as ‘yes’ or ‘no’ strings or as boolean values.

optimagic.typing.DirectionLiteral

Type alias for optimization direction, either ‘minimize’ or ‘maximize’.

alias of Literal[‘minimize’, ‘maximize’]

optimagic.typing.BatchEvaluatorLiteral

Type alias for batch evaluator types, can be ‘joblib’, ‘pathos’, or ‘threading’.

alias of Literal[‘joblib’, ‘pathos’, ‘threading’]

optimagic.typing.ErrorHandlingLiteral

Type alias for error handling strategies, can be ‘raise’ or ‘continue’.

alias of Literal[‘raise’, ‘continue’]

optimagic.typing.DEFAULT_PYDANTIC_CONFIG = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_default': True}

coerce generous inputs to strict types.

Type:

Pydantic config for user-facing options

optimagic.typing.STRICT_PYDANTIC_CONFIG = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'strict': True, 'validate_default': True}

reject inputs that need conversion.

Type:

Pydantic config for internal types

optimagic.typing.validated_dataclass(config: ConfigDict, make_error: Callable[[ValidationError], Exception]) → Callable[[type[DataclassT]], type[DataclassT]]

Create a class decorator that adds pydantic validation to a frozen dataclass.

The decorated class is re-created as a pydantic dataclass, so field values are validated and converted according to their type annotations on every instantiation (including via dataclasses.replace). Annotations are resolved at runtime, so this also works in modules using from __future__ import annotations.

This is deliberately a layer on top of existing dataclasses rather than a replacement for pydantic.dataclasses.dataclass at the definition site, for two reasons. First, it keeps the classes themselves plain frozen dataclasses, which made adopting pydantic non-breaking: algorithm classes — including ones defined outside optimagic — are still written as regular dataclasses and gain validation through mark.minimizer without any change to their definition. Second, it raises domain-specific exceptions (built by make_error) instead of pydantic.ValidationError, which preserves optimagic’s exception contracts; pydantic itself has no hook to customize the raised exception type.

Parameters:

• config – The pydantic config that controls validation behavior.

• make_error – Called with the raised pydantic.ValidationError to build the exception that is raised in its place.

Returns:

A class decorator for frozen dataclasses.

class optimagic.typing.IterationHistory

History of iterations in a process.

params

A list of parameters used in each iteration.

Type:

list[Any]

criterion

A list of criterion values obtained in each iteration.

runtime

A list or array of runtimes associated with each iteration.

params: list[Any]

fun: list[float]

time: list[float] | ndarray[tuple[Any, ...], dtype[float64]]

class optimagic.typing.MultiStartIterationHistory

History of multiple start iterations.

history

The main iteration history, representing the best end value.

Type:

optimagic.typing.IterationHistory

local_histories

Optional, a list of local iteration histories.

Type:

list[optimagic.typing.IterationHistory] | None

exploration

Optional, iteration history for exploration steps.

Type:

optimagic.typing.IterationHistory | None

history: IterationHistory

local_histories: list[IterationHistory] | None = None

exploration: IterationHistory | None = None