Technology

Technology#

This page walks you through everything you need to run the lab notebooks on your own computer. If you prefer not to install anything, you can run every notebook in Google Colab using the badge at the top of each lab — no setup required.

Option A: Google Colab (no installation)#

Every lab notebook has a “Open in Colab” badge at the top. Click it, sign in with any Google account, and the notebook will open with all dependencies pre-installed. This is the easiest option and works on any device.

Note

Colab sessions are temporary. Save your work to your Google Drive or download the notebook before closing the tab.

Option B: Run locally on your computer#

Running locally gives you persistent files, faster execution, and the ability to work offline. Follow the three steps below.

Step 1 — Get Git and clone the repository#

Git is version-control software that lets you download (“clone”) the course repository and pull updates when new materials are posted.

Install Git#

Platform

What to do

macOS

Open Terminal and run git --version. If Git is not found, macOS will prompt you to install the Xcode Command Line Tools — click Install.

Windows

Download and run the installer from git-scm.com/download/win. Accept all defaults.

Linux

Run sudo apt install git (Ubuntu/Debian) or sudo dnf install git (Fedora).

Clone the repository#

Command line:

git clone https://github.com/uw-geophysics-edu/ess314.git
cd ess314

GitHub Desktop:

  1. Open GitHub Desktop.

  2. Go to File → Clone Repository → URL.

  3. Paste https://github.com/uw-geophysics-edu/ess314.git

  4. Choose a local folder and click Clone.

You now have a local copy of all lecture notes, notebooks, and lab files.

Pulling updates during the quarter#

New materials are posted regularly. Before each lab, update your local copy:

# Command line
cd ess314
git pull

In GitHub Desktop, click Fetch origin then Pull.

Tip

Never edit files that are part of the course materials directly; you will get merge conflicts when you pull updates. Instead, make a copy of any notebook you want to modify (e.g., rename Lab1-FirstnameLastname.ipynb with your actual name before filling it in).

Step 2 — Install the Python environment#

The labs use a specific set of Python packages (NumPy, SciPy, Matplotlib, ObsPy, etc.). Installing them into an isolated environment prevents conflicts with any other Python software on your computer.

We support two environment managers: Pixi (preferred — faster, handles everything automatically) and conda/miniconda (familiar to many scientists).

Option B-1: Pixi (preferred)#

Pixi is a fast, cross-platform package manager that reads the pixi.toml file already in the repository. Full installation docs: pixi.prefix.dev/latest/installation.

  1. Install Pixi.

    macOS / Linux — open a terminal and run:

    curl -fsSL https://pixi.sh/install.sh | sh

    If your system does not have curl, use wget instead:

    wget -qO- https://pixi.sh/install.sh | sh

    On macOS you can also use Homebrew:

    brew install pixi

    Windows — open PowerShell and run:

    winget install prefix-dev.pixi

    Or download the .msi installer from the Pixi GitHub releases page.

    After installation, close and reopen your terminal so that the pixi command is on your PATH.

  2. Install all dependencies — from inside the ess314 folder:

    pixi install

    This reads pixi.toml and installs all required packages into a local .pixi/ folder inside the repository. It does not affect your system Python.

  3. Register the Jupyter kernel (one-time, required so JupyterLab can find the environment):

    pixi run install-kernel

    This registers a kernel named ESS 314 (Python 3) that will appear in JupyterLab’s kernel selector.

  4. Launch JupyterLab:

    pixi run lab

    Your browser will open JupyterLab. Navigate to notebooks/, open a lab file, and select the ESS 314 (Python 3) kernel when prompted.

Option B-2: conda / miniconda#

If you already use conda, you can create the course environment from the included environment.yml file.

  1. Install Miniconda (if not already installed) — download from docs.conda.io/en/latest/miniconda.html and run the installer.

  2. Create the environment — from inside the ess314 folder:

    conda env create -f environment.yml

    This creates an environment named ess314.

  3. Activate the environment — you must do this every time you open a new terminal:

    conda activate ess314

  4. Launch JupyterLab:

    jupyter lab

Step 3 — Verify your installation#

Once JupyterLab is open, navigate to notebooks/ and open Lab1-Intro-Python.ipynb. Run the first few cells. If you see output from import numpy and import matplotlib without errors, your environment is working correctly.

Step 4 — Restarting the kernel#

A kernel is the Python process that runs your notebook cells. You will need to restart it in several situations:

When

What to do

A cell seems stuck and never finishes

Kernel → Interrupt Kernel, then re-run if needed

Variables are in an unexpected state after deleting/reordering cells

Kernel → Restart Kernel…

You install a new package and need it to be importable

Kernel → Restart Kernel…

Before submitting: verify the notebook runs top-to-bottom cleanly

Kernel → Restart Kernel and Run All Cells…

Important

Always do a Restart Kernel and Run All Cells before submitting a lab. This catches bugs where later cells depend on variables set in cells that were later deleted or reordered.

To restart in JupyterLab: click the Kernel menu at the top, or right-click in the notebook and choose from the kernel options. You can also click the ⟳ (restart) button in the toolbar.

Option C: Run notebooks in VS Code#

If you already use Visual Studio Code, you can open and run the lab notebooks directly inside the editor.

Note

VS Code does not include Jupyter support by default. The first time you open a .ipynb file, VS Code will display a prompt asking you to install the Jupyter extension — just click Install and follow the prompts. You will also be prompted to select a kernel; choose ESS 314 (Python 3) (registered in Step 2.3 above).

  1. Make sure you have completed Steps 1 and 2 above (clone + pixi install + pixi run install-kernel).

  2. Open VS Code, then open the ess314 folder: File → Open Folder…

  3. Open any notebook in notebooks/. VS Code will prompt you to install the Jupyter extension if it is not already present — click Install.

  4. In the top-right corner of the notebook, click Select Kernel and choose ESS 314 (Python 3).

  5. Run cells with Shift+Enter (run current cell and advance) or Ctrl/Cmd+Enter (run in place).

Kernel restart works the same way as in JupyterLab: use the ⟳ Restart button in the toolbar, or open the Command Palette (Ctrl/Cmd+Shift+P) and search for Jupyter: Restart Kernel.

Troubleshooting#

Symptom

Likely cause

Fix

git: command not found

Git not installed

Follow Step 1 above

pixi: command not found after install

Terminal not restarted

Close and reopen terminal

ModuleNotFoundError: No module named 'numpy'

Wrong environment active

Run pixi run lab (Pixi) or conda activate ess314 then jupyter lab (conda)

Kernel selector shows no ESS 314 kernel

install-kernel not run

Run pixi run install-kernel once, then restart JupyterLab

JupyterLab opens but kernel fails to start

Kernel not linked to environment

Run pixi run install-kernel (Pixi) or python -m ipykernel install --user --name ess314 (conda)

Cell output looks wrong after editing earlier cells

Stale kernel state

Kernel → Restart Kernel and Run All Cells

VS Code says “No kernel found”

install-kernel not run

Run pixi run install-kernel, then reload VS Code

VS Code does not open .ipynb files properly

Jupyter extension not installed

Click Install when VS Code prompts, or search for “Jupyter” in the Extensions panel

git pull gives “merge conflict”

You edited a tracked file

Copy your changes to a separate file, run git checkout -- <filename>, then pull

If you are stuck, post a screenshot of the error on the course Slack or bring your laptop to office hours.