PCPT Teaser

Unit 1: Get Started¶

Overview and Learning Objectives

In this first unit, we briefly introduce how to use the PCPT notebooks and start interacting with them using the Jupyter notebook framework. If a static view of the PCPT notebooks is enough for you, the exported HTML versions can be used right away without any installation. Suppose you want to execute, modify, and experiment with the Python code contained in the notebooks' code cells. In that case, you need to install Python, some additional Python packages, and the Jupyter software underlying the web-based interactive computational environment for creating notebook documents. In the following, we discuss the required software components and explain the steps necessary to install them.

At the end of this unit, you should be able to run the PCPT notebooks locally on your computer. Since the steps for installing PCPT notebooks are typical for many software projects, we strongly recommend that students carry out these steps themselves while getting familiar with the software concepts involved. As an alternative for locally executing the notebooks, you may also use web-based services such as Google colab or binder. We refer to the PCPT notebooks' GitHub repository for further details.

In [1]:
# --- Custom utilities (Unit 1) ---
from libpcpt.unit01 import (
    print_zip_url
)

Downloading PCPT Notebooks¶

The latest version of the PCPT notebooks is available on GitHub, a platform for collaborative software development and version control based on Git. To use Git, download and install the latest version for your operating system. For guidance on setup and usage, see resources such as the GitHub Quickstart Guide and the Git Tutorial. You can download (or clone) the PCPT GitHub repository by running:

git clone https://github.com/meinardmueller/PCPT.git.

Alternatively, you can download a ZIP-compressed archive containing the PCPT notebooks along with all required data.
After downloading, extract (decompress) the archive and store it on your local computer.
You can find the archive at:

In [2]:
print_zip_url()

----------------------------------------------------------------------------------
| https://github.com/meinardmueller/PCPT/releases/download/v0.4.4/PCPT_0.4.4.zip |
----------------------------------------------------------------------------------

Note that downloading the ZIP archive is recommended if you only want to explore or run the notebooks locally without using Git. Cloning the repository is more suitable if you plan to update your local copy regularly or contribute to the project.

Finally, note that the repository can also be run in interactive online Jupyter environments such as Google Colab or Binder without any additional installation steps. See the README.md file of the GitHub repository for further information.

Package Management System and Environment Files¶

Conda is an open source package manager that helps finding and installing packages. It runs on Windows, macOS, and Linux. The Conda package and environment manager is included in Anaconda and its slim version Miniconda, which are free and open-source distributions of Python. Miniconda can make installing Python quick and easy even for new users. Download and install Miniconda for your platform from the following website:

The following steps and commands may be useful to get started:

  • Install Anaconda or Miniconda (slim version of Anaconda).
  • On Windows: Start with opening the terminal Anaconda Prompt.
    On Linux/MacOS: You can use a usual shell.
  • Verify that conda is installed: conda --version
  • Update conda (it is recommended to always keep conda updated to the latest version): conda update conda
  • Default environment is named base
  • Create a new environment and install the desired packages. For example:
    conda create --name PCPT_test python=3.12 pip numpy scipy matplotlib jupyter This command creates a new Python environment named PCPT_test that includes the packages numpy, scipy, matplotlib, and jupyter.
  • List of all environments: conda env list
  • Activate environment: conda activate PCPT
  • Python version in current environment: python --version
  • List packages contained in environment: conda list
  • Remove environment: conda env remove --name PCPT_test

To simplify the installation of Python and Jupyter, we recommend creating an environment from an environment file, typically named environment.yml. This file specifies all required packages and their exact versions, ensuring a consistent and reproducible setup across different systems and users.

  • We already provide such a file for the PCPT notebooks. To create the environment named PCPT, you need to call
    conda env create -f environment.yml

  • To update the environment, you can call
    conda env update -f environment.yml

  • Sometimes it may be easier to first remove the environment and than install it again:
    conda env remove -n PCPT
    conda env create -f environment.yml

  • Once the environment has been installed, you need to activate it using:
    conda activate PCPT

The current PCPT environment can be listed as follows:

In [3]:
import os

fn = os.path.join('environment.yml')
with open(fn, 'r', encoding='utf-8') as stream:
    env = stream.read()

print(env)

name: PCPT

channels:
  - pytorch
  - defaults
  - conda-forge

dependencies:
  - python >=3.12.0, <4.0.0
  - pip >=25.2, <26.0
  - numpy >=2.3.0, <3.0.0
  - scipy >=1.16.0, <2.0.0
  - scikit-learn >=1.7.0, <2.0.0
  - matplotlib >=3.10.0, <4.0.0
  - jupyter >=1.1.0, <2.0.0
  - pytorch::pytorch >=2.5.0, <3.0.0
  - pytorch::torchvision >=0.20.0, <1.0.0
  - pytorch::torchaudio >=2.5.0, <3.0.0
  - pip:
    - nbconvert[webpdf] >=7.16.0, <8.0.0
    - nbstripout >=0.8.0, <1.0.0
    - torchinfo >=1.8.0, <2.0.0

