jupyter_codelab.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6cdf730e-9fe7-4d78-ab10-dcd6a26bfefc",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Copyright 2021 DeepMind Technologies Limited\n",
    "#\n",
    "# Licensed under the Apache License, Version 2.0 (the \"License\");\n",
    "# you may not use this file except in compliance with the License.\n",
    "# You may obtain a copy of the License at\n",
    "#\n",
    "#      http://www.apache.org/licenses/LICENSE-2.0\n",
    "#\n",
    "# Unless required by applicable law or agreed to in writing, software\n",
    "# distributed under the License is distributed on an \"AS IS\" BASIS,\n",
    "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n",
    "# See the License for the specific language governing permissions and\n",
    "# limitations under the License."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "081405f1-aa42-4569-9332-21add7ae04b5",
   "metadata": {
    "tags": []
   },
   "source": [
    "# XManager codelab notebook\n",
    "\n",
    "This notebook will take you through running an XManager experiment on Google Cloud Platform (GCP).\n",
    "\n",
    "A stand-alone Jupyter Notebook can be created via GCP's [Vertex AI Notebooks](https://console.cloud.google.com/vertex-ai/notebooks/list/instances)\n",
    "\n",
    "JupyterLab can be installed on your machine following [Jupyter's installation](https://jupyter.org/install)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "05f0dec3-860d-4847-bc30-1f99c2e063e1",
   "metadata": {},
   "source": [
    "## Install any prerequisites\n",
    "\n",
    "1. Create a [GCP project](https://console.cloud.google.com/) if one does not already exist.\n",
    "\n",
    "2. Install [Docker](https://docs.docker.com/engine/install/) if it is not already installed."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "632a09e9-ae00-4e3a-abfe-ac3d8a18a223",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Download and install XManager"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5d1749a4-aff0-43c5-93ab-7cc2e0e03f5b",
   "metadata": {},
   "outputs": [],
   "source": [
    "!git clone https://github.com/deepmind/xmanager.git ~/xmanager\n",
    "!pip install ~/xmanager"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aa3628d5-e006-44de-87b8-b87f73ed21c2",
   "metadata": {},
   "source": [
    "## Set default GCP values"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a1d7e16b-d84e-42fd-b899-443f1a577f5b",
   "metadata": {},
   "source": [
    "The following gets the GCP project."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e0c477f2-d762-469d-bbe0-001f44d8f8df",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from google import auth\n",
    "credentials = auth.default()[0]\n",
    "project = auth.default()[1]\n",
    "print('GCP Project:', project)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "37a7d47a-133c-4597-84de-b53b8ac8fccd",
   "metadata": {},
   "source": [
    "Use `gcloud auth application-default login` if the above command results in an error or the project is incorrect.\n",
    "\n",
    "XManager requires a Google Cloud Storage Bucket. [Create one](https://cloud.google.com/storage/docs/creating-buckets) if one does not already exist and enter it in the box below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "14f3e08a-de24-4d93-a656-74e1f424a385",
   "metadata": {
    "jupyter": {
     "source_hidden": true
    },
    "tags": []
   },
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "5207147fbf66460481c585674abf8dc5",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "Text(value='', description='GOOGLE_CLOUD_BUCKET_NAME:', layout=Layout(width='50%'), style=DescriptionStyle(des…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "from IPython.display import display\n",
    "import ipywidgets\n",
    "import os\n",
    "\n",
    "def bucket_changed(change):\n",
    "    os.environ['GOOGLE_CLOUD_BUCKET_NAME'] = change.new\n",
    "\n",
    "GOOGLE_CLOUD_BUCKET_NAME = ipywidgets.Text(\n",
    "    description='GOOGLE_CLOUD_BUCKET_NAME:',\n",
    "    style={'description_width': 'initial'},\n",
    "    layout=ipywidgets.Layout(width='50%'),\n",
    ")\n",
    "GOOGLE_CLOUD_BUCKET_NAME.observe(bucket_changed, names='value')\n",
    "\n",
    "display(GOOGLE_CLOUD_BUCKET_NAME)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5139b368-9183-442e-b421-760ec268741a",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from xmanager import xm\n",
    "from xmanager import xm_local\n",
    "# This code block sets FLAGS to use default values to avoid an absl.flags.UnparsedFlagAccessError.\n",
    "# Normally XManager flags are set via the command-line with `xmanager train.py -- --key=value`\n",
    "from absl import flags\n",
    "flags.FLAGS([''])\n",
    "flags.FLAGS.xm_wrap_late_bindings = True"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8ea2b7f4-a1bf-444f-a0cd-35d144ccfd3b",
   "metadata": {},
   "source": [
    "## Launching an experiment"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9cf5e68c-3c6b-4fc7-9749-088b53ced1bc",
   "metadata": {},
   "source": [
    "This code block imports dependencies used in later steps."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "63f6a625-2e56-4091-9e3e-06efe4f8e697",
   "metadata": {},
   "outputs": [],
   "source": [
    "import itertools\n",
    "import os\n",
    "\n",
    "from xmanager import xm\n",
    "from xmanager import xm_local"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "93855a16-e0b1-4614-9ec4-9b493bbe8317",
   "metadata": {
    "tags": []
   },
   "source": [
    "An experiment can be broken down into 5 steps:\n",
    "\n",
    "1. Creating the experiment.\n",
    "2. Defining the executable specification.\n",
    "3. Defining the execution environment.\n",
    "4. Creating the jobs and experiment units.\n",
    "5. Defining the hyperparameters."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ca2f5e67-8c5d-49cd-89e9-3165abc09ec6",
   "metadata": {},
   "source": [
    "### Creating the experiment\n",
    "\n",
    "Experiments are the core of XManager. An experiment typically involves running a computation (e.g., training a model in JAX or TensorFlow) in different hyperparameter configurations. It can have associated metadata (name, description, notes, tags, links, etc.). Experiments are made up of various experiment units, including work units which do the computation(s) in question and auxiliary units which perform other functions like TensorBoard.\n",
    "\n",
    "Give the experiment a name. The `create_experiment` method will also create a unique integer id for the experiment and save this experiment to a database."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a2562c02-0dde-48c2-8f08-1cba3a64e33a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# XManager runs asynchronously. Because the Jupyter REPL is also asynchronous, we must run coroutines with the `async` keyword.\n",
    "# https://blog.jupyter.org/ipython-7-0-async-repl-a35ce050f7f7\n",
    "async with xm_local.create_experiment(experiment_title='my-first-experiment') as experiment:\n",
    "    print(f'Local Experiment created with experiment_id={experiment.experiment_id}')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "916a97c3-fdf7-422f-8b73-22b4a623af4c",
   "metadata": {
    "tags": []
   },
   "source": [
    "### Defining the executable specification\n",
    "\n",
    "Define the job that will run in the experiment. A `PythonContainer` is an example of a executable specificaiton. This executable specification tells XManager to package everything inside the `PythonContainer.path` as a container and use `PythonContainer.entrypoint` as the main module. Because we cloned XManager to `~/xmanager` in an early step, we can use one of the examples, `~/xmanager/examples/cifar10_torch` as the path.\n",
    "\n",
    "We also need to declare where the executable should be staged. This step will upload the executable specification to the correct storage option that is best suited for the execution environment. For example, if the execution environment is Vertex AI, the executable must be stored in Google Container Registry. The `Vertex.Spec()` specification will upload the specification to Google Container Registry, where it will be accessible by Vertex AI."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5d03e3a4-b48d-4a7b-9ad5-5b0f08646ed5",
   "metadata": {},
   "outputs": [],
   "source": [
    "[executable] = experiment.package([\n",
    "    xm.python_container(\n",
    "        executor_spec=xm_local.Vertex.Spec(),\n",
    "        path=os.path.expanduser('~/xmanager/examples/cifar10_torch'),\n",
    "        entrypoint=xm.ModuleName('cifar10'),\n",
    "    )\n",
    "])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1d6249a6-8596-4a70-886a-18738396cea6",
   "metadata": {},
   "source": [
    "### Defining the execution environment\n",
    "\n",
    "Declare where the job will run and what compute requirements are necessary to run one job. To run on AI Vertex, we must use the `xm_local.Vertex` executor. Each job should use 1 NVidia T4 GPU, so we must pass in a `xm.JobRequirements` to the executor."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cb7ecc92-dc01-4513-9aec-105295ad484e",
   "metadata": {},
   "outputs": [],
   "source": [
    "executor = xm_local.Vertex(xm.JobRequirements(T4=1))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "57b6d9c5-28b0-4074-91ed-645e72908329",
   "metadata": {},
   "source": [
    "### Launching the jobs\n",
    "\n",
    "Finally, we can create an experiment and jobs to the experiment. A **job** is an unit of execution. A job contains an executable representing \"what to run\" and an executor reprenting \"how to run it\". Jobs can be reused.\n",
    "\n",
    "To add a single job to the experiment, create a `xm.Job` object that combine the executable, compute requirements, and custom arguments hyperparameters, and the job to the experiment."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "27ccf7ba-d19e-4b84-8eaa-634b13ddd7e6",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "async with xm_local.create_experiment(experiment_title='cifar10') as experiment:\n",
    "    await experiment.add(xm.Job(\n",
    "        executable=executable,\n",
    "        executor=executor,\n",
    "        args={'batch_size': 64, 'learning_rate': 0.01},\n",
    "    ))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5a9e0a7c-88be-4cf3-83f7-fe740e3b0114",
   "metadata": {},
   "source": [
    "#### Job Groups\n",
    "\n",
    "A **job group** is a collection of jobs. Job groups can be added to experiments in the same way. The jobs in a job groups should be connected in some way. Some examples include: a client and server, multiple workers in a distributed experiment, a tpu session and a coordinator, a trainer and a evaluator, etc."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "71b64486-a02c-4ad9-bb57-2efd35db36fd",
   "metadata": {},
   "outputs": [],
   "source": [
    "async with xm_local.create_experiment(experiment_title='cifar10') as experiment:\n",
    "    await experiment.add(xm.JobGroup(\n",
    "        client=xm.Job(\n",
    "            executable=executable,\n",
    "            executor=executor,\n",
    "        ),\n",
    "        server=xm.Job(\n",
    "            executable=executable,\n",
    "            executor=executor,\n",
    "        ),\n",
    "    ))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1a8cf716-3c84-423e-88d3-e6c3e7322c41",
   "metadata": {},
   "source": [
    "#### Defining the hyperparameters\n",
    "\n",
    "In research, it is often required to run the experimental setup multiple times with different hyperparameter values. This is called **hyperparameter optimization**. The simplest form of hyperparameter optimization is called *grid search* or *parameter sweep*, which is an exhaustive search through all possible Cartesian products of hyperparameter values. Grid search trials can be constructed using `itertools`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "73ad717a-ae2b-4437-98d4-ed2d7e1b7e68",
   "metadata": {},
   "outputs": [],
   "source": [
    "inputs = {\n",
    "    'batch_size': [64, 128],\n",
    "    'learning_rate': [0.01, 0.001],\n",
    "}\n",
    "hyperparameters = list(dict(zip(inputs, x)) for x in itertools.product(*inputs.values()))\n",
    "\n",
    "from pprint import pprint\n",
    "pprint(hyperparameters)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "54cbbfa7-8856-49af-a77f-147ed4749bdc",
   "metadata": {},
   "source": [
    "To perform the grid search, loop over all the hyperparameters, passing a different hyperparameter configuration to the `args` parameter of each job. Add each job to the experiment."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "24767b61-2861-4cc5-9cdf-fd6673f34893",
   "metadata": {},
   "outputs": [],
   "source": [
    "async with xm_local.create_experiment(experiment_title='cifar10') as experiment:\n",
    "    for hparams in trials:\n",
    "        experiment.add(xm.Job(\n",
    "            executable=executable,\n",
    "            executor=executor,\n",
    "            args=hparams,\n",
    "        ))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b86633d3-5def-407e-883c-828c9498f71a",
   "metadata": {},
   "source": [
    "#### Experiment Units\n",
    "\n",
    "The return result of `experiment.add` is an awaitable experiment unit.\n",
    "\n",
    "An **experiment unit** is created by XManager for every instance the experiment launches a set launched jobs. Jobs inside an experiment unit must be created together or should be destroyed together.\n",
    "\n",
    "The common type of experiment unit is the work unit. A **work unit** contains the main task of training in an ML experiment, and they are part of the hyperparameter sweep. A helpful way of thinking of work units is that each work unit represents a trial. Just as an experiment can trial different hyperparameter sets, an XManager experiment can create a work unit for each trial. Work units are enumerated and assigned a `work_unit_id` starting from 0.\n",
    "\n",
    "There are other experiment unit types which represent differnt roles. For example, an **auxiliary unit** represents a job that runs alongside all the trials such as a Tensorboard or an hyperparameter optimizer job."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "79a036a7-2c88-4a1c-8eee-199e6b42568e",
   "metadata": {},
   "source": [
    "#### Job Generator\n",
    "\n",
    "It's possible to modify the args of a job based on the attributes of the work unit. A good example of wanting to do this is when you want to create a pass a different log directory argument to each work unit. Another example is if you need to adjust the args with the correct DNS names based on the `work_unit_id`.\n",
    "\n",
    "A job generator allows you modify the arguments of a job before they are added to the work unit."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0cfaa17c-4687-4896-9590-8739b56e144a",
   "metadata": {},
   "outputs": [],
   "source": [
    "async generate(work_unit, hparams):\n",
    "    print(work_unit.work_unit_id, hparams)\n",
    "    # hparams.update({'log_dir', f'/tmp/{work_unit.work_unit_id}'})\n",
    "    work_unit.add(xm.Job(\n",
    "        executable=executable,\n",
    "        executor=executor,\n",
    "        args=hparams,\n",
    "    ))\n",
    "\n",
    "async with xm_local.create_experiment(experiment_title='cifar10') as experiment:\n",
    "    for hparams in trials:\n",
    "        work_unit = await experiment.add(generate, hparams)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2ad78311-0bfb-48bf-b049-641aa1a2a721",
   "metadata": {},
   "source": [
    "### Tracking job status\n",
    "\n",
    "You can list all of your previous experiments."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "84a0f4a9-b98d-4077-b785-259f7b8352a2",
   "metadata": {},
   "outputs": [],
   "source": [
    "[e.experiment_id for e in xm_local.list_experiments()]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5625b8e4-81ea-405a-baa7-064f18cea593",
   "metadata": {},
   "source": [
    "Some execution environments allow you to track the status of jobs in an experiment. Vertex AI is one of the execution environments that supports job-tracking."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "994824a7-946b-4070-b2a6-58a444e1d213",
   "metadata": {},
   "outputs": [],
   "source": [
    "# TODO: Use experiment.work_units instead of private member.\n",
    "for i, unit in enumerate(experiment._experiment_units):\n",
    "    print(f'[{i}] Completed: {unit.get_status().is_completed}, Failed: {unit.get_status().is_failed}')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c76908f8-ada4-4f57-8bf4-7407256948f2",
   "metadata": {},
   "source": [
    "## End to end"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "76651cc3-41b0-4eea-9370-2a7882c495c3",
   "metadata": {},
   "source": [
    "Combining everything above into a single code-block, the launch script looks like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c3aa0b2e-ab14-4952-8b42-a1245167864a",
   "metadata": {},
   "outputs": [],
   "source": [
    "async with xm_local.create_experiment(experiment_title='cifar10') as experiment:\n",
    "    [executable] = experiment.package([\n",
    "        xm.python_container(\n",
    "            executor_spec=xm_local.Vertex.Spec(),\n",
    "            path=os.path.expanduser('~/xmanager/examples/cifar10_torch'),\n",
    "            entrypoint=xm.ModuleName('cifar10'),\n",
    "        )\n",
    "    ])\n",
    "\n",
    "    batch_sizes = [64, 128]\n",
    "    learning_rates = [0.01, 0.001]\n",
    "    trials = list(\n",
    "        dict([('batch_size', bs), ('learning_rate', lr)])\n",
    "        for (bs, lr) in itertools.product(batch_sizes, learning_rates)\n",
    "    )\n",
    "    for hyperparameters in trials:\n",
    "        experiment.add(xm.Job(\n",
    "            executable=executable,\n",
    "            executor=xm_local.Vertex(requirements=xm.JobRequirements(T4=1)),\n",
    "            args=hyperparameters,\n",
    "        ))"
   ]
  }
 ],
 "metadata": {
  "environment": {
   "kernel": "python3",
   "name": "common-cpu.m94",
   "type": "gcloud",
   "uri": "gcr.io/deeplearning-platform-release/base-cpu:m94"
  },
  "kernelspec": {
   "display_name": "Python3.9 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}