🖥️ Lecture slides — Session 02 (Fri Oct 2)
This page is Homework 1. It walks you through setting up the tools you will use all quarter: pixi for environments, git and GitHub for version control, and JupyterLab for notebooks. Each step ends in a state you can verify, so you always know whether it worked before moving on. Budget one to two hours; ask for help early if a step fails.
By the end you will have: pixi and git installed, a GitHub account, your personal course repository MLGEO2026_UWNETID (replace UWNETID with your UW NetID), the course book running locally, and a commit pushed to your own repository.
Step 1 — Install pixi¶
macOS / Linux / WSL2, in a terminal:
curl -fsSL https://pixi.sh/install.sh | shOn macOS with Homebrew, brew install pixi works too. After installing, close and reopen the terminal so your shell picks up the new PATH.
Verify:
pixi --versionSuccess looks like: a version number prints, e.g. pixi 0.48.0. If the command is not found, restart the terminal; if it is still not found, the installer prints the line to add to your shell profile — add it and restart again.
Step 2 — Install git and create a GitHub account¶
Check whether git is already installed:
git --versionIf not: on macOS, running that command triggers the Xcode Command Line Tools installer (accept it); on Ubuntu/WSL2, sudo apt install git.
Then:
Create an account at github.com and set up two-factor authentication (see 1.5).
Tell git who you are, using the same user name and email as the GitHub account:
git config --global user.name "superseismo" git config --global user.email "superseismo@uw.edu"Install the GitHub CLI and authenticate:
gh auth loginAccept the defaults (GitHub.com, HTTPS, login with a web browser) and follow the browser prompts.
Verify:
git --version
gh auth statusSuccess looks like: git prints a version 2.40 or newer, and gh auth status reports Logged in to github.com with your user name.
Step 3 — Create your course repository¶
Create your personal course repository, named MLGEO2026_UWNETID (your NetID in capitals, e.g. MLGEO2026_SUPERSEISMO). This repository holds your homeworks and project work for the quarter. Create it once, with one command:
gh repo create MLGEO2026_UWNETID --public --add-readme --license mit --cloneThis creates the repository on GitHub with a README and an MIT license, and clones it into a folder of the same name. Run it from the directory where you keep course work — outside cloud-synced folders such as Dropbox or Google Drive.
(No terminal? The browser equivalent is in 1.5; then clone it.)
Verify: open https://github.com/YOURUSERNAME/MLGEO2026_UWNETID in a browser.
Success looks like: the repository page loads and shows a README and a LICENSE file, and ls MLGEO2026_UWNETID on your computer shows the same files.
Step 4 — Clone the course book and install its environment¶
Clone the course repository and let pixi build the environment from the lockfile:
git clone https://github.com/geo-smart/mlgeo-book.git
cd mlgeo-book
pixi installThe first pixi install downloads a few gigabytes of packages; expect several minutes on a fast connection. Then launch JupyterLab from inside the environment:
pixi run jupyter labVerify: JupyterLab opens in your browser (or prints a http://localhost:8888/lab?token=... URL to open).
Success looks like: the JupyterLab interface loads and its file browser shows the book/ folder. Stop it later with Ctrl-C in the terminal.
Step 5 — Smoke test: run a notebook¶
A smoke test is a short, fast check that the basic machinery runs from start to finish: the packages import, a small calculation with a known answer returns that answer, and output appears. The name comes from hardware testing: switch the new device on and check that nothing starts smoking. A smoke test cannot show that a scientific result is right. It shows that the setup does not fail at once, in seconds instead of an hour into a real run. Run it first on any new machine and after every environment change. It is also the first thing another person runs to find out whether your repository works on their computer. This step smoke-tests the course book’s environment. Step 6 adds a smoke test to your own repository.
In JupyterLab, open any Chapter 1 notebook — for example book/Chapter1-GettingStarted/1.7_get_geodetic_gnss.ipynb — and run the first few cells (Shift-Enter).
Success looks like: the import cells complete without ModuleNotFoundError, and the first data or plot cell produces output. If imports fail, you are probably running a kernel outside the pixi environment: check that you launched JupyterLab with pixi run jupyter lab from the mlgeo-book directory.
Step 6 — Push a change to your own repository¶
Close the loop by pushing a commit to MLGEO2026_UWNETID. In a terminal, go to your repository from step 3, edit README.md (add a title line, your name, and one sentence on what you want out of this course), then:
git add README.md
git commit -m "Introduce myself in the README"
git pushWhile you are at it, copy the environment files from the course book into your repository, so your own work is reproducible from day one:
cp ../mlgeo-book/pixi.toml ../mlgeo-book/pixi.lock .
pixi remove --pypi mlgeo-synth(Adjust the ../mlgeo-book/ path if your folders live elsewhere.) The second command removes one line that only makes sense inside the book: it installs the book’s own mlgeo_synth package from the book’s folder, which does not exist in your repository. Without the removal, every pixi run in your repository fails with “does not appear to be a Python project”. Every other package keeps the exact version pinned in the book’s lockfile.
Now give your repository its own smoke test. Save this as smoke_test.py in the repository:
"""Smoke test: check that the course environment runs before doing real work."""
import platform
import numpy as np
import pandas as pd
import xarray as xr
# A calculation with a known answer: a line rising 2.5 mm/yr must give slope 2.5.
t = np.arange(0.0, 10.0, 0.1)
slope = np.polyfit(t, 2.5 * t + 1.0, 1)[0]
assert abs(slope - 2.5) < 1e-9, f"expected slope 2.5, got {slope}"
print(f"Python {platform.python_version()} on {platform.system()} {platform.machine()}")
print(f"numpy {np.__version__}, pandas {pd.__version__}, xarray {xr.__version__}")
print("smoke test passed")Register it as a pixi task and run it:
pixi task add smoke "python smoke_test.py"
pixi run smokeSuccess looks like: the last line printed is smoke test passed. Add a How to run section to README.md that names the command (pixi run smoke) and records the operating system and machine type from the first printed line, for example Tested on Darwin arm64. Then commit and push:
git add pixi.toml pixi.lock smoke_test.py README.md
git commit -m "Add course environment and smoke test"
git pushVerify: reload the repository page on GitHub.
Success looks like: your README edit, the two pixi files, and smoke_test.py are visible on GitHub, and the commits appear under Commits with your user name attached. In class on Monday Oct 5, a classmate will clone your repository and run pixi run smoke with only your README as a guide.
Done — and what to submit¶
You now have a working workbench: a pinned environment that runs the book’s notebooks, and a repository that records your work and states how to check that it runs. Submit the URL of your MLGEO2026_UWNETID repository on Canvas; the commit history is the evidence of completion.
Two follow-ups: