feat(api): unify results API; add backend selection and multiperiod/pyomo support

[nathantgray]

Feature: API Improvements — Summary of Changes

Branch: feature/api-improvements
Compared against: origin/develop (head)

Overview

This feature unifies the results API and improves backend selection and multi-period support. The main goals were:

• Provide a single, consistent result object for all solver backends.
• Centralize backend selection (auto-detect and explicit override).
• Add/normalize multiperiod and Pyomo backend support.
• Improve examples, tests, and developer ergonomics.

Key Changes

• Added PowerFlowResult dataclass (src/distopf/results.py) as the unified results container for PF/OPF/FBS.

  • Centralized plotting (plot_*), save/export (save()), and summary (summary()) on the result object.
  • Backward-compatible convenience behavior preserved via explicit APIs.

• Case API updates

  • Case.run_pf(), Case.run_opf(), and Case.run_fbs() now return a PowerFlowResult (optionally raw_result preserved).
  • Added Case._select_backend() helper (wrapper for backend auto-selection).

• Backend selection and backends

  • New BackendSelector (src/distopf/backend_selector.py) implements auto-selection rules and routing.
  • Added backend implementations (factory/structure) for:
    • matrix (single-period, CVXPY/clarabel)
    • multiperiod (time-series/battery support)
    • pyomo (NLP/IPOPT)

• Multiperiod & Pyomo

  • Normalized outputs across backends (e.g., add time column t for single-period to ensure consistent shapes).
  • Warnings for unsupported backend-specific kwargs.
  • Fixed Pyomo solver interface issues encountered during integration.

• FBS (Forward-Backward Sweep)

  • Added run_fbs() and distopf.fbs utilities for fast 3-phase radial power flows.
  • Example examples/11_fbs_power_flow.py added demonstrating FBS and comparison with case.run_pf().

• Examples & docs

  • Added/updated example scripts in examples/ and consolidated example README into examples/README.md.
  • Removed duplicate migration/deprecation notes from MIGRATION.md (cleared by request).
  • Added docs/FEATURE_API_IMPROVEMENTS_SUMMARY.md (this file).

• Tests

  • Added tests for new behavior: tests/test_results_api.py, tests/test_fbs_validation.py, tests/test_case_validation.py.
  • Updated existing tests that relied on the old result API.

Files of Note (selected)

New/Added

• src/distopf/results.py (PowerFlowResult)
• src/distopf/backend_selector.py
• src/distopf/backends/* (backend implementations)
• src/distopf/api.py (formerly importer.py)
• examples/11_fbs_power_flow.py
• tests/test_results_api.py, tests/test_fbs_validation.py

Modified

• src/distopf/* (matrix and pyomo model integrations, fbs, plot interfaces)
• examples/* (added/normalized examples)
• tests/* (updated to new API)

Removed

• MIGRATION.md contents cleared (file removed from branch in final commit)
• src/distopf/result.py (replaced by results.py)

Migration Notes for Users

• Minimal friction: the key change is that analysis methods return a PowerFlowResult object.

  • Access results via result.voltages, result.p_flows, result.p_gens, result.q_gens.
  • If you relied on tuple unpacking, adapt to the object-based API (see examples/).

• Case no longer exposes result DataFrames as persistent properties; use the return value.

How to run smoke checks

Run examples and tests locally:

uv run examples/11_fbs_power_flow.py
uv run pytest tests/test_results_api.py -q
uv run pytest -m "not slow"

---

If you'd like, I can push the branch to the remote and/or open a PR draft with this summary as the PR description. Let me know which you prefer.