Chapter 2: Software Setup Guide

Setup Roadmap¶

Total time: ~30 minutes

Understanding the Setup (2-minute read)¶

Your computer probably already has Python, but it’s used by your operating system. Touching it could break things. We need:

• Our own Python: Separate from system Python (that’s what Miniforge provides)

• Isolated workspace: A bubble for course packages (that’s the conda environment)

• Code editor: A professional tool for writing code (that’s VS Code)

Think of it like setting up a chemistry lab—you need the right equipment in a clean, isolated space where experiments won’t affect anything else.

Step 1: Install Python via Miniforge¶

Miniforge gives us:

• Python + conda package manager (same as Anaconda/Miniconda)

• Free, open-source, no licensing issues

• Works identically on all operating systems

• Default conda-forge channel (community-maintained, most comprehensive)

• Minimal installation (~400 MB vs Anaconda’s ~3 GB)

# Go to Downloads folder
cd ~/Downloads

# Check the file downloaded (should be ~80-100 MB)
ls -lh Miniforge3*.sh

# Make it executable (required on some systems)
chmod +x Miniforge3-*.sh

# Run the installer
bash Miniforge3-*.sh

source ~/.bashrc  # Linux
source ~/.zshrc   # macOS

conda --version

:::{tab-item} Windows
:sync: tab2

:::{admonition} ⚠️ Windows Users: Important Notes
:class: warning

1. The instructor uses macOS/Linux and hasn't personally tested these Windows instructions
2. Most commands work in "Git Bash" (install Git first if needed)
3. Use "Miniforge Prompt" for pure conda operations
4. If you encounter issues:
   - Google the exact error message (in quotes)
   - Ask ChatGPT/Claude with the full error text
   - Post on Slack with screenshots
   - Find a Windows-using classmate!

conda --version

Step 2: Create Your Course Environment¶

An environment is an isolated workspace. Think of it as a clean room where we can install packages without affecting anything else on your computer.

# Create environment with Python 3.11
conda create -n astr596 python=3.11

When prompted “Proceed ([y]/n)?”, type y and press Enter.

# Activate your environment
conda activate astr596

✅ Success Check: Your prompt now shows (astr596) at the beginning

Install Essential Packages¶

You have two options for package installation:

Option 1: Install Everything Now (Recommended)¶

# Install all course packages at once
conda install numpy scipy matplotlib pandas jupyter ipython astropy h5py scikit-learn

# Install JAX and jax-related packages separately (can be finicky)
conda install jax jaxlib -c conda-forge
conda install flax optax diffrax lineax optimistix -c conda-forge

# If JAX fails with conda, use pip as fallback:
# pip install --upgrade jax jaxlib

This ensures you won’t forget to install something later when you need it!

Option 2: Progressive Installation¶

Start with core packages and add others as needed:

# Essential packages (install these now)
conda install numpy matplotlib jupyter ipython

Add more when you need them:

# Scientific computing (Project 2+)
conda install scipy pandas astropy

# Machine learning (Project 3+)
conda install scikit-learn h5py
conda install jax jaxlib -c conda-forge

Managing Packages¶

✅ Quick Test:

python -c "import numpy; print('NumPy works!')"

Step 3: Install and Configure VS Code¶

Installation¶

1. Download from: https://code.visualstudio.com/

2. Run installer for your operating system

3. Launch VS Code

Minimal Setup (That’s All You Need!)¶

1. Install Python Extension:

   • Click Extensions icon in sidebar (or press Ctrl+Shift+X)

   • Search “Python”

   • Install “Python” by Microsoft (first result)

2. Select Your Environment:

   • Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac)

   • Type “Python: Select Interpreter”

   • Choose astr596 from the list

   • Note: VS Code remembers this choice per folder - set once per project!

That’s it! Add other extensions only as you need them.

Disable AI Assistants (Course Requirement)¶

Step 4: Test Your Setup¶

Create a simple test file to verify everything works:

1. Create test_setup.py:

"""Quick setup test for ASTR 596"""
print("Testing imports...")

import numpy as np
print("✓ NumPy works!")

import matplotlib.pyplot as plt
print("✓ Matplotlib works!")

# Only test JAX if you installed it
try:
    import jax
    print("✓ JAX works!")
except ImportError:
    print("○ JAX not installed (that's okay for now)")

print("\n🎉 Everything is installed correctly!")
print("Your environment is ready for ASTR 596!")

2. Run the test:

python test_setup.py

✅ Success: You see checkmarks and the success message!

Step 5: Quick Practice¶

Let’s make sure you’re comfortable with the basics:

# 1. Check your environment is active
conda activate astr596

# 2. Check what's installed
conda list

# 3. Create a simple plot
python -c "import matplotlib.pyplot as plt; plt.plot([1,2,3]); plt.savefig('test.png'); print('Created test.png')"

# 4. Open VS Code in current folder
code .

✅ Setup Complete Checklist¶

You’re ready for the course when:

• Opening a new terminal and typing conda activate astr596 works

• The prompt shows (astr596) after activation

• Running python -c "import numpy" produces no errors

• VS Code opens when you type code .

• The test script runs successfully

All checked? You’re ready!

🎉 Congratulations!¶

You’ve just accomplished what many graduate students struggle with for weeks. Your professional development environment is now:

• ✅ Isolated from system Python (no conflicts!)

• ✅ Reproducible (same setup works on any machine)

• ✅ Professional-grade (same tools as research scientists)

Take a screenshot of your successful test script output—you’ve earned this victory!

Troubleshooting¶

# Configure proxy (replace with your proxy details)
conda config --set proxy_servers.http http://proxy.yourorg.com:8080
conda config --set proxy_servers.https https://proxy.yourorg.com:8080

# Remove environment and start fresh
conda deactivate
conda env remove -n astr596
# Then go back to Step 2

# Remove unused packages and cache
conda clean --all
# Check environment size
du -sh ~/miniforge3/envs/astr596

What’s Next?¶

1. ✅ Environment is ready

2. → Continue to Git and GitHub Guide

3. → Start working on Project 1

Quick Reference Card¶