{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "513957d3",
   "metadata": {},
   "source": [
    "# Introduction to Ray: Developer\n",
    "\n",
    "## Course Welcome and Overview\n",
    "\n",
    "This course provides a comprehensive introduction to Ray with hands-on examples and practical use cases, designed to help developers quickly master distributed computing and scale their Python applications from development to production.\n",
    "\n",
    "## 📋 Notebook Compute Requirements Legend\n",
    "\n",
    "Throughout this course, you'll see these symbols in each notebook to indicate the recommended compute environment:\n",
    "\n",
    "| Symbol | Meaning | Description |\n",
    "|--------|---------|-------------|\n",
    "| 💻 | **Launch Locally** | Whether the notebook can run efficiently on your laptop/local machine |\n",
    "| 🚀 | **Launch on Cloud** | Benefits from GPU acceleration, cloud recommended |\n",
    "\n",
    "**Note**: For 🚀 notebooks, we recommend using [Anyscale](http://console.anyscale.com/register) with a Ray cluster that has GPUs.\n",
    "\n",
    "## Why Ray?\n",
    "\n",
    "Today's ML workloads are increasingly compute-intensive. As convenient as they are, single-node development environments such as your laptop cannot scale to meet these demands.\n",
    "\n",
    "Ray is a unified way to scale Python and AI applications from a laptop to a cluster.\n",
    "\n",
    "With Ray, you can seamlessly scale the same code from a laptop to a cluster. Ray is designed to be general-purpose, meaning that it can performantly run any kind of workload. If your application is written in Python, you can scale it with Ray, no other infrastructure required.\n",
    "\n",
    "## Setting Up a Local Ray server using Jupyter Notebook\n",
    "\n",
    "### Prerequisites\n",
    "\n",
    "This guide helps you set up a local Jupyter Notebook environment using **Conda** and install **Ray** for parallel and distributed computing.\n",
    "\n",
    "---\n",
    "\n",
    "### ✅ 1. Install Conda\n",
    "\n",
    "If you don't already have Conda, you can install **Miniforge** or **Miniconda** on macOS with Apple Silicon (ARM-based M1/M2/M3 chips):\n",
    "\n",
    "### 🧩 Miniforge Installation (It depends on your OS. In this case, we use ARM Macs)\n",
    "\n",
    "Open your terminal and run:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "99eadf0e",
   "metadata": {},
   "outputs": [],
   "source": [
    "curl -LO https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh\n",
    "bash Miniforge3-MacOSX-arm64.sh"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c976b5ee",
   "metadata": {},
   "source": [
    "Follow the prompts to accept the license, choose the install location, and initialize Miniforge.\n",
    "\n",
    "Then restart your terminal or run:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ac09e581",
   "metadata": {},
   "outputs": [],
   "source": [
    "source ~/.zprofile  # or ~/.bash_profile if you're using bash"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "464f95e4",
   "metadata": {},
   "source": [
    "Verify installation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "36cf36b9",
   "metadata": {},
   "outputs": [],
   "source": [
    "conda --version"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "69eb97fa",
   "metadata": {},
   "source": [
    "Alternatively, download from:\n",
    "- Miniforge: https://github.com/conda-forge/miniforge#miniforge3\n",
    "- Miniconda (ARM builds available): https://docs.conda.io/en/latest/miniconda.html\n",
    "\n",
    "---\n",
    "\n",
    "### 🛠️ 2. Create a New Conda Environment"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6c5183c0",
   "metadata": {},
   "outputs": [],
   "source": [
    "conda create -n ray-jupyter python=3.11 -y"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a687ee34",
   "metadata": {},
   "source": [
    "> Ray supports Python 3.7 to 3.11 (Python 3.12 is not supported as of Ray 2.20).\n",
    "\n",
    "---\n",
    "\n",
    "### ▶️ 3. Activate the Environment"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cb160d3b",
   "metadata": {},
   "outputs": [],
   "source": [
    "conda activate ray-jupyter"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "85178e05",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "### 📦 4. Install UV and Dependencies\n",
    "\n",
    "First, install UV:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "397c2c30",
   "metadata": {},
   "outputs": [],
   "source": [
    "curl -LsSf https://astral.sh/uv/install.sh | sh"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cc59d60b",
   "metadata": {
    "lines_to_next_cell": 0
   },
   "source": [
    "Install the dependencies using the lock file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b4a1683b",
   "metadata": {},
   "outputs": [],
   "source": [
    "uv pip install -r requirements.lock"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fe5ce4b6",
   "metadata": {},
   "source": [
    "This will install all dependencies with their exact versions as specified in the lock file, ensuring reproducible builds across different environments.\n",
    "\n",
    "### Managing Dependencies\n",
    "\n",
    "When you need to add new dependencies:\n",
    "\n",
    "1. Add the new package to `requirements.txt`\n",
    "2. Generate a new lock file:\n",
    "   ```bash\n",
    "   uv pip compile requirements.txt -o requirements.lock\n",
    "   ```\n",
    "3. Install using the updated lock file:\n",
    "   ```bash\n",
    "   uv pip install -r requirements.lock\n",
    "   ```\n",
    "\n",
    "This workflow ensures that all dependencies are properly tracked and versions are locked for reproducibility.\n",
    "\n",
    "---\n",
    "\n",
    "### 🖥️ 5. (Optional but Recommended) Add Your Conda Environment to Jupyter\n",
    "\n",
    "To use your `ray-jupyter` environment as a kernel in Jupyter Notebook, run:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2181118d",
   "metadata": {},
   "outputs": [],
   "source": [
    "pip install ipykernel\n",
    "python -m ipykernel install --user --name ray-jupyter --display-name \"Python (ray-jupyter)\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "74544f07",
   "metadata": {},
   "source": [
    "This will make your environment available as a selectable kernel in Jupyter.\n",
    "\n",
    "---\n",
    "\n",
    "### 🚀 6. Launch Jupyter Notebook"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f6e25e3d",
   "metadata": {},
   "outputs": [],
   "source": [
    "jupyter notebook"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "323255f2",
   "metadata": {},
   "source": [
    "This will open a browser window for you to create and manage notebooks.\n",
    "\n",
    "---\n",
    "\n",
    "### ✅ 7. Verify Ray Installation with a Simple Example\n",
    "\n",
    "After launching Jupyter Notebook and selecting your `ray-jupyter` kernel, create a new notebook and run the following code to verify Ray is working:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "7aac6903",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "2025-12-10 22:57:33,031\tINFO worker.py:1951 -- Started a local Ray instance.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Ray is working!\n"
     ]
    }
   ],
   "source": [
    "%%python\n",
    "import ray\n",
    "ray.init()\n",
    "\n",
    "@ray.remote\n",
    "def hello_world():\n",
    "    return \"Ray is working!\"\n",
    "\n",
    "result = ray.get(hello_world.remote())\n",
    "print(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "941e1483",
   "metadata": {},
   "source": [
    "You should see the output:\n",
    "\n",
    "```\n",
    "2025-06-10 10:41:31,774\tINFO worker.py:1879 -- Started a local Ray instance. View the dashboard at http://127.0.0.1:8265 \n",
    "\n",
    "Ray is working!\n",
    "```\n",
    "\n",
    "If you see this message, Ray is set up correctly! You can now view the local Ray Dashboard at: http://127.0.0.1:8265\n",
    "\n",
    "---\n",
    "\n",
    "### 🧹 8. Shut Down and Clean Up\n",
    "\n",
    "To stop the Jupyter Notebook server:\n",
    "\n",
    "- Press `Ctrl+C` in the terminal\n",
    "\n",
    "To deactivate the environment:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7152b7b9",
   "metadata": {},
   "outputs": [],
   "source": [
    "conda deactivate"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "49d0b853",
   "metadata": {},
   "source": [
    "To remove the environment completely:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2b700651",
   "metadata": {},
   "outputs": [],
   "source": [
    "conda remove --name ray-jupyter --all"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "521bc35d",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "You're now ready to start developing Ray applications in a local Jupyter Notebook environment!\n"
   ]
  }
 ],
 "metadata": {
  "jupytext": {
   "cell_metadata_filter": "-all",
   "main_language": "bash",
   "notebook_metadata_filter": "-all"
  },
  "kernelspec": {
   "display_name": "speedy_utils",
   "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.13.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
