6 Setting up your learning / tinkering computer environment
6.1 Lecture Overview
6.1.1 Before You Begin
To complete this lecture’s activities, you will need:
- A GitHub account: Create one at github.com if you don’t already have one
- Administrator privileges: Ensure you have the ability to install software on your computer
- A text editor or IDE: VS Code, Sublime Text, or any editor you’re comfortable with (optional but recommended)
6.1.2 Project Milestones
This lecture establishes the foundational development environment for the entire course. By completing this module, you will have achieved the first major project milestone: a fully configured development environment that includes:
- Python and uv for package management
- Jupyter Notebooks for interactive development and assignment submissions
- Git/GitHub for version control and collaboration
- SSH for connecting to the Home Assistant server in the final project
6.2 Setting Up Python and uv
6.2.1 Why Python and uv?
Why Python?
Python has become the de facto language for machine learning and data science applications. For this course, we’ve chosen Python because:
- It’s the primary language used in the ML/AI ecosystem, with libraries like scikit-learn, TensorFlow, and PyTorch
- It allows for rapid prototyping and experimentation - crucial for the iterative nature of building energy management solutions
- It has excellent support for scientific computing (NumPy, SciPy, pandas) and visualization (matplotlib, plotly)
- It integrates well with building automation platforms like Home Assistant
Why uv?
For package management, we’re using uv instead of traditional tools like pip or conda. uv is a modern Python package and project manager that offers several advantages:
- Speed: Much faster than pip or conda for installing packages
- Modern dependency resolution: Better handling of complex dependency trees
- Project isolation: Creates lightweight virtual environments without the overhead of conda
- All-in-one tool: Manages both Python installation and packages in a single tool
- Simplicity: Straightforward commands that are easy to learn and use
Interface Comparison:
| Task | pip | conda | uv |
|---|---|---|---|
| Install package | pip install numpy |
conda install numpy |
uv pip install numpy |
| Create project | Manual venv setup | conda create -n myenv |
uv init myproject |
| Manage dependencies | requirements.txt |
environment.yml |
pyproject.toml |
| Install Python | Separate download | Bundled with Anaconda | uv python install 3.11 |
Functional Differences:
- pip: Package installer only; requires separate Python installation and venv management
- conda: Full environment manager with its own package repository; heavier and slower but handles non-Python dependencies
- uv: Fast, all-in-one tool that manages Python versions, packages, and projects; uses standard PyPI repository; lightweight and modern
For this course’s focus on ML applications for building energy management, uv provides the right balance of simplicity, speed, and functionality.
6.2.2 Installing uv
The installation methods below download and execute scripts directly from the internet. While this is the official installation method recommended by the uv developers, you should be aware that running scripts this way carries inherent security risks. Only proceed if you trust the source (Astral, the developers of uv). For production environments, consider reviewing the installation script first or using alternative installation methods.
uv can be installed using the official installer script. Follow the instructions for your operating system:
macOS
Open Terminal and run:
curl -LsSf https://astral.sh/uv/install.sh | shAfter installation, restart your terminal or run:
source $HOME/.cargo/envWindows
Open PowerShell and run:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"After installation, restart PowerShell to ensure the uv command is available.
Verify Installation
Regardless of your platform, verify that uv is installed correctly by running:
uv --versionYou should see output showing the installed version of uv (e.g., uv 0.x.x).
6.2.3 Installing Python
One of uv’s key features is that it can install and manage Python versions for you. For this course, we’ll use Python 3.11.
Check Available Python Versions
First, you can see which Python versions are available:
uv python listThis will show you all available Python versions that uv can install.
Install Python 3.11
To install Python 3.11, run:
uv python install 3.11uv will download and install Python 3.11 for you. This works identically on both macOS and Windows.
Verify Python Installation
Check that Python was installed successfully:
uv python listYou should see Python 3.11 listed with an indicator showing it’s installed.
Managing Multiple Python Versions
uv can manage multiple Python versions simultaneously. You don’t need to worry about conflicts - when you create a project (which we’ll do next), you’ll specify which Python version that project should use. This allows you to work on different projects with different Python versions without any issues.
6.2.4 Learn-by-Doing Activity 1: Python and uv Setup
Objective: Create a simple test project to verify your Python and uv installation is working correctly.
Steps:
Create a new directory for your test project:
mkdir uv-test cd uv-testInitialize a new uv project with Python 3.11:
uv init --python 3.11This creates a basic project structure. Now add a simple Python package:
uv add numpyCreate a simple test script. Create a file called
test.pywith the following content:import numpy as np print(f"NumPy version: {np.__version__}") print("Installation successful!")Run your script using uv:
uv run test.py
Expected Result: You should see output showing the NumPy version and the success message. If you see this, congratulations! Your Python and uv setup is working correctly.
6.3 Working with Jupyter Notebooks
6.3.1 What are Jupyter Notebooks?
Jupyter Notebooks are interactive documents that combine live code, visualizations, and explanatory text in a single interface. They run in your web browser and connect to a Python kernel that executes your code. This architecture allows you to write code in “cells,” run them individually, see results immediately, and document your work with markdown cells - all in one place.
For this course, Jupyter Notebooks are ideal because they allow you to prototype machine learning solutions iteratively, visualize building energy data alongside your analysis, and create self-contained documents that combine your code, results, and explanations. All course assignments will be submitted as Jupyter Notebook files (.ipynb), making it easy for you to show both your work and your reasoning.
6.3.2 Creating and Managing Projects with uv
Creating a New Project
To create a new Python project with uv:
uv init myproject --python 3.11
cd myprojectThis creates a project directory with the following structure: - pyproject.toml: Project configuration and dependencies - .python-version: Specifies which Python version to use - README.md: Project documentation
Managing Dependencies
Add packages to your project:
uv add package-nameRemove packages:
uv remove package-nameView your dependency tree:
uv treeSyncing Dependencies
When working with an existing project (for example, one you downloaded from a colleague or from GitHub), you’ll need to install all the project’s dependencies. The uv sync command reads the pyproject.toml file and installs everything the project needs:
cd existing-project
uv syncThis is particularly useful when:
- You’ve just cloned the course repository and want to work with the example notebooks
- You’re starting work on a project on a new computer
- Another team member has added new dependencies to the project
The sync command ensures your local environment matches exactly what the project specifies, so the code will run the same way for everyone.
Running Python Code
Execute Python scripts within your project’s environment:
uv run script.pyThis automatically uses the correct Python version and has access to all installed dependencies.
6.3.3 Setting Up Jupyter Kernels
What is a Jupyter Kernel?
A Jupyter kernel is the computational engine that executes the code in your notebooks. When you run a code cell, Jupyter sends that code to the kernel, which executes it in a specific Python environment and returns the results. Different kernels can use different Python versions and have access to different installed packages.
Two Approaches to Using Jupyter with uv
There are two ways to set up Jupyter to work with your uv projects:
Approach 1: Simple (Using uv run)
The quickest way to start Jupyter with access to your project’s environment:
uv run --with jupyter jupyter lab--with flag
The --with flag tells uv to temporarily install a package (in this case, jupyter) for this command only, without adding it to your project’s dependencies. This is useful for tools you need to run but don’t want as permanent project dependencies.
This starts Jupyter Lab with access to all your project’s packages. Use this approach when you want to quickly work on a single project.
Approach 2: Kernel Registration (Recommended for Course Work)
For more robust setup, especially when working with multiple projects, register your project as a Jupyter kernel:
First, add
ipykernelto your project as a development dependency:uv add --dev ipykernelNoteAbout the--devflagThe
--devflag marks a package as a development dependency - something needed for working on the project (like testing tools, linters, or Jupyter kernels) but not required to run the final code. Development dependencies are tracked separately inpyproject.tomland won’t be installed by users who just want to use your code.Register your project as a kernel:
uv run ipython kernel install --user --name=myprojectStart Jupyter Lab:
uv run --with jupyter jupyter labWhen creating a new notebook, select your project kernel from the kernel dropdown menu in the top-right corner.
Benefits of Kernel Registration
With a registered kernel, you can:
- Work with multiple projects simultaneously in Jupyter
- Easily switch between different project environments
- Add packages directly from within notebooks using
!uv add package-name - Ensure consistent environments across different machines
For this course, we recommend using Approach 2 (kernel registration) so you can easily work with both the course materials and your own projects.
6.3.4 Running Jupyter Notebooks
Launching Jupyter Lab
Once you have your project set up with a registered kernel, start Jupyter Lab:
uv run --with jupyter jupyter labThis opens Jupyter Lab in your default web browser. Jupyter Lab is a modern, feature-rich interface for working with notebooks.
Jupyter Lab vs Jupyter Notebook
There are two interfaces available:
- Jupyter Lab (recommended): Modern interface with multiple panels, file browser, and advanced features. Launch with
jupyter lab - Jupyter Notebook: Classic, simpler interface focused on single notebooks. Launch with
jupyter notebook
Both work identically for editing notebooks - the difference is in the surrounding interface. Feel free to use whichever you prefer, but we recommend Jupyter Lab for its improved usability.
Getting the Sample Notebook
To practice using Jupyter, you’ll work through the sample notebook for this lecture. You can download it directly from the course website or find it in the course repository at:
lectures/Lecture-3/lecture-3-sample-notebook.ipynb
If you don’t have the course repository yet (we’ll cover git cloning shortly), you can download just this file from the course website and place it in your project directory.
Working with Notebooks
Once you open the sample notebook in Jupyter Lab:
- Select your project kernel from the kernel dropdown in the top-right corner
- Follow the instructions in the notebook - it will guide you through creating code cells, running them, and working with Python packages
- The sample notebook covers the basics of the Jupyter interface, so you can learn by doing
6.3.5 Learn-by-Doing Activity 2: Your First Jupyter Notebook
In-Class Exercise: Work through the lecture-3-sample-notebook.ipynb file available in the course repository. This hands-on activity will guide you through:
- Creating and running Python code cells
- Using Jupyter magic commands (like
%matplotlib inline) - Creating simple visualizations with matplotlib
- Running shell commands from within Jupyter using
! - Saving your notebook
Clone the course repository and open this notebook to follow along during the lecture.
6.4 Git and GitHub
6.4.1 Why Version Control?
Version control systems track changes to files over time, allowing you to recall specific versions later. Git, the most widely used version control system, is essential for modern software development and collaborative research.
Problems Version Control Solves:
- “Final_FINAL_v3_actually_final.docx”: No more confusing file names - version control tracks all changes with meaningful descriptions
- Lost work: Accidentally deleted something important? Version control lets you restore any previous version
- Collaboration conflicts: Multiple people editing the same file? Git helps merge changes intelligently
- Understanding history: See who changed what, when, and why - crucial for understanding code decisions
- Experimentation safety: Try new approaches without fear - you can always revert to a working version
For This Course:
You’ll use Git and GitHub in two ways:
Accessing course materials: The course repository (https://git.inferlab.org/websites/12-770) contains all lecture notebooks, examples, and resources. You’ll clone this repository to get updates throughout the semester.
Final project submission: You’ll create your own repository for your final project, making it easy to track your progress, collaborate with team members, and share your work with instructors.
Version control isn’t just a technical tool - it’s a practice that makes collaborative work possible and individual work more reliable.
6.4.2 Installing Git
Git is the version control system we’ll use throughout the course. Installation varies by operating system.
macOS
Git often comes pre-installed on macOS as part of the Xcode Command Line Tools. First, check if it’s already installed:
git --versionIf you see a version number, you’re all set! If not, macOS will prompt you to install the Command Line Tools. Alternatively, you can install git via Homebrew:
brew install gitWindows
Download and install Git for Windows from git-scm.com/download/win. The installer will guide you through the setup with recommended defaults.
While native Git for Windows works well for this course, you may want to consider installing WSL2 (Windows Subsystem for Linux) for your final project work. WSL2 provides a full Linux environment on Windows, which can be helpful for working with tools like Docker and SSH. It’s not required now, but worth exploring if you’re interested in a more Unix-like development environment. Learn more at docs.microsoft.com/windows/wsl.
Verify Installation
Regardless of your platform, verify that git is installed correctly:
git --versionYou should see output showing the installed version of git (e.g., git version 2.x.x).
6.4.3 Git Basics
Git tracks changes to your files through a three-stage workflow. Understanding these core concepts will help you use git effectively.
Core Concepts:
- Repository (repo): A directory where git tracks all changes to your files. Contains the complete history of your project.
- Commit: A snapshot of your files at a specific point in time, with a message describing what changed and why.
- Branch: A parallel version of your repository, allowing you to work on features independently without affecting the main codebase.
The Three-Stage Workflow:
Git uses three stages to manage changes:
- Working Directory: Where you edit your files normally
- Staging Area: Where you prepare changes for a commit (like a “shopping cart” for changes)
- Repository: Where committed changes are permanently stored
This workflow gives you fine control over what gets saved in each commit.
Basic Git Commands:
Check the status of your repository:
git statusAdd files to the staging area:
git add filename.py # Add a specific file
git add . # Add all changed filesCommit staged changes:
git commit -m "Descriptive message about what changed"View commit history:
git logAbout Branches:
Branches let you experiment or work on features without affecting the main code. For this course, you’ll primarily work on the main branch for your project. However, branches become valuable when:
- Testing a new approach without breaking working code
- Collaborating with teammates on different features simultaneously
- Keeping experimental work separate from stable code
We won’t focus heavily on branching in this course, but it’s a powerful feature worth exploring in the Additional Resources.
Visual Learning:
If you’re finding these concepts abstract, check out the Explain Git with D3 resource in the Additional Resources section - it provides an interactive visualization of how git works internally.
6.4.4 Common Git Operations
Once you have git installed, you’ll use a few core operations repeatedly. These commands connect your local work with remote repositories (like those on GitHub).
Understanding Remotes:
A remote is a version of your repository hosted elsewhere (typically on GitHub or another git server). The default remote is usually named origin. When you clone a repository, git automatically sets up the remote connection for you.
Clone: Get a Copy of a Repository
Download a complete copy of a repository to your computer:
git clone <repository-url>This creates a new directory with all the project files and their complete history.
Commit: Save Your Changes Locally
After making changes to files, save a snapshot:
git add .
git commit -m "Description of what changed"This saves changes to your local repository only - they’re not yet on the remote server.
Push: Send Your Commits to the Remote
Upload your local commits to the remote repository:
git push origin mainThis makes your changes visible to others and backs them up on the remote server.
Pull: Get Updates from the Remote
Download and merge changes from the remote repository:
git pull origin mainThis updates your local repository with changes others have made. Always pull before starting new work to avoid conflicts.
6.4.4.1 Cloning the Course Repository
One of the first git operations you’ll perform is cloning the course repository to access lecture materials and sample notebooks:
git clone https://git.inferlab.org/websites/12-770.gitThis creates a local copy of all course materials on your computer. Navigate into the cloned directory to access the lecture notebooks and other resources.
6.4.5 Creating a GitHub Repository
Before creating repositories, make sure you have a GitHub account. If you haven’t already created one as mentioned in the “Before You Begin” section, sign up at github.com.
Creating a New Repository:
Log in to GitHub and click the “+” icon in the top-right corner
Select “New repository”
Choose a repository name (e.g.,
12-770-final-project)Add an optional description
Choose repository visibility:
- Public (recommended for this course): Anyone can see your code
- Private: Only you and collaborators you invite can see the code
For this course, we recommend using public repositories for your final project. This makes collaboration easier and allows you to showcase your work. However, be mindful: never commit secrets, passwords, API keys, or sensitive Home Assistant configuration to public repositories.
Optionally initialize with a README (recommended - it helps document your project)
Click “Create repository”
Getting the Repository URL:
After creating the repository, GitHub will show you the repository URL. You’ll see options for HTTPS and SSH:
- HTTPS:
https://github.com/username/repository.git - SSH:
git@github.com:username/repository.git
About Authentication:
When you clone or push to a GitHub repository, you’ll need to authenticate. GitHub offers two methods:
- HTTPS with Personal Access Token: Works immediately but requires entering credentials
- SSH Keys: More convenient after initial setup - no passwords needed
We’ll cover SSH key setup in the SSH section later in this lecture. For now, you can use HTTPS to get started, but we recommend setting up SSH keys for easier long-term use.
6.4.6 Learn-by-Doing Activity 3: Your First Git Repository
In-Class Exercise: Practice the complete git workflow:
- Create a new repository on GitHub
- Clone it to your local machine using
git clone - Create a new Jupyter notebook in the repository folder
- Add some Python code or markdown cells to the notebook
- Stage your changes:
git add yourfile.ipynb - Commit your changes:
git commit -m "Made my first commit" - Push to GitHub:
git push origin main - Verify the file appears in your GitHub repository online
This workflow of clone → modify → commit → push will be used throughout the course for assignment submissions.
6.5 SSH for Remote Access
6.5.1 What is SSH and Why Do We Need It?
SSH (Secure Shell) is a protocol for securely connecting to remote computers over a network. It encrypts all communication between your computer and the remote server, keeping your data safe from eavesdropping.
Why SSH Matters for This Course:
You’ll use SSH in two important ways:
GitHub Authentication: SSH keys provide a convenient, password-free way to authenticate with GitHub. Once set up, you can push and pull code without entering credentials each time.
Home Assistant Server Access: For your final project, you’ll need to connect to the Home Assistant server to deploy and test your solutions. SSH provides secure remote access to the server’s command line.
SSH uses key-based authentication instead of passwords, which is both more secure and more convenient for regular use.
6.5.2 Installing and Configuring SSH
Most modern operating systems include an SSH client by default. Let’s verify and install if needed.
macOS and Linux
SSH comes pre-installed on macOS and most Linux distributions. Verify it’s available:
ssh -VYou should see output showing the OpenSSH version. If you see this, you’re all set!
Windows
Windows 10 and later include OpenSSH by default. Verify it’s available by opening PowerShell and running:
ssh -VIf you see the version information, you’re ready to go.
Alternative for Windows: PuTTY
If you prefer a graphical interface or are using an older version of Windows, you can install PuTTY, a popular SSH client for Windows. PuTTY includes both command-line tools and a GUI for managing SSH connections.
However, for this course, we recommend using the built-in OpenSSH client (available in PowerShell) as it provides a consistent experience with macOS/Linux and works seamlessly with the commands we’ll use.
6.5.3 SSH Key-Based Authentication
SSH keys work in pairs: a private key (kept secret on your computer) and a public key (shared with services like GitHub or servers you want to access). When you connect, the server uses your public key to verify you own the matching private key, without the private key ever leaving your computer.
Generating SSH Keys
Create a new SSH key pair:
ssh-keygen -t ed25519 -C "your_email@example.com"The -t ed25519 flag specifies the Ed25519 algorithm, which is modern, secure, and recommended for new keys. If you omit this flag, ssh-keygen will use RSA by default, which also works but generates larger keys.
When prompted:
- File location: Press Enter to accept the default location (
~/.ssh/id_ed25519) - Passphrase: You can optionally enter a passphrase for extra security. This means you’ll need to enter the passphrase each time you use the key. For convenience, many users leave this blank, but a passphrase adds an additional layer of protection if your private key is ever compromised.
Viewing Your Public Key
To see your public key (which you’ll add to GitHub and other services):
cat ~/.ssh/id_ed25519.pubThis displays your public key, which starts with ssh-ed25519 and ends with your email. You can safely share this - it’s designed to be public.
Important: Never share your private key (~/.ssh/id_ed25519 without the .pub). Keep it secure on your computer.
6.5.4 Testing Your SSH Connection
Once you’ve generated SSH keys and added them to services like GitHub, you can test your SSH connection.
Testing GitHub SSH Connection
GitHub provides a convenient test endpoint:
ssh -T git@github.comExpected Output:
If successful, you’ll see a message like:
Hi username! You've successfully authenticated, but GitHub does not provide shell access.
This confirms your SSH key is properly configured with GitHub. The “does not provide shell access” part is normal - GitHub only allows git operations via SSH, not shell access.
For Home Assistant Server
Later in the course, when you work with the Home Assistant Green hardware for your final project, you’ll use SSH to connect directly to the server:
ssh username@server-addressThis will give you command-line access to deploy and test your solutions on the actual hardware.
Common Issues
If the connection fails, check:
Key not added: Make sure you’ve added your public key to GitHub (Settings → SSH and GPG keys)
Wrong key location: Ensure your key is in
~/.ssh/id_ed25519(or update your SSH config if using a different location)Permissions: SSH keys require specific permissions. If you have issues, run:
chmod 600 ~/.ssh/id_ed25519 chmod 644 ~/.ssh/id_ed25519.pub
6.5.5 Learn-by-Doing Activity 4: SSH Setup and Testing
Objective: Set up SSH keys for use with GitHub and future Home Assistant server access.
Steps:
-
- Go to GitHub → Settings → SSH and GPG keys → New SSH key
- Paste your public key and give it a descriptive title (e.g., “My Laptop”)
- For detailed instructions, see GitHub’s official SSH key guide
Note: We’re setting this up now as a reference for later use. You’ll actively use SSH keys when:
- Pushing/pulling from GitHub repositories (more convenient than HTTPS)
- Connecting to the Home Assistant server for your final project
You don’t need to verify the connection works right now - we’ll do that when you start working with GitHub repositories and the Home Assistant hardware later in the course. This activity ensures you know where to find these instructions when you need them.
6.6 Putting It All Together
6.6.1 Your Complete Development Workflow
Now that you’ve learned all the individual tools, let’s put them together in a complete workflow. This exercise will test your understanding of the entire development environment.
The Challenge:
Complete this workflow on your own to verify your development environment is fully functional:
Clone the course repository (if you haven’t already):
git clone https://git.inferlab.org/websites/12-770.git cd 12-770Find and copy the sample notebook:
- Navigate to
lectures/Lecture-3/lecture-3-sample-notebook.ipynb - Copy this file to a new location on your computer (outside the course repo)
- Navigate to
Create a new GitHub repository:
- Go to GitHub and create a new public repository named
12-770-test - Initialize with a README
- Clone your new repository to your computer
- Go to GitHub and create a new public repository named
Set up your project with uv:
- In your cloned
12-770-testdirectory, initialize a uv project - Add jupyter and ipykernel as dependencies
- Register a Jupyter kernel for this project
- In your cloned
Work with the notebook:
- Copy the sample notebook into your
12-770-testdirectory - Launch Jupyter Lab
- Open the notebook and make some modifications (add a cell, change some code, etc.)
- Save your changes
- Copy the sample notebook into your
Commit and push to GitHub:
git add lecture-3-sample-notebook.ipynb git commit -m "Add modified sample notebook" git push origin mainVerify: Check your GitHub repository in a web browser - you should see your modified notebook!
What This Tests:
- ✓ Git cloning and repository management
- ✓ uv project setup and dependency management
- ✓ Jupyter Lab with custom kernels
- ✓ Git workflow: add, commit, push
- ✓ GitHub repository creation and verification
If you can complete this workflow successfully, your development environment is ready for the course!
6.6.2 Best Practices
As you work with these tools throughout the course, keep these key practices in mind:
Git and Version Control:
- Commit frequently with descriptive messages that explain why you made changes, not just what changed
- Pull from the course repository regularly to get the latest materials and updates
- Never commit sensitive information (passwords, API keys, personal data) to public repositories
Python and uv:
- Create a separate project for each assignment or experiment - don’t try to do everything in one environment
- Use
uv syncwhen you switch between projects to ensure dependencies are up to date - Keep your
pyproject.tomlfile clean - remove packages you’re no longer using
Jupyter Notebooks:
- Restart your kernel and run all cells before submitting work to ensure it runs from a clean state
- Use markdown cells to document your thinking and explain your approach
- Save often - Jupyter’s autosave helps, but manual saves are more reliable
General Workflow:
- Keep your development tools updated (run occasional
uv self updateandgit --versionto check) - When stuck, check the Additional Resources section - the official documentation is often the best help
- Use the course repository as a reference for working examples of these tools in action
6.7 Additional Resources
6.7.1 Python Resources
- Python Cheat Sheet
- Python Official Documentation
- Scientific Python Lectures - Introduction to Python for Scientific Computing
- Introduction to Python Programming Tutorial
- NumPy Tutorial
- Matplotlib Tutorial
- SciPy Lecture Notes - Heavy focus on Python fundamentals
- Quantitative Economics with Python
6.7.2 Online Courses
- Introduction to Scientific Python (Stanford)
- Practical Data Science (CMU)
- Computational Statistics in Python (Duke)
6.7.3 Git Resources
- Git Official Documentation - Especially the first three videos
- Official Git Tutorial - For those familiar with version control
- Explain Git with D3 - Visual, interactive explanation of git internals
- Git from the Inside Out - In-depth discussion of git internals
- Animated Git Tutorial
- Simple Git Tutorial
- Pro Git Book