Optimizer

amltk.optimization.optimizer

The base Optimizer class, defines the API we require optimizers to implement.

• ask() - Ask the optimizer for a new Trial to evaluate.
• tell() - Tell the optimizer the result of the sampled config. This comes in the form of a Trial.Report.

Additionally, to aid users from switching between optimizers, the preferred_parser() method should return either a parser function or a string that can be used with node.search_space(parser=..._) to extract the search space for the optimizer.

Optimizer

Optimizer(
    metrics: Sequence[Metric],
    bucket: PathBucket | None = None,
)

Bases: Generic[I]

An optimizer protocol.

An optimizer is an object that can be asked for a trail using ask and a tell to inform the optimizer of the report from that trial.

PARAMETER	DESCRIPTION
metrics	The metrics to optimize. TYPE: Sequence[Metric]
bucket	The bucket to store results of individual trials from this optimizer. TYPE: PathBucket | None DEFAULT: None

Source code in src/amltk/optimization/optimizer.py

def __init__(
    self,
    metrics: Sequence[Metric],
    bucket: PathBucket | None = None,
) -> None:
    """Initialize the optimizer.

    Args:
        metrics: The metrics to optimize.
        bucket: The bucket to store results of individual trials from this
            optimizer.
    """
    super().__init__()
    if not all_unique(metric.name for metric in metrics):
        raise ValueError(
            "All metrics must have unique names."
            f"Got {metrics} with names {[metric.name for metric in metrics]}",
        )

    self.metrics = MetricCollection.from_collection(metrics)
    self.bucket = (
        bucket
        if bucket is not None
        else PathBucket(f"{self.__class__.__name__}-{datetime.now().isoformat()}")
    )

bucket instance-attribute

bucket: PathBucket = (
    bucket
    if bucket is not None
    else PathBucket(f"{__name__}-{isoformat()}")
)

The bucket to give to trials generated by this optimizer.

metrics instance-attribute

metrics: MetricCollection = from_collection(metrics)

The metrics to optimize.

CreateSignature

Bases: Protocol

A Protocol which defines the keywords required to create an optimizer with deterministic behavior at a desired location.

This protocol matches the Optimizer.create classmethod, however we also allow any function which accepts the keyword arguments to create an Optimizer.

__call__

__call__(
    *,
    space: Node,
    metrics: Metric | Sequence[Metric],
    bucket: PathBucket | None = None,
    seed: Seed | None = None
) -> Optimizer

A function which creates an optimizer for node.optimize should accept the following keyword arguments.

PARAMETER	DESCRIPTION
space	The node to optimize TYPE: Node
metrics	The metrics to optimize TYPE: Metric | Sequence[Metric]
bucket	The bucket to store the results in TYPE: PathBucket | None DEFAULT: None
seed	The seed to use for the optimization TYPE: Seed | None DEFAULT: None

Source code in src/amltk/optimization/optimizer.py

def __call__(
    self,
    *,
    space: Node,
    metrics: Metric | Sequence[Metric],
    bucket: PathBucket | None = None,
    seed: Seed | None = None,
) -> Optimizer:
    """A function which creates an optimizer for node.optimize should
    accept the following keyword arguments.

    Args:
        space: The node to optimize
        metrics: The metrics to optimize
        bucket: The bucket to store the results in
        seed: The seed to use for the optimization
    """
    ...

ask abstractmethod

ask(
    n: int | None = None,
) -> Trial[I] | Iterable[Trial[I]]

Ask the optimizer for a trial to evaluate.

PARAMETER	DESCRIPTION
n	The number of trials to ask for. If None, ask for a single trial. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
Trial[I] | Iterable[Trial[I]]	A config to sample.

Source code in src/amltk/optimization/optimizer.py

@abstractmethod
def ask(self, n: int | None = None) -> Trial[I] | Iterable[Trial[I]]:
    """Ask the optimizer for a trial to evaluate.

    Args:
        n: The number of trials to ask for. If `None`, ask for a single trial.

    Returns:
        A config to sample.
    """
    ...

create abstractmethod classmethod

create(
    *,
    space: Node,
    metrics: Metric | Sequence[Metric],
    bucket: str | Path | PathBucket | None = None,
    seed: Seed | None = None
) -> Self

Create this optimizer.

Note

Subclasses should override this with more specific configuration but these arguments should be all that's necessary to create the optimizer.

PARAMETER	DESCRIPTION
space	The space to optimize over. TYPE: Node
bucket	The bucket for where to store things related to the trial. TYPE: str | Path | PathBucket | None DEFAULT: None
metrics	The metrics to optimize. TYPE: Metric | Sequence[Metric]
seed	The seed to use for the optimizer. TYPE: Seed | None DEFAULT: None

RETURNS	DESCRIPTION
Self	The optimizer.

Source code in src/amltk/optimization/optimizer.py

@classmethod
@abstractmethod
def create(
    cls,
    *,
    space: Node,
    metrics: Metric | Sequence[Metric],
    bucket: str | Path | PathBucket | None = None,
    seed: Seed | None = None,
) -> Self:
    """Create this optimizer.

    !!! note

        Subclasses should override this with more specific configuration
        but these arguments should be all that's necessary to create the optimizer.

    Args:
        space: The space to optimize over.
        bucket: The bucket for where to store things related to the trial.
        metrics: The metrics to optimize.
        seed: The seed to use for the optimizer.

    Returns:
        The optimizer.
    """

preferred_parser classmethod

preferred_parser() -> (
    str
    | Callable[Concatenate[Node, ...], Any]
    | Callable[[Node], Any]
    | None
)

The preferred parser for this optimizer.

Note

Subclasses should override this as required.

Source code in src/amltk/optimization/optimizer.py

@classmethod
def preferred_parser(
    cls,
) -> str | Callable[Concatenate[Node, ...], Any] | Callable[[Node], Any] | None:
    """The preferred parser for this optimizer.

    !!! note

        Subclasses should override this as required.

    """
    return None

tell abstractmethod

tell(report: Report[I]) -> None

Tell the optimizer the report for an asked trial.

PARAMETER	DESCRIPTION
report	The report for a trial TYPE: Report[I]

Source code in src/amltk/optimization/optimizer.py

@abstractmethod
def tell(self, report: Trial.Report[I]) -> None:
    """Tell the optimizer the report for an asked trial.

    Args:
        report: The report for a trial
    """