getml.hyperopt

def list_hyperopts() -> List[str]:
    """Lists all hyperparameter optimization objects present in the Engine.

    Note that this function only lists hyperopts which are part of the
    current project. See [`set_project`][getml.engine.set_project] for
    changing projects.

    To subsequently load one of them, use
    [`load_hyperopt`][getml.hyperopt.load_hyperopt.load_hyperopt].

    Returns:
        list containing the names of all hyperopts.

    """

    cmd: Dict[str, Any] = {}
    cmd["type_"] = "list_hyperopts"
    cmd["name_"] = ""

    with comm.send_and_get_socket(cmd) as sock:
        msg = comm.recv_string(sock)
        if msg != "Success!":
            comm.handle_engine_exception(msg)
        json_str = comm.recv_string(sock)

    return json.loads(json_str)["names"]

def tune_feature_learners(
    pipeline: Pipeline,
    container: Container,
    train: str = "train",
    validation: str = "validation",
    n_iter: int = 0,
    score: Optional[str] = None,
    num_threads: int = 0,
) -> Pipeline:
    """
    A high-level interface for optimizing the feature learners of a
    [`Pipeline`][getml.pipeline.Pipeline].

    Efficiently optimizes the hyperparameters for the set of feature learners
    (from [`feature_learning`][getml.feature_learning]) of a given pipeline by breaking each
    feature learner's hyperparameter space down into carefully curated
    subspaces: `hyperopt_tuning_subspaces` and optimizing the hyperparameters for
    each subspace in a sequential multi-step process.  For further details about
    the actual recipes behind the tuning routines refer
    to tuning routines: `hyperopt_tuning`.

    Args:
        pipeline:
            Base pipeline used to derive all models fitted and scored
            during the hyperparameter optimization. It defines the data
            schema and any hyperparameters that are not optimized.

        container:
            The data container used for the hyperparameter tuning.

        train:
            The name of the subset in 'container' used for training.

        validation:
            The name of the subset in 'container' used for validation.

        n_iter:
            The number of iterations.

        score:
            The score to optimize. Must be from
            [`metrics`][getml.pipeline.metrics].

        num_threads:
            The number of parallel threads to use. If set to 0,
            the number of threads will be inferred.

    Returns:
        Pipeline containing tuned versions of the feature learners.

    ??? example
        We assume that you have already set up your
        [`Pipeline`][getml.Pipeline] and
        [`Container`][getml.data.Container].

        ```python
        tuned_pipeline = getml.hyperopt.tune_predictors(
            pipeline=base_pipeline,
            container=container)
        ```
    """

    if not isinstance(pipeline, getml.pipeline.Pipeline):
        raise TypeError("'pipeline' must be a pipeline!")

    pipeline._validate()

    if not score:
        score = _infer_score(pipeline)

    tuned_feature_learners = []

    for feature_learner in pipeline.feature_learners:
        tuned_pipeline = _tune_feature_learner(
            feature_learner=feature_learner,
            pipeline=pipeline,
            container=container,
            train=train,
            validation=validation,
            n_iter=n_iter,
            score=score,
            num_threads=num_threads,
        )

        assert len(tuned_pipeline.feature_learners) == 1, (
            "Expected exactly one feature learner, got "
            + str(len(tuned_pipeline.feature_learners))
        )

        tuned_feature_learners.append(tuned_pipeline.feature_learners[0])

    return _make_final_pipeline(
        pipeline,
        tuned_feature_learners,
        copy.deepcopy(pipeline.predictors),
        container,
        train,
        validation,
    )

def tune_predictors(
    pipeline: Pipeline,
    container: Container,
    train: str = "train",
    validation: str = "validation",
    n_iter: int = 0,
    score: Optional[str] = None,
    num_threads: int = 0,
) -> Pipeline:
    """
    A high-level interface for optimizing the predictors of a
    [`Pipeline`][getml.Pipeline].

    Efficiently optimizes the hyperparameters for the set of predictors (from
    [`getml.predictors`][getml.predictors]) of a given pipeline by breaking each
    predictor's
    hyperparameter space down into carefully curated
    subspaces: `hyperopt_tuning_subspaces` and optimizing the hyperparameters for
    each subspace in a sequential multi-step process.  For further details about
    the actual recipes behind the tuning routines refer to
    tuning routines: `hyperopt_tuning`.

    Args:
        pipeline:
            Base pipeline used to derive all models fitted and scored
            during the hyperparameter optimization. It defines the data
            schema and any hyperparameters that are not optimized.

        container:
            The data container used for the hyperparameter tuning.

        train:
            The name of the subset in 'container' used for training.

        validation:
            The name of the subset in 'container' used for validation.

        n_iter:
            The number of iterations.

        score:
            The score to optimize. Must be from
            [`metrics`][getml.pipeline.metrics].

        num_threads:
            The number of parallel threads to use. If set to 0,
            the number of threads will be inferred.

    ??? example
        We assume that you have already set up your
        [`Pipeline`][getml.Pipeline] and
        [`Container`][getml.data.Container].

        ```python
        tuned_pipeline = getml.hyperopt.tune_predictors(
            pipeline=base_pipeline,
            container=container)
        ```

    Returns:
        Pipeline containing tuned predictors.

    """

    if not isinstance(pipeline, getml.pipeline.Pipeline):
        raise TypeError("'pipeline' must be a pipeline!")

    pipeline._validate()

    if not score:
        score = _infer_score(pipeline)

    tuned_predictors = []

    for predictor in pipeline.predictors:
        tuned_pipeline = _tune_predictor(
            predictor=predictor,
            pipeline=pipeline,
            container=container,
            train=train,
            validation=validation,
            n_iter=n_iter,
            score=score,
            num_threads=num_threads,
        )

        assert len(tuned_pipeline.predictors) == 1, (
            "Expected exactly one predictor, got " + str(len(tuned_pipeline.predictors))
        )

        tuned_predictors.append(tuned_pipeline.predictors[0])

    return _make_final_pipeline(
        pipeline,
        copy.deepcopy(pipeline.feature_learners),
        tuned_predictors,
        container,
        train,
        validation,
    )

def exists(name: str) -> bool:
    """Determines whether a hyperopt exists.

    Args:
        name: The name of the hyperopt.

    Returns:
        A boolean indicating whether a hyperopt named 'name' exists.
    """
    if not isinstance(name, str):
        raise TypeError("'name' must be of type str")

    return name in list_hyperopts()

def delete(name: str) -> None:
    """
    If a hyperopt named 'name' exists, it is deleted.

    Args:
        name: The name of the hyperopt.
    """

    if not exists(name):
        return

    cmd: Dict[str, Any] = {}

    cmd["type_"] = "Hyperopt.delete"
    cmd["name_"] = name

    with comm.send_and_get_socket(cmd) as sock:
        msg = comm.recv_string(sock)
        if msg != "Success!":
            comm.handle_engine_exception(msg)