6. Troubleshooting

6.1 OpenDSS Convergence / Connection Issues

  • Symptom: Circuit fails to solve or crashes.

  • Action: Add circuit to a SKIP_CIRCUITS list in instantiation scripts and re-run matching/instantiation for remaining feeders.

6.2 Long Runtime for kVAr/kW Ratios

  • Expected: ~579 minutes for a full-state dataset.

  • Mitigation: Reduce circuit set, parallelize where possible, or precompute/store ratios per feeder cohort.

6.3 Large Scenario Memory Footprint

  • Symptom: Python crashes during aggregation.

  • Action: Process in batches; use chunked CSV reads; convert intermediates to parquet.

6.4 Read the Docs Build Failures

  • Missing .readthedocs.yaml or wrong path to docs/conf.py.

  • Mixed Markdown/RST without MyST enabled (ensure myst_parser is in extensions).

  • Autodoc importing Windows-only/OpenDSS deps. Fix: use autodoc_mock_imports (already configured).

Tip

When in doubt, open the RTD build logs from the project dashboard. They usually point to the exact failure line.