We provide an environment file that includes all packages required to work with the PCPT notebooks. Open the Anaconda Prompt on Windows or your default shell on Linux/macOS. Then navigate to the directory containing the environment.yml file and create the environment with the following command:

conda env create -f environment.yml

Working with Jupyter Notebooks¶

Jupyter is a non-profit, open-source project that evolved from the IPython project. It aims to develop open-source software, open standards, and services for interactive computing across dozens of programming languages.
The Jupyter notebook framework allows users to combine code, text, formulas, images, and plots within a single interactive document. Here are some helpful links and comments:

One option to explore and run Jupyter notebooks is to manually start a Jupyter server. This can be done easily using the jupyter package, which is included in the PCPT environment. First, activate the environment by running the following command:

conda activate PCPT

Then change to the directory containing the PCPT notebooks and start the Jupyter server using the following command:

jupyter notebook

This command opens a browser window displaying the folder structure of the PCPT notebooks. You can open the overview notebook by selecting the file PCPT.ipynb. Alternatively, you can directly open any individual PCPT notebook by selecting a file in a subdirectory with the .ipynb extension. Within a Jupyter session, make sure to follow the IPYNB links so that all code cells remain executable. Also note that you can only access files located in the directory from which the Jupyter server was launched, or in any of its subdirectories.

A more modern interface is provided by JupyterLab, which offers a multi-tab workspace instead of displaying one notebook per browser tab. This interface provides the best compatibility with the notebooks, ensuring correct rendering of mathematical formulas and plots. However, by default, it offers only basic code-editing features and lacks advanced tools such as code completion. To launch this interface directly, run the following command:

jupyter lab

Another way to work with Jupyter notebooks is to use an Integrated Development Environment (IDE) such as Visual Studio Code or PyCharm. Quick-start guides for these tools are available on their respective websites (VS Code, PyCharm). These IDEs automatically run a Jupyter server in the background and provide advanced programming features such as code completion, syntax checking, version control, and debugging.

While IDEs offer a powerful and flexible development environment, they may not always render mathematical formulas correctly.
Therefore, for running the PCPT course, we recommend using the Jupyter server for optimal notebook compatibility and visual output.

Keyboard Shortcuts¶

Keyboard shortcuts can greatly speed up your work in Jupyter notebooks.
Jupyter operates in two primary modes:

  • Edit mode: Used to type and edit the content of a cell. Enter this mode by clicking inside a cell or pressing Enter.
  • Command mode: Used to perform notebook-level actions with keyboard shortcuts. Enter this mode by pressing Esc or clicking outside a cell’s editor area. The active cell is highlighted.

In command mode, the following shortcuts are particularly useful:

  • Esc: Switch to command mode
  • Ctrl + Shift + H: Open the help menu with available shortcuts
  • Ctrl + Shift + C: Activate Command Palette
  • Ctrl + Enter: Run selected cell and do not advance
  • Shift + Enter: Run selected cell and select the next one
  • A: Insert a new cell above the current cell
  • B: Insert a new cell below the current cell
  • Ctrl + Shift + -: split the cell at the current cursor position
  • Y: change the selected cell to a code cell
  • M: change the selected cell to a Markdown cell
  • D + D (press D twice): delete the current cell
  • Z: Undo the last cell deletion
  • Shift + Z: Redo cell operation
  • Shift + J: Select cells downwards
    Shift + K: Select cells upwards
    Once multiple cells are selected, you can delete, copy, cut, paste, or run them as a batch.
  • Shift + M: merge selected cells
  • X: Cut selected cells
  • C: Copy selected cells
  • V: Paste cells below

Tip: Press Ctrl + Shift + H in command mode to display the full list of available shortcuts.

HTML and PDF Export¶

Jupyter notebooks can be exported in a variety of different formats, including .pdf, .tex, and .html. The export can either be done via the Jupyter menu (File→Save and Export Notebook As) or via the command line. The following commands show the HTML and PDF export on the example of the notebook Unit 2.

  • Clear output: nbstripout PCPT_02_classes.ipynb
  • Run notebook: jupyter nbconvert --to notebook --execute --inplace PCPT_02_classes.ipynb
  • HTML export: jupyter nbconvert --to html PCPT_02_classes.ipynb
  • PDF export: jupyter nbconvert --to webpdf PCPT_02_classes.ipynb

To run and export all PCPT notebooks at once, we provide a Python script tools/run_and_export_notebooks.py which can be used as follows:

python tools/run_and_export_notebooks.py

Further Notes¶

Here is a list of useful commands, which may be helpful when working with Conda and Jupyter notebooks:

Updating, removing, and creating Python environments:

conda update conda
conda env list
conda env create -f environment.yml
conda env update -f environment.yml
conda env remove -n PCPT
conda activate PCPT

Starting a Jupyter Server:

jupyter notebook
jupyter lab

Using Git:

git status
git pull
git add -A (or git add --all)
git add *.tex
git commit -m "message"
git push
git clone https://github.com/meinardmueller/PCPT.git
PCPT License