Trial

A trial is a configuration and it's associated data.

MetaData dataclass

MetaData(
    id: str,
    location: str,
    state: State,
    previous_trial_id: str | None,
    previous_trial_location: str | None,
    sampling_worker_id: str,
    time_sampled: float,
    evaluating_worker_id: str | None = None,
    evaluation_duration: float | None = None,
    time_submitted: float | None = None,
    time_started: float | None = None,
    time_end: float | None = None,
)

Metadata for a trial.

NotReportedYetError

Bases: NePSError

Raised when trying to access a report that has not been reported yet.

Report dataclass

Report(
    objective_to_minimize: float | list[float] | None,
    cost: float | None,
    learning_curve: list[float] | list[list[float]] | None,
    extra: Mapping[str, Any],
    err: Exception | None,
    tb: str | None,
    reported_as: Literal["success", "failed", "crashed"],
    evaluation_duration: float | None,
)

A failed report of the evaluation of a configuration.

State

Bases: str, Enum

The state of a trial.

Trial dataclass

Trial(
    State: ClassVar = State,
    Report: ClassVar = Report,
    MetaData: ClassVar = MetaData,
    NotReportedYetError: ClassVar = NotReportedYetError,
    config: Mapping[str, Any],
    metadata: MetaData,
    report: Report | None,
)

A trial is a configuration and it's associated data.

id property

id: str

Return the id of the trial.

new classmethod

new(
    *,
    trial_id: str,
    config: Mapping[str, Any],
    location: str,
    previous_trial: str | None,
    previous_trial_location: str | None,
    time_sampled: float,
    worker_id: int | str
) -> Self

Create a new trial object that was just sampled.

Source code in neps\state\trial.py

@classmethod
def new(
    cls,
    *,
    trial_id: str,
    config: Mapping[str, Any],
    location: str,
    previous_trial: str | None,
    previous_trial_location: str | None,
    time_sampled: float,
    worker_id: int | str,
) -> Self:
    """Create a new trial object that was just sampled."""
    worker_id = str(worker_id)
    return cls(
        config=config,
        metadata=MetaData(
            id=trial_id,
            state=State.PENDING,
            location=location,
            time_sampled=time_sampled,
            previous_trial_id=previous_trial,
            previous_trial_location=previous_trial_location,
            sampling_worker_id=worker_id,
        ),
        report=None,
    )

reset

reset() -> None

Reset the trial to a pending state.

Source code in neps\state\trial.py

def reset(self) -> None:
    """Reset the trial to a pending state."""
    self.metadata = MetaData(
        id=self.metadata.id,
        state=State.PENDING,
        location=self.metadata.location,
        previous_trial_id=self.metadata.previous_trial_id,
        previous_trial_location=self.metadata.previous_trial_location,
        time_sampled=self.metadata.time_sampled,
        sampling_worker_id=self.metadata.sampling_worker_id,
    )

set_complete

set_complete(
    *,
    report_as: Literal["success", "failed", "crashed"],
    time_end: float,
    objective_to_minimize: float | list[float] | None,
    cost: float | None,
    learning_curve: list[float] | list[list[float]] | None,
    err: Exception | None,
    tb: str | None,
    extra: dict[str, Any] | None,
    evaluation_duration: float | None
) -> Report

Set the report for the trial.

Source code in neps\state\trial.py

def set_complete(
    self,
    *,
    report_as: Literal["success", "failed", "crashed"],
    time_end: float,
    objective_to_minimize: float | list[float] | None,
    cost: float | None,
    learning_curve: list[float] | list[list[float]] | None,
    err: Exception | None,
    tb: str | None,
    extra: dict[str, Any] | None,
    evaluation_duration: float | None,
) -> Report:
    """Set the report for the trial."""
    if report_as == "success":
        self.metadata.state = State.SUCCESS
    elif report_as == "failed":
        self.metadata.state = State.FAILED
    elif report_as == "crashed":
        self.metadata.state = State.CRASHED
    else:
        raise ValueError(f"Invalid report_as: '{report_as}'")

    self.metadata.time_end = time_end
    self.metadata.evaluation_duration = evaluation_duration

    return Report(
        reported_as=report_as,
        evaluation_duration=evaluation_duration,
        objective_to_minimize=objective_to_minimize,
        cost=cost,
        learning_curve=learning_curve,
        extra=extra if extra is not None else {},
        err=err,
        tb=tb,
    )

set_corrupted

set_corrupted() -> None

Set the trial as corrupted.

Source code in neps\state\trial.py

def set_corrupted(self) -> None:
    """Set the trial as corrupted."""
    self.metadata.state = State.CORRUPTED

set_evaluating

set_evaluating(
    *, time_started: float, worker_id: int | str
) -> None

Set the trial as in progress.

Source code in neps\state\trial.py

def set_evaluating(self, *, time_started: float, worker_id: int | str) -> None:
    """Set the trial as in progress."""
    self.metadata.time_started = time_started
    self.metadata.evaluating_worker_id = str(worker_id)
    self.metadata.state = State.EVALUATING

set_submitted

set_submitted(*, time_submitted: float) -> None

Set the trial as submitted.

Source code in neps\state\trial.py

def set_submitted(self, *, time_submitted: float) -> None:
    """Set the trial as submitted."""
    self.metadata.time_submitted = time_submitted
    self.metadata.state = State.SUBMITTED