Troubleshooting Guide#

This guide helps you resolve common issues when working with BC Combined Modelling.

Installation Issues#

Environment Setup Problems#

Issue: Conda environment creation fails

Error: Could not create conda environment

Solution:

# Clean up any partial installation
conda env remove -n bc_combined_modelling

# Update conda
conda update conda

# Create environment with explicit channel
conda env create -f env/environment.yml -v

# If still fails, try manual installation
conda create -n bc_combined_modelling python=3.9
conda activate bc_combined_modelling
pip install -e .

Issue: Submodule installation fails

Error: Failed to clone submodules

Solution:

# Initialize submodules manually
git submodule init
git submodule update --recursive

# If authentication issues
git submodule update --init --recursive --force

# Install packages individually
cd models/RESource && pip install -e . && cd ../..
cd models/BC_Nexus && pip install -e . && cd ../..
cd models/PyPSA_BC && pip install -e . && cd ../..

Dependency Conflicts#

Issue: Package version conflicts

ERROR: pip has conflicting dependencies

Solution:

# Create fresh environment
conda create -n bc_combined_fresh python=3.9
conda activate bc_combined_fresh

# Install core dependencies first
pip install numpy pandas matplotlib

# Install project
pip install -e .

# Check for conflicts
pip check

Runtime Issues#

Configuration Errors#

Issue: Configuration file not found

FileNotFoundError: config/config.yaml not found

Solution:

# Check if config directory exists
ls -la config/

# Copy from template if needed
cp config/config.yaml.template config/config.yaml

# Verify file paths in configuration
python -c "
import yaml
with open('config/config.yaml') as f:
    config = yaml.safe_load(f)
    print('Configuration loaded successfully')
    print(f'Project name: {config.get(\"project\", {}).get(\"name\", \"Not set\")}')
"

Issue: Invalid configuration parameters

ValidationError: Invalid scenario configuration

Solution:

# Validate configuration
bc-combined validate-config --config config/config.yaml

# Check scenario names
python workflow/scripts/bccm_pipelines.py show_nexus_scenarios

# Use valid scenario names
make nexus SCENARIO=Base_CNZ_noCCS

Data Path Issues#

Issue: Input data not found

FileNotFoundError: Input data files missing

Solution:

# Check data directory structure
ls -la data/

# Verify expected data files exist
python -c "
import os
required_paths = [
    'data/clews_data/',
    'data/pypsa_data/', 
    'data/processed_data/'
]
for path in required_paths:
    exists = os.path.exists(path)
    print(f'{path}: {\"EXISTS\" if exists else \"MISSING\"}')
"

# Create missing directories
mkdir -p data/{clews_data,pypsa_data,processed_data}

Model Execution Errors#

Issue: BC_Nexus model fails

Error in BCNexus.py: Model execution failed

Solution:

# Check BC_Nexus installation
python -c "
try:
    import bc_nexus
    print('BC_Nexus module imported successfully')
except ImportError as e:
    print(f'BC_Nexus import failed: {e}')
"

# Run with verbose output
python workflow/scripts/BCNexus.py --verbose

# Check log files
cat workflow/log/*nexus*.log

# Try with minimal scenario first
make nexus SCENARIO=Base_CNZ_noCCS TIMESLICES=12

Issue: PyPSA optimization fails

OptimizationError: Solver failed to find solution

Solution:

# Check solver installation
python -c "
import pypsa
network = pypsa.Network()
print('Available solvers:')
for solver in ['cbc', 'glpk', 'gurobi', 'cplex']:
    try:
        network.optimize(solver=solver)
        print(f'  {solver}: AVAILABLE')
    except:
        print(f'  {solver}: NOT AVAILABLE')
"

# Install open-source solver
conda install -c conda-forge glpk

# Try with different solver
python workflow/scripts/BCPyPSA.py Base_CNZ_noCCS 24 2035 --solver glpk

Memory and Performance Issues#

Memory Limitations#

Issue: Out of memory errors

MemoryError: Unable to allocate array

Solution:

# Check available memory
free -h

# Reduce temporal resolution
make pypsa TIMESLICES=12  # Instead of 96

# Use memory-efficient options
export PYTHONHASHSEED=0
export OMP_NUM_THREADS=1

# Monitor memory usage
python -c "
import psutil
print(f'Available memory: {psutil.virtual_memory().available / 1e9:.1f} GB')
print(f'Memory percent used: {psutil.virtual_memory().percent:.1f}%')
"

Performance Optimization#

Issue: Models run very slowly

# Models taking excessive time

Solution:

# Use parallel processing
export OMP_NUM_THREADS=4  # Adjust based on CPU cores

# Reduce problem size for testing
make nexus TIMESLICES=12
make pypsa PYPSA_YEAR=2030  # Shorter time horizon

# Profile performance
python -m cProfile workflow/scripts/BCNexus.py > performance_profile.txt

Data Issues#

Data Quality Problems#

Issue: Inconsistent data between models

Warning: Data mismatch between BC_Nexus and PyPSA

Solution:

# Validate data consistency
python -c "
from bc_combined_modelling.clews_to_pypsa import CLEWSPyPSALinker
linker = CLEWSPyPSALinker()
validation_report = linker.validate_data_consistency()
print(validation_report)
"

# Re-run data linking
python workflow/scripts/data_linking.py --validate

# Check temporal alignment
python -c "
import pandas as pd
# Check if timestamps align between datasets
clews_data = pd.read_csv('results/bc_nexus/generation_profiles.csv')
pypsa_data = pd.read_csv('data/pypsa_data/loads.csv') 
print('CLEWS temporal range:', clews_data['datetime'].min(), 'to', clews_data['datetime'].max())
print('PyPSA temporal range:', pypsa_data['datetime'].min(), 'to', pypsa_data['datetime'].max())
"

Missing Data Files#

Issue: Required input data missing

FileNotFoundError: Required input files not found

Solution:

# Download required data
python workflow/scripts/download_data.py

# Check data completeness
python -c "
import os
required_files = [
    'data/clews_data/renewable_resources.csv',
    'data/pypsa_data/network.h5',
    'data/processed_data/demand_profiles.csv'
]
for file in required_files:
    exists = os.path.exists(file)
    size = os.path.getsize(file) if exists else 0
    print(f'{file}: {\"EXISTS\" if exists else \"MISSING\"} ({size} bytes)')
"

Documentation Issues#

Documentation Build Fails#

Issue: Sphinx build errors

Error: Sphinx build failed

Solution:

# Install documentation dependencies
make install-docs

# Clean and rebuild
make clean-docs
make docs-build

# Check for missing files
ls -la docs/source/_static/

# Create placeholder images if needed
python -c "
import matplotlib.pyplot as plt
import os
os.makedirs('docs/source/_static', exist_ok=True)
plt.figure(figsize=(8,2))
plt.text(0.5, 0.5, 'BC Combined Modelling', ha='center', va='center')
plt.axis('off')
plt.savefig('docs/source/_static/BC_Combined_Modelling_logo.png')
plt.close()
print('Placeholder logo created')
"

GitHub Pages Deployment Issues#

Issue: GitHub Pages not updating

# Documentation not appearing on GitHub Pages

Solution:

# Check GitHub Actions status
# Go to: https://github.com/DeltaE/BC_Combined_Modelling/actions

# Verify Pages settings
# Go to: Settings > Pages > Source: GitHub Actions

# Manual deployment
make docs
git add docs/build/html
git commit -m "Update documentation"
git push origin main

# Check .nojekyll file exists
ls -la docs/build/html/.nojekyll

Getting Additional Help#

Log Files and Debugging#

# Enable verbose logging
export PYTHONPATH=/path/to/bc_combined_modelling:$PYTHONPATH
export BC_COMBINED_DEBUG=1

# Check log files
ls -la workflow/log/
tail -n 50 workflow/log/bc_combined_modelling.log

# Run with debug output
python -u workflow/scripts/BCNexus.py 2>&1 | tee debug_output.txt

System Information#

# Collect system information for bug reports
python -c "
import sys, platform, os
print('System Information:')
print(f'  OS: {platform.system()} {platform.release()}')
print(f'  Python: {sys.version}')
print(f'  Current directory: {os.getcwd()}')
print(f'  Environment: {os.environ.get(\"CONDA_DEFAULT_ENV\", \"Not in conda\")}')

# Check package versions
try:
    import bc_combined_modelling
    print(f'  BC Combined Modelling: {bc_combined_modelling.__version__}')
except:
    print('  BC Combined Modelling: Not installed')

try:
    import pypsa
    print(f'  PyPSA: {pypsa.__version__}')
except:
    print('  PyPSA: Not installed')
"

Contact and Support#

If you continue to experience issues:

Check existing issues: GitHub Issues
Create new issue: Include system information and error logs
Contact developers: See Development Team for contact information
Community forum: Join discussions in the repository

Reporting Bugs#

When reporting bugs, please include:

# System information
python --version
conda --version  # if using conda
pip list | grep -E "(pypsa|bc-combined|bc-nexus)"

# Error logs
cat workflow/log/bc_combined_modelling.log

# Configuration
cat config/config.yaml

# Steps to reproduce
echo "1. Command run: make nexus SCENARIO=..."
echo "2. Expected behavior: ..."
echo "3. Actual behavior: ..."
echo "4. Error message: ..."

For additional help, see the Getting Started Guide or contact the development team.

Troubleshooting Guide

Contents

Troubleshooting Guide#

Installation Issues#

Environment Setup Problems#

Dependency Conflicts#

Runtime Issues#

Configuration Errors#

Data Path Issues#

Model Execution Errors#

Memory and Performance Issues#

Memory Limitations#

Performance Optimization#

Data Issues#

Data Quality Problems#

Missing Data Files#

Documentation Issues#

Documentation Build Fails#

GitHub Pages Deployment Issues#

Getting Additional Help#

Log Files and Debugging#

System Information#

Contact and Support#

Reporting Bugs#