{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Xgqk7eHswDpB"
      },
      "source": [
        "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/google/vizier/blob/main/docs/guides/user/running_vizier.ipynb)\n",
        "\n",
        "# Vizier Basics\n",
        "Below, we provide examples of how to:\n",
        "\n",
        "*   Define a problem statement and study configuration.\n",
        "*   Start a client.\n",
        "*   (Optionally) Connect the client to a server.\n",
        "*   Perform a typical tuning loop.\n",
        "*   Use other client APIs."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "4TsmlBbCu8Aw"
      },
      "source": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "O5RnMytPR8Aw"
      },
      "source": [
        "## Installation and reference imports"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "kSG8XlxLvCJO"
      },
      "outputs": [],
      "source": [
        "!pip install google-vizier[jax]"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "fzYr0bPYSHfQ"
      },
      "outputs": [],
      "source": [
        "from vizier import service\n",
        "from vizier.service import clients\n",
        "from vizier.service import pyvizier as vz\n",
        "from vizier.service import servers"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "qJ1kRiHaKOVt"
      },
      "source": [
        "## Setting up the problem statement\n",
        "Here we setup the problem statement, which contains information about the search space and the metrics to optimize."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "zX2G3_pcKYdG"
      },
      "outputs": [],
      "source": [
        "problem = vz.ProblemStatement()\n",
        "problem.search_space.root.add_float_param('x', 0.0, 1.0)\n",
        "problem.search_space.root.add_float_param('y', 0.0, 1.0)\n",
        "problem.metric_information.append(vz.MetricInformation(name='maximize_metric', goal=vz.ObjectiveMetricGoal.MAXIMIZE))\n",
        "\n",
        "\n",
        "def evaluate(x: float, y: float) -\u003e float:\n",
        "  return x**2 - y**2"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "GjDXKSIPKoex"
      },
      "source": [
        "## Setting up the study configuration\n",
        "The study configuration contains additional information, such as the algorithm to use and level of noise that we think the objective will have."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "NlSWnX1wKrjZ"
      },
      "outputs": [],
      "source": [
        "study_config = vz.StudyConfig.from_problem(problem)\n",
        "study_config.algorithm = 'DEFAULT'"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "5e2B91UvZYIM"
      },
      "source": [
        "## Setting up the client\n",
        "Starts a `study_client`, which will implicitly create a local Vizier Service which will be shared across other clients in the same Python process. Studies will then be stored locally in a SQL database file located at `service.VIZIER_DB_PATH`."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "X2AR4OmXX3in"
      },
      "outputs": [],
      "source": [
        "study_client = clients.Study.from_study_config(study_config, owner='owner', study_id='example_study_id')\n",
        "print('Local SQL database file located at: ', service.VIZIER_DB_PATH)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Vh3eNsrAdaMJ"
      },
      "source": [
        "## Obtaining suggestions\n",
        "Start requesting suggestions from the server, for evaluating objectives. Suggestions can be made sequentially (`count=1`) or in batches (`count\u003e1`)."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "BnFKc7FadkJV"
      },
      "outputs": [],
      "source": [
        "for i in range(10):\n",
        "  suggestions = study_client.suggest(count=1)\n",
        "  for suggestion in suggestions:\n",
        "    x = suggestion.parameters['x']\n",
        "    y = suggestion.parameters['y']\n",
        "    objective = evaluate(x, y)\n",
        "    print(f'Iteration {i}, suggestion ({x},{y}) led to objective value {objective}.')\n",
        "    final_measurement = vz.Measurement({'maximize_metric': objective})\n",
        "    suggestion.complete(final_measurement)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "V_pbH38ZfMVo"
      },
      "source": [
        "## Find optimal trial\n",
        "Find the best objective so far, with corresponding suggestion value. For multiobjective cases, there may be multiple outputs of `optimal_trials()`, all corresponding to a Pareto-optimal curve."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "vTKVZHVtfXJc"
      },
      "outputs": [],
      "source": [
        "for optimal_trial in study_client.optimal_trials():\n",
        "  optimal_trial = optimal_trial.materialize()\n",
        "  print(\"Optimal Trial Suggestion and Objective:\", optimal_trial.parameters,\n",
        "        optimal_trial.final_measurement)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "TPJD47ipbsQi"
      },
      "source": [
        "## Other client commands\n",
        "The `study_client` can also send other requests, such as the following:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "vcXrVLuMb201"
      },
      "outputs": [],
      "source": [
        "study_client.get_trial(1)  # Get the first trial.\n",
        "study_client.trials()  # Get all trials so far.\n",
        "\n",
        "# Obtain only the completed trials.\n",
        "trial_filter = vz.TrialFilter(status=[vz.TrialStatus.COMPLETED])\n",
        "study_client.trials(trial_filter=trial_filter)"
      ]
    }
  ],
  "metadata": {
    "colab": {
      "last_runtime": {
        "build_target": "//ads/thresholds/kumamon/colab:notebook",
        "kind": "shared"
      },
      "name": "Running Vizier.ipynb",
      "private_outputs": true,
      "provenance": [
        {
          "file_id": "/piper/depot/http://github.com/google/vizier/tree/main/vizier/docs/guides/user/running_vizier.ipynb",
          "timestamp": 1673247218127
        },
        {
          "file_id": "1q87rsDDUJLHci3o9Gv-sU0g7H3O3lAbU",
          "timestamp": 1659555396142
        }
      ]
    },
    "kernelspec": {
      "display_name": "Python 3",
      "name": "python3"
    },
    "language_info": {
      "name": "python"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}