Troubleshooting Guide

"Python not found" or "python is not recognized"

Python is not installed or not in your system PATH.

• Recommended: Install Anaconda, which bundles Python, Jupyter, pandas, scikit-learn, and other packages the guides need.
• Windows: After installing Anaconda, open Anaconda Prompt from the Start Menu instead of Command Prompt.
• macOS/Linux: If you installed Python via Homebrew or your package manager, try python3 instead of python.
• Verify: Run python --version (or python3 --version). You should see Python 3.8 or later.

pip install fails or "pip: command not found"

• Try pip3 install ... instead of pip install ...
• If you get permission errors, add --user: pip install --user pandas scikit-learn
• Best practice: Use a virtual environment to avoid conflicts:
  python -m venv ml-playground-env # Windows: ml-playground-env\Scripts\activate # macOS/Linux: source ml-playground-env/bin/activate pip install pandas numpy matplotlib seaborn scikit-learn xgboost lightgbm

Jupyter won't start

• Install JupyterLab: pip install jupyterlab
• If you see a port conflict error, specify a different port: jupyter lab --port 8889
• Alternatively, use Google Colab in your browser — no local install needed.

ModuleNotFoundError: No module named 'demo_data'

You must run scripts from the repository root directory (the folder containing the demo_data/ folder).

FileNotFoundError for CSV files

• Verify you cloned the full repository: git clone https://github.com/SGridworks/Dynamic-Network-Model.git
• Check your working directory:
  import os print(os.getcwd()) print(os.listdir("demo_data"))
• Make sure you're running from the repo root, not from a subdirectory.

KeyError on column name

Column names were recently updated for clarity. If you see a KeyError like KeyError: 'rated_kva' or KeyError: 'start_time', you may have an older version of the code or data.

• Pull the latest version: git pull origin main
• Updated column names:
  • rated_kva → kva_rating (transformers.csv)
  • cause → cause_code (outage_history.csv)
  • start_time → fault_detected (outage_history.csv)
  • end_time → service_restored (outage_history.csv)
  • customers_affected → affected_customers (outage_history.csv)

MemoryError loading data

The customer_interval_data.csv file is large (~605 MB uncompressed). For testing and development, load a subset:

Guide 03: "OpenDSS not found"

OpenDSS is an optional dependency for the full power flow analysis in Guide 03 (Hosting Capacity).

• Install it: pip install opendssdirect.py
• Note: OpenDSS is only available on Windows and Linux, not macOS. On macOS, use the simplified screening method provided in the guide (no OpenDSS needed).
• The guide's test script will skip the OpenDSS section if it's not installed and still validate the rest.

Guide 06: Q-learning not converging

The reinforcement learning model in Guide 06 (Volt-VAR Optimization) can be sensitive to hyperparameters.

• Check the epsilon decay rate — if it decays too fast, the agent won't explore enough. Try epsilon_decay = 0.995 instead of 0.99.
• Increase training episodes to at least 500–1000.
• Verify the reward function rewards voltage within bounds and penalizes out-of-range values.

Guide 10: LSTM/TensorFlow crash

TensorFlow can have environment issues on some systems, especially Apple Silicon Macs or older GPUs.

• Recommended: Use the XGBoost alternative provided in the guide — it produces comparable results without TensorFlow dependencies.
• If you want TensorFlow: pip install tensorflow (for Apple Silicon: pip install tensorflow-macos tensorflow-metal)
• Set TF_CPP_MIN_LOG_LEVEL=2 to suppress warnings: import os; os.environ['TF_CPP_MIN_LOG_LEVEL'] = '2'