# Technical Requirements and Setup

## The Short Version

The lowest-friction path is a current web browser plus **free Google Colab**. You do not need to buy software, own a GPU, or install Python to complete the supplied labs. The supplied labs are CPU-compatible; no dedicated GPU is required.

## Student Hardware

| Path | Minimum | Recommended | Cost |
|---|---|---|---|
| Colab | Current Chrome, Edge, Firefox, or Safari; stable broadband | 8 GB system memory and a keyboard suitable for coding | Free tier is sufficient |
| GitHub Codespaces | Current browser; stable broadband | 8 GB system memory | Uses the GitHub account's available Codespaces quota |
| Local installation | 64-bit computer, 8 GB RAM, 4 GB free disk | 16 GB RAM, 10 GB free disk | No course software fee |

Tablets can read course pages, but a laptop or desktop is strongly recommended for notebook editing and assignments.

## Supported Software Versions

- **Python 3.12** is the reference interpreter used by the course build and Codespaces configuration.
- **Jupyter Book 1.0.4.post1** is pinned in `requirements.txt`.
- **Git 2.40 or newer** is recommended only for local or Codespaces repository work.
- The complete private student repository includes `requirements.txt`; use that file as the authoritative package list rather than following a public course-source repository or installing packages individually.

Rendered readings, slides, and narration require only a browser.

## Google Colab Setup (Complete Private Student Repository)

1. In Populi, open the single private course repository assigned to you and confirm its name includes your GitHub username. You use this same repository for all eight modules.
2. In Colab, choose **File → Open notebook → GitHub**, authorize access to your private repositories, select your assigned repository, and open `modules/module-N/lab.ipynb` for the current Populi module.
3. Keep the default CPU runtime, choose **Runtime → Run all**, preserve the baseline evidence, make the required controlled change, and complete the exit-ticket fields.
4. Choose **File → Save a copy in GitHub**, select the same private repository and branch, keep the module path, and enter a descriptive commit message. If institutional settings prevent direct Colab-to-GitHub saving, download the notebook and replace the matching file through GitHub or Codespaces, creating a commit there. A Drive-only copy is not submitted work.
5. Open and complete `modules/module-N/exercise.ipynb` the same way, replace the prompts in `MEMO.md` with the required evidence memo, and complete `SUBMISSION.md` with the immutable commit URL and files-to-grade list. Upload `SUBMISSION.md` plus the requested memo or artifact in Populi.

If a GPU extension is assigned, choose **Runtime → Change runtime type → T4 GPU** when the free tier offers it. GPU availability is not guaranteed, so every required activity has a CPU path. **Colab Pro is optional and is not a course requirement.**

## GitHub Codespaces Setup (Complete Private Student Repository)

1. Open the private course repository assigned in Populi and select **Code → Codespaces → Create codespace on main**. Create it once and reuse it for the course.
2. Wait for dependency installation and the course Python kernel registration to finish.
3. For the current module, open `modules/module-N/lab.ipynb`, run and complete it, then complete `modules/module-N/exercise.ipynb`, `MEMO.md`, and `SUBMISSION.md`. Select the course Python kernel when prompted.
4. Save the graded module files, inspect the changes, commit with a descriptive message, and push to the private repository. Copy that immutable commit URL into `SUBMISSION.md`, then upload the completed record plus the requested memo or artifact in Populi. The record is an upload receipt and does not need to be part of the commit it identifies.

Use Codespaces when an activity needs multiple files, Git, tests, or a complete project. The Pages site is for reading; your student repository is your working environment.

## Optional Local Installation

```bash
git clone <your-assigned-student-repository-url>
cd <your-assigned-student-repository-folder>
python3.12 -m venv .venv
source .venv/bin/activate  # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
jupyter lab
```

In JupyterLab, open the current `modules/module-N/lab.ipynb` and `exercise.ipynb`. Verify the installation with `python --version`, `jupyter lab --version`, and `python -c "import numpy, matplotlib, torch"`.

## Slides and RISE

Students can read every slide deck as an ordinary web page from the course module map. Facilitators who want full-screen presentation mode should open `modules/module-N/slides.ipynb` in the configured Jupyter environment and start the RISE slideshow. The matching `narration.md` page is the prepared script for that deck.

## Troubleshooting Checklist

- Confirm that you opened the correct module and selected the course Python kernel.
- Restart the notebook runtime, then run cells from the top in order.
- Do not install a paid service to solve an environment error; use the CPU/Colab path or ask the instructor.
- When requesting help, include the module number, environment (Colab/Codespaces/local), exact error, and the cell where it occurred.