setup.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Course set-up"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "__author__ = \"Christopher Potts\"\n",
    "__version__ = \"CS224u, Stanford, Spring 2021\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook covers the steps you'll need to take to get set up for [CS224u](http://web.stanford.edu/class/cs224u/)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Contents\n",
    "\n",
    "1. [Anaconda](#Anaconda)\n",
    "1. [The course Github repository](#The-course-Github-repository)\n",
    "1. [Main data distribution](#Main-data-distribution)\n",
    "1. [Additional installations](#Additional-installations)\n",
    "  1. [Installing the package requirements](#Installing-the-package-requirements)\n",
    "  1. [PyTorch](#PyTorch)\n",
    "  1. [Hugging Face transformers](#Hugging-Face-transformers)\n",
    "1. [Jupyter notebooks](#Jupyter-notebooks)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Anaconda\n",
    "\n",
    "We recommend installing [the free Anaconda Python distribution](https://www.anaconda.com/products/individual), which includes IPython, Numpy, Scipy, matplotlib, scikit-learn, NLTK, and many other useful packages. This is not required, but it's an easy way to get all these packages installed. Unless you're very comfortable with Python package management and like installing things, this is the option for you!\n",
    "\n",
    "Please be sure that you download the __Python 3__ version, which currently installs Python 3.8. __Our codebase is not compatible with Python 2__.\n",
    "\n",
    "One you have Anaconda installed, create a virtual environment for the course. In a terminal, run\n",
    "\n",
    "```conda create -n nlu python=3.8 anaconda```\n",
    "\n",
    "to create an environment called `nlu`.\n",
    "\n",
    "Then, to enter the environment, run\n",
    "\n",
    "```conda activate nlu```\n",
    "\n",
    "To leave it, you can just close the window, or run\n",
    "\n",
    "```conda deactivate```\n",
    "\n",
    "If your version of Anaconda is older than version 4.4 (see `conda --version`), then replace `conda` with `source` in the above (and consider upgrading your Anaconda!).\n",
    "\n",
    "[This page](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) has more detailed instructions on managing virtual environments with Anaconda."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The course Github repository\n",
    "\n",
    "The core materials for the course are on Github:\n",
    "\n",
    "https://github.com/cgpotts/cs224u\n",
    "\n",
    "We'll be working in this repository a lot, and it will receive updates throughout the quarter, as we add new materials and correct bugs.\n",
    "\n",
    "If you're new to git and Github, we recommend using [Github's Desktop Apps](https://desktop.github.com). Then you just have to clone our repository and sync your local copy with the official one when there are updates. \n",
    "\n",
    "If you are comfortable with git in the command line, you can type the following command to clone the course's Github repo:\n",
    "\n",
    "```git clone https://github.com/cgpotts/cs224u```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Main data distribution\n",
    "\n",
    "The datasets needed to run the course notebooks and complete the assignments are in the following zip archive:\n",
    "\n",
    "http://web.stanford.edu/class/cs224u/data/data.tgz\n",
    "\n",
    "We recommend that you download it, unzip it, and place it in the same directory as your local copy of this Github repository. If you decide to put it somewhere else, you'll need to adjust the paths given in the \"Set-up\" sections of essentially all the notebooks.\n",
    "\n",
    "We recommend you to check the `md5` checksum of the `data.tgz` afte the download. The current version (as of 8/22/2021), the checksum is `a447b2a81835707ad7882f8f881af79a`. If you see the different checksum, then ask this to the teaching staff."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Additional installations\n",
    "\n",
    "Be sure to do these additional installations from [inside your virtual environment](#Anaconda) for the course! Before you proceed from here, perhaps run\n",
    "\n",
    "```conda activate nlu```\n",
    "\n",
    "to make sure you are in that environment."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Installing the package requirements\n",
    "\n",
    "If you are running Anaconda, then most of the requirements are already met – you'll just need to add PyTorch and the Hugging Face `transformers` library, both discussed below. \n",
    "\n",
    "People who aren't using Anaconda should edit `requirements.txt` so that it installs all the prerequisites that come with Anaconda and then run\n",
    "\n",
    "```pip install -r requirements.txt```\n",
    "\n",
    "from inside the course virtual environment to install the core additional packages. __The above command will not install anything unless you edit it.__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### PyTorch\n",
    "\n",
    "The PyTorch library has special installation instructions depending on your computing environment. For Anaconda users, we recommend\n",
    "\n",
    "```conda install pytorch=1.8.0 torchvision -c pytorch```\n",
    "\n",
    "For non-Anaconda users, or if you have a [CUDA-enabled GPU](https://developer.nvidia.com/cuda-gpus), we recommend following the instructions posted here:\n",
    "\n",
    "https://pytorch.org/get-started/locally/\n",
    "\n",
    "For this course, you should be running at least version `1.7.0` and preferably `1.8.0`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'1.8.0'"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import torch\n",
    "\n",
    "torch.__version__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you decide to use a different version of PyTorch, you might encounter problems. The library is progressing fast and we cannot guarantee backward compatibility for versions before `1.7.0`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Hugging Face transformers"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will be making extensive use of the [Hugging Face](https://huggingface.co/) `transformers` library. To install it, run the following from inside your virtual environment:\n",
    "\n",
    "```pip install transformers==4.3.3```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And then verify that you are running the correct version here:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'4.3.3'"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import transformers\n",
    "\n",
    "transformers.__version__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This library is changing even faster that PyTorch, so it is crucial that you run this version for our coursework."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Jupyter notebooks\n",
    "\n",
    "The majority of the materials for this course are Jupyter notebooks, which allow you to work in a browser, mixing code and description. It's a powerful form of [literate programming](https://en.wikipedia.org/wiki/Literate_programming), and increasingly a standard for open science.\n",
    "\n",
    "To start a notebook server, navigate to the directory where you want to work and run\n",
    "\n",
    "```jupyter notebook --port 5656```\n",
    "\n",
    "The port specification is optional. \n",
    "\n",
    "This should launch a browser that takes you to a view of the directory you're in. You can then open notebooks for working and create new notebooks.\n",
    "\n",
    "A major advantage of working with Anaconda is that you can switch virtual environments from inside a notebook, via the __Kernel__ menu. If this isn't an option for you, then run this command while inside your virtual environment:\n",
    "\n",
    "```python -m ipykernel install --user --name nlu --display-name \"nlu\"```\n",
    "\n",
    "(If you named your environment something other than `nlu`, then change the `--name` and `--display-name` values.) \n",
    "\n",
    "[Additional discussion of Jupyter and kernels.](https://stackoverflow.com/questions/39604271/conda-environments-not-showing-up-in-jupyter-notebook)\n",
    "\n",
    "For some tips on getting started with notebooks, see [our Jupyter tutorial](tutorial_jupyter_notebooks.ipynb)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.8.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}