Environment Setup Guide

Step-by-step instructions to set up the PopulationSim TM2 environment on your machine.

Prerequisites

Quick Setup

1. Clone Repository

# Clone repository
git clone https://github.com/BayAreaMetro/populationsim.git
cd populationsim
git checkout tm2

2. Create Conda Environment

# Create environment from minimal specification
conda env create -f bay_area/environment_minimal.yml

# Activate environment
conda activate popsim

# Verify Python version (should be 3.8.20)
python --version

Important: Python 3.8 is required. Do not use Python 3.12 due to compatibility issues with PopulationSim dependencies.

3. Verify Installation

cd bay_area

# Test PopulationSim import
python -c "import populationsim; print('PopulationSim installed:', populationsim.__file__)"

# Run environment verification
python setup_environment.py

4. You’re Ready!

Proceed to How to Run to execute the pipeline.

Alternative: Windows Batch Script

For Windows users, use the provided activation script:

cd bay_area
activate_environment.bat

This script will:

Environment Details

Tested Configuration

Component Version/Details
OS Windows 10/11, macOS, Linux
Python 3.8.20 (REQUIRED)
Conda Env popsim
PopulationSim Development version from repo

Key Package Versions

Environment Files

File Purpose
environment_minimal.yml Recommended environment specification
environment_export.yml Complete exact environment
environment_exact.txt Pip-format package list
requirements.txt Legacy pip requirements (use .yml instead)
activate_environment.bat Windows activation helper
setup_environment.py Environment verification script

Troubleshooting

Common Issues

“Python was not found”

Solution: Make sure conda environment is activated

conda activate popsim
python --version

“conda: command not found”

Solutions:

Package version conflicts

Solution: Always use environment_minimal.yml

# Remove old environment
conda env remove -n popsim

# Recreate fresh
conda env create -f bay_area/environment_minimal.yml

“No module named ‘dask’”

Solution: Install dask in the environment

conda activate popsim
conda install -c conda-forge dask

PopulationSim import errors

Solution: Ensure development install was completed

cd populationsim
pip install -e .

# Verify
python -c "import populationsim; print(populationsim.__file__)"

Environment Verification Script

Run this Python snippet to verify your setup:

import sys
print(f"Python version: {sys.version}")

import pandas as pd
print(f"Pandas version: {pd.__version__}")

import populationsim
print(f"PopulationSim path: {populationsim.__file__}")

import dask
print(f"Dask version: {dask.__version__}")

print("\n✓ Environment setup successful!")
← Back to Getting Started Home