distopf 1.1.0.dev3__tar.gz → 1.1.0.dev5__tar.gz

{distopf-1.1.0.dev3 → distopf-1.1.0.dev5}/.gitignore

@@ -15,3 +15,7 @@ examples/layouts/*
 *.code-workspace
 scratch/*
 */.ipynb_checkpoints/*
+graphify-out/
+CLAUDE.md
+.claude/
+benchmarks/

{distopf-1.1.0.dev3 → distopf-1.1.0.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: distopf
-Version: 1.1.0.dev3
+Version: 1.1.0.dev5
 Summary: A package for solving unbalanced three-phase distribution system optimal power flow problems.
 Author: Abodh Poudyal
 Author-email: Nathan Gray <nathan.gray@pnnl.gov>, Rabayet Sadnan <rabayet.sadnan@pnnl.gov>
@@ -16,7 +16,9 @@ Requires-Dist: pandas>=2.3.3
 Requires-Dist: plotly>=6.3.0
 Requires-Dist: pyomo>=6.9.4
 Requires-Dist: pyscipopt>=6.0.0
+Requires-Dist: rich-click>=1.9.9
 Requires-Dist: scipy>=1.15.3
+Requires-Dist: tomli>=2.0.1; python_version < '3.11'
 Provides-Extra: cim
 Requires-Dist: cim-graph==0.4.1a2; extra == 'cim'
 Requires-Dist: gridappsd-python==2025.3.2a13; extra == 'cim'
@@ -100,13 +102,14 @@ result.plot_network().show(renderer="browser")
 ```python
 import distopf as opf
 case = opf.create_case(opf.CASES_DIR / "csv" / "ieee123_30der")
-result = case.run_opf(objective="curtail_min", control_variable="P", v_max=1.05, v_min=0.95, gen_mult=10)
+case.modify(v_max=1.05, v_min=0.95, gen_mult=10)
+result = case.run_opf(objective="curtail_min", control_variable="P")
 result.plot_network().show(renderer="browser")
 ```
 
 ## Spatial ENAPP and ADMM solvers
 
-The spatial solvers are available through the public [`Case.run_enapp()`](src/distopf/api.py:577) and [`Case.run_admm()`](src/distopf/api.py:617) methods. Supply an area topology as a JSON-safe dictionary keyed by area name. Each area must define `up_areas`, `down_areas`, and exactly one `up_buses` entry; bus names must match the selected case.
+The spatial solvers are available through the public [`Case.run_enapp()`](src/distopf/api.py:590) and [`Case.run_admm()`](src/distopf/api.py:630) methods. Supply an area topology as a JSON-safe dictionary keyed by area name. Each area must define `up_areas`, `down_areas`, and exactly one `up_buses` entry; bus names must match the selected case.
 
 ```python
 area_info = {
@@ -127,19 +130,57 @@ case = opf.create_case(opf.CASES_DIR / "csv" / "ieee13")
 result = case.run_enapp(
     area_info=area_info,
     objective="substation_power",
-    parallel=False,
+    parallel=True,
     max_iterations=25,
 )
 ```
 
-Runs made through these methods are recorded by [`record_call()`](src/distopf/utils/call_recorder.py:90). Calling [`PowerFlowResult.save()`](src/distopf/results.py:209) writes `run_config.json`, including the distributed solver and topology, so named-objective runs can be reproduced with [`replay()`](src/distopf/api.py:1140):
+Set `parallel=True` to solve the independent area subproblems with multiprocessing. The coordination iterations themselves remain sequential: each iteration waits for all area solves before exchanging boundary messages. Use `parallel=False` for serial execution or when debugging.
+
+Runs made through these methods are recorded by [`record_call()`](src/distopf/utils/call_recorder.py:90). Calling [`PowerFlowResult.save()`](src/distopf/results.py:209) writes `run_config.json`, including the distributed solver, topology, and `parallel` setting, so named-objective runs can be reproduced with [`replay()`](src/distopf/api.py:1165):
 
 ```python
 result.save("results/ieee13-enapp")
 replayed = opf.replay("results/ieee13-enapp/run_config.json")
 ```
 
-Custom objective callables and solve/iteration callbacks are intentionally marked non-replayable because they cannot be reconstructed from JSON.
+Replay preserves the recorded `parallel` setting for ENAPP and ADMM. Parallel replay requires a normal multiprocessing-capable execution environment; arbitrary custom objective callables and solve/iteration callbacks remain non-replayable because they cannot be reconstructed from JSON.
+
+### Command-line interface
+
+The installed `distopf` command provides human-readable and JSON output for saved runs, user-authored TOML scenarios, and result comparisons. Run `distopf --help` or any subcommand with `--help` for the complete option list.
+
+```bash
+distopf inspect results/ieee13-enapp/run_config.json
+distopf validate results/ieee13-enapp/run_config.json
+distopf run results/ieee13-enapp/run_config.json --output-dir results/replayed
+```
+
+Public commands are:
+
+- `run CONFIG [--output-dir DIR] [--verbose] [--json]` runs a JSON `run_config.json` replay artifact or a TOML scenario. Scenario analysis types are `pf`/`power_flow`, `fbs`, `opf`, `enapp`, and `admm`.
+- `inspect CONFIG [--json]` displays scenario or replay metadata without solving.
+- `validate CONFIG [--json]` checks configuration structure, referenced paths, replayability, and case data.
+- `replay-exact-power-flow INPUT_PATH [OUTPUT_PATH] [--overwrite] [--json]` replays saved OPF setpoints through the exact FBS power flow. The output defaults to `INPUT_PATH/exact`; existing output is preserved unless `--overwrite` is supplied.
+- `compare LEFT_FOLDER RIGHT_FOLDER [--output-dir DIR] [--nominal-voltage VALUE] [--json]` compares common result CSV tables and writes `comparison.json` plus difference CSVs. `--nominal-voltage` defaults to `1.0` and is used for voltage metrics.
+- `compare-exact FOLDER [RIGHT_FOLDER] [--batch] [--depth N] [--workers N] [--output-dir DIR] [--nominal-voltage VALUE] [--json]` compares a result folder with its `exact` FBS replay, creating that replay when needed. With `--batch`, it processes directories exactly `--depth` levels below `FOLDER`; `RIGHT_FOLDER` cannot be combined with `--batch`.
+
+Add `--json` to any command for machine-readable output. Successful commands return `0`; validation failures return `1`; run and comparison runtime failures return `2`.
+
+Use `distopf run --help` for the full scenario format. A minimal `scenario.toml` is:
+
+```toml
+[case]
+path = "../cases/csv/ieee13"
+
+[analysis]
+type = "opf"
+objective = "loss"
+```
+
+TOML scenarios require only `case.path` and `analysis.type`; `pf`/`power_flow`, `fbs`, `opf`, `enapp`, and `admm` are supported. Case options go directly under `[case]`, modifications under `[case.modifications]`, and ENAPP/ADMM topology under `[analysis.area_info.<area>]`. The `version` field is optional and defaults to `1`.
+
+JSON `run_config.json` files generated by `PowerFlowResult.save()` remain supported as exact replay artifacts. Use `--json` on any subcommand for automation. `inspect` reads metadata without solving. `validate` checks the schema, referenced case directory, replayability, and case data. `run` executes either format and can persist result CSV files and metadata with `--output-dir`. Successful commands return exit code `0`; validation failures return `1`; run/runtime failures return `2`.
 
 
 
@@ -168,6 +209,27 @@ Use `formulation="branchflow"`.
 - **Speed**: Slower than linear, but more accurate
 - **Accuracy**: Nonlinear power flow representation
 
+### Pyomo Wrapper — SOCP Relaxation
+The SOCP formulation is a relaxation of the nonlinear BranchFlow model. It uses the same
+Pyomo/IPOPT solve path, but replaces the two branch-current equality constraints with
+inequality constraints. Use `formulation="socp"`.
+
+- **Model**: BranchFlow model with relaxed current constraints
+- **Solver**: IPOPT for continuous problems; MINLP solvers for discrete controls
+- **Use case**: Faster or more robust optimization when exact current equalities are not required
+- **Wrapper**: Pyomo only; it is not available through the matrix wrappers
+
+```python
+import distopf as opf
+
+case = opf.create_case(opf.CASES_DIR / "csv" / "ieee13")
+result = case.run_opf(
+    formulation="socp",
+    objective="loss",
+    solver="ipopt",
+)
+```
+
 #### Continuous Optimization (IPOPT)
 For continuous optimization without discrete controls:
 
@@ -208,12 +270,14 @@ result = case.run_opf(wrapper="matrix_bess", objective="loss")
 ```
 
 #### Wrapper Comparison
-| Feature | Matrix/Matrix BESS | Pyomo  |
-|---------|---|---|
-| Model Type | LinDistFlow (linear) | LinDistFlow or Non-Linear BranchFlow |
-| Formulation | Matrix-based | Algebraic equations |
-| Solver API | Scipy or CVXPY | Pyomo |
-| Prefered Solver | HiGHs or Clarabel | IPOPT, Gurobi, Knitro |
+| Feature | Matrix | Matrix BESS | Pyomo |
+|---------|---|---|---|
+| Primary role | Single-period convex LinDistFlow OPF | Multi-period LinDistFlow OPF with batteries and schedules | LinDistFlow, BranchFlow, or SOCP-relaxed BranchFlow |
+| Solver API | SciPy or CVXPY | CVXPY | Pyomo |
+| Default solver path | CVXPY with CLARABEL | CVXPY with CLARABEL | IPOPT |
+| Other supported solver choices | Depends on installed CVXPY/SciPy backends | Depends on installed CVXPY backend | MINLP solvers such as Bonmin/Couenne for supported discrete models |
+
+The default `Case.run_opf()` wrapper is Pyomo unless a `formulation` selects another wrapper. Matrix is intended for fast single-period convex models; Matrix BESS is the time-series/battery backend. Pyomo is the backend for nonlinear BranchFlow, SOCP, Pyomo dual extraction, and its supported discrete formulations. Solver availability depends on the installed backend and model.
 
 #### Solver Requirements
 - **IPOPT**: Install via `conda install -c conda-forge ipopt`. On Ubuntu, `apt-get install coinor-libipopt-dev` only installs headers and shared libraries; it does not provide the `ipopt` executable that Pyomo's `SolverFactory("ipopt")` expects.
@@ -224,11 +288,11 @@ DistOPF supports multiple optimization objectives for distribution system OPF:
 
 | Objective | String | Supported Wrappers | Description |
 |-----------|--------|-------------------|-------------|
-| **Loss Minimization** | `"loss"`, `"loss_min"` | All | Minimize distribution losses (most common) |
-| **Substation Power** | `"substation"`, `"substation_power"` | Pyomo, Matrix | Minimize power imported from substation |
+| **Loss Minimization** | `"loss"`, `"loss_min"` | Matrix, Matrix BESS, Pyomo | Minimize distribution losses (most common) |
+| **Substation Power** | `"substation"`, `"substation_power"` | Pyomo | Minimize power imported from substation |
 | **Voltage Deviation** | `"voltage_deviation"` | Pyomo | Minimize deviations from nominal voltage (1.0 p.u.) |
-| **Generation Curtailment** | `"curtail"`, `"curtail_min"`, `"curtailment"` | Pyomo | Minimize DER curtailment |
-| **Cost Minimization** | `"cost"`, `"cost_min"` | Pyomo (LinDistFlow, BranchFlow) | Minimize energy procurement cost from swing bus |
+| **Generation Curtailment** | `"curtail"`, `"curtail_min"`, `"curtailment"` | Matrix, Matrix BESS, Pyomo | Minimize DER curtailment |
+| **Cost Minimization** | `"cost"`, `"cost_min"` | Pyomo | Minimize energy procurement cost from the swing bus; requires price data and a time horizon |
 
 #### Cost Minimization with Price Data
 
@@ -238,10 +302,10 @@ To use cost minimization, add an hourly `price` column to the case schedules (in
 import pandas as pd
 import distopf as opf
 
-case = opf.create_case(opf.CASES_DIR / "csv" / "ieee123_30der")
+case = opf.create_case(opf.CASES_DIR / "csv" / "ieee123_30der", n_steps=24)
 
 # Add hourly electricity prices
-case.schedules['price'] = [38, 35, 34, 32, 30, 32, 38, 45, 52, 58, 62, 65, 
+case.schedules['price'] = [38, 35, 34, 32, 30, 32, 38, 45, 52, 58, 62, 65,
                             68, 65, 62, 58, 55, 60, 75, 82, 78, 65, 50, 42]
 
 # Run OPF minimizing energy cost
@@ -251,10 +315,15 @@ print(f"Total energy cost: ${result.objective_value:.2f}")
 
 ### Result Fields
 
-`PowerFlowResult` uses descriptive field names. Short aliases are also accepted for backward compatibility.
+`PowerFlowResult` uses descriptive field names. Short aliases are also accepted for backward compatibility. Fields are optional: availability depends on the analysis, backend, case devices, and requested options.
+
+Core fields include `voltages`/`voltage_magnitudes`, `voltage_angles`, active and reactive power flows, active and reactive generation, and active and reactive loads. FBS results provide `voltage_angles`, `currents`, and `current_angles` (angles are in degrees); these fields can also be present when another backend has computed them.
+
+Battery and device fields include `battery_active_power`, `battery_reactive_power`, `p_charge`, `p_discharge`, and `soc`; regulator/capacitor-related fields include `tap_ratios`, `reg_taps`, `z_caps`, and `u_caps`, where supported by the selected model. `capacitor_reactive_power` is also available for capacitor outputs. Mixed-integer binary details may remain available through `raw_result` rather than the unified result fields.
 
 | Field Name | Alias |
 |---|---|
+| `voltages` | — |
 | `active_power_flows` | `p_flows` |
 | `reactive_power_flows` | `q_flows` |
 | `active_power_generation` | `p_gens` |
@@ -263,19 +332,25 @@ print(f"Total energy cost: ${result.objective_value:.2f}")
 | `reactive_power_loads` | `q_loads` |
 | `capacitor_reactive_power` | `q_caps` |
 | `battery_active_power` | `p_bats` |
-| `voltage_magnitudes` | `voltages` |
+| `battery_reactive_power` | `q_bats` |
+
+#### Plotting and Dual Variables
 
-#### Dual Variables
-When running with `duals=True`, dual variables are accessible on the result object:
+The public plotting methods return Plotly figures: `plot_voltages(t=None)`, `plot_power_flows(t=None)`, `plot_gens(t=None)`, `plot_batteries()`, `plot_schedules()`, `plot_network(v_min=0.95, v_max=1.05, show_phases="abc", show_reactive_power=False, t=None)`, `plot_voltage_vs_distance(title=..., color_by="algorithm", include_secondary_phases=False)`, and `plot_line_flow_vs_distance(power_type="active", title=..., color_by="algorithm", include_secondary_phases=False)`. Methods that require unavailable result data or a case reference raise `RuntimeError`.
+
+When running with `duals=True` using the Pyomo wrapper, dual variables are accessible on the result object. The unified names are:
 
 ```python
 result = case.run_opf(wrapper="pyomo", objective="loss", duals=True)
 result.dual_power_balance_p
 result.dual_power_balance_q
 result.dual_voltage_drop
-result.dual_voltage_limits
+result.dual_voltage_limits_lower
+result.dual_voltage_limits_upper
 ```
 
+Dual extraction is Pyomo-only; matrix and FBS results do not populate these fields.
+
 ## Using a custom model.
 Create CSVs formatted as shown below and store them in a single folder. The csv names must match exactly as shown. 
 Column order is not important. 

{distopf-1.1.0.dev3 → distopf-1.1.0.dev5}/README.md

@@ -76,13 +76,14 @@ result.plot_network().show(renderer="browser")
 ```python
 import distopf as opf
 case = opf.create_case(opf.CASES_DIR / "csv" / "ieee123_30der")
-result = case.run_opf(objective="curtail_min", control_variable="P", v_max=1.05, v_min=0.95, gen_mult=10)
+case.modify(v_max=1.05, v_min=0.95, gen_mult=10)
+result = case.run_opf(objective="curtail_min", control_variable="P")
 result.plot_network().show(renderer="browser")
 ```
 
 ## Spatial ENAPP and ADMM solvers
 
-The spatial solvers are available through the public [`Case.run_enapp()`](src/distopf/api.py:577) and [`Case.run_admm()`](src/distopf/api.py:617) methods. Supply an area topology as a JSON-safe dictionary keyed by area name. Each area must define `up_areas`, `down_areas`, and exactly one `up_buses` entry; bus names must match the selected case.
+The spatial solvers are available through the public [`Case.run_enapp()`](src/distopf/api.py:590) and [`Case.run_admm()`](src/distopf/api.py:630) methods. Supply an area topology as a JSON-safe dictionary keyed by area name. Each area must define `up_areas`, `down_areas`, and exactly one `up_buses` entry; bus names must match the selected case.
 
 ```python
 area_info = {
@@ -103,19 +104,57 @@ case = opf.create_case(opf.CASES_DIR / "csv" / "ieee13")
 result = case.run_enapp(
     area_info=area_info,
     objective="substation_power",
-    parallel=False,
+    parallel=True,
     max_iterations=25,
 )
 ```
 
-Runs made through these methods are recorded by [`record_call()`](src/distopf/utils/call_recorder.py:90). Calling [`PowerFlowResult.save()`](src/distopf/results.py:209) writes `run_config.json`, including the distributed solver and topology, so named-objective runs can be reproduced with [`replay()`](src/distopf/api.py:1140):
+Set `parallel=True` to solve the independent area subproblems with multiprocessing. The coordination iterations themselves remain sequential: each iteration waits for all area solves before exchanging boundary messages. Use `parallel=False` for serial execution or when debugging.
+
+Runs made through these methods are recorded by [`record_call()`](src/distopf/utils/call_recorder.py:90). Calling [`PowerFlowResult.save()`](src/distopf/results.py:209) writes `run_config.json`, including the distributed solver, topology, and `parallel` setting, so named-objective runs can be reproduced with [`replay()`](src/distopf/api.py:1165):
 
 ```python
 result.save("results/ieee13-enapp")
 replayed = opf.replay("results/ieee13-enapp/run_config.json")
 ```
 
-Custom objective callables and solve/iteration callbacks are intentionally marked non-replayable because they cannot be reconstructed from JSON.
+Replay preserves the recorded `parallel` setting for ENAPP and ADMM. Parallel replay requires a normal multiprocessing-capable execution environment; arbitrary custom objective callables and solve/iteration callbacks remain non-replayable because they cannot be reconstructed from JSON.
+
+### Command-line interface
+
+The installed `distopf` command provides human-readable and JSON output for saved runs, user-authored TOML scenarios, and result comparisons. Run `distopf --help` or any subcommand with `--help` for the complete option list.
+
+```bash
+distopf inspect results/ieee13-enapp/run_config.json
+distopf validate results/ieee13-enapp/run_config.json
+distopf run results/ieee13-enapp/run_config.json --output-dir results/replayed
+```
+
+Public commands are:
+
+- `run CONFIG [--output-dir DIR] [--verbose] [--json]` runs a JSON `run_config.json` replay artifact or a TOML scenario. Scenario analysis types are `pf`/`power_flow`, `fbs`, `opf`, `enapp`, and `admm`.
+- `inspect CONFIG [--json]` displays scenario or replay metadata without solving.
+- `validate CONFIG [--json]` checks configuration structure, referenced paths, replayability, and case data.
+- `replay-exact-power-flow INPUT_PATH [OUTPUT_PATH] [--overwrite] [--json]` replays saved OPF setpoints through the exact FBS power flow. The output defaults to `INPUT_PATH/exact`; existing output is preserved unless `--overwrite` is supplied.
+- `compare LEFT_FOLDER RIGHT_FOLDER [--output-dir DIR] [--nominal-voltage VALUE] [--json]` compares common result CSV tables and writes `comparison.json` plus difference CSVs. `--nominal-voltage` defaults to `1.0` and is used for voltage metrics.
+- `compare-exact FOLDER [RIGHT_FOLDER] [--batch] [--depth N] [--workers N] [--output-dir DIR] [--nominal-voltage VALUE] [--json]` compares a result folder with its `exact` FBS replay, creating that replay when needed. With `--batch`, it processes directories exactly `--depth` levels below `FOLDER`; `RIGHT_FOLDER` cannot be combined with `--batch`.
+
+Add `--json` to any command for machine-readable output. Successful commands return `0`; validation failures return `1`; run and comparison runtime failures return `2`.
+
+Use `distopf run --help` for the full scenario format. A minimal `scenario.toml` is:
+
+```toml
+[case]
+path = "../cases/csv/ieee13"
+
+[analysis]
+type = "opf"
+objective = "loss"
+```
+
+TOML scenarios require only `case.path` and `analysis.type`; `pf`/`power_flow`, `fbs`, `opf`, `enapp`, and `admm` are supported. Case options go directly under `[case]`, modifications under `[case.modifications]`, and ENAPP/ADMM topology under `[analysis.area_info.<area>]`. The `version` field is optional and defaults to `1`.
+
+JSON `run_config.json` files generated by `PowerFlowResult.save()` remain supported as exact replay artifacts. Use `--json` on any subcommand for automation. `inspect` reads metadata without solving. `validate` checks the schema, referenced case directory, replayability, and case data. `run` executes either format and can persist result CSV files and metadata with `--output-dir`. Successful commands return exit code `0`; validation failures return `1`; run/runtime failures return `2`.
 
 
 
@@ -144,6 +183,27 @@ Use `formulation="branchflow"`.
 - **Speed**: Slower than linear, but more accurate
 - **Accuracy**: Nonlinear power flow representation
 
+### Pyomo Wrapper — SOCP Relaxation
+The SOCP formulation is a relaxation of the nonlinear BranchFlow model. It uses the same
+Pyomo/IPOPT solve path, but replaces the two branch-current equality constraints with
+inequality constraints. Use `formulation="socp"`.
+
+- **Model**: BranchFlow model with relaxed current constraints
+- **Solver**: IPOPT for continuous problems; MINLP solvers for discrete controls
+- **Use case**: Faster or more robust optimization when exact current equalities are not required
+- **Wrapper**: Pyomo only; it is not available through the matrix wrappers
+
+```python
+import distopf as opf
+
+case = opf.create_case(opf.CASES_DIR / "csv" / "ieee13")
+result = case.run_opf(
+    formulation="socp",
+    objective="loss",
+    solver="ipopt",
+)
+```
+
 #### Continuous Optimization (IPOPT)
 For continuous optimization without discrete controls:
 
@@ -184,12 +244,14 @@ result = case.run_opf(wrapper="matrix_bess", objective="loss")
 ```
 
 #### Wrapper Comparison
-| Feature | Matrix/Matrix BESS | Pyomo  |
-|---------|---|---|
-| Model Type | LinDistFlow (linear) | LinDistFlow or Non-Linear BranchFlow |
-| Formulation | Matrix-based | Algebraic equations |
-| Solver API | Scipy or CVXPY | Pyomo |
-| Prefered Solver | HiGHs or Clarabel | IPOPT, Gurobi, Knitro |
+| Feature | Matrix | Matrix BESS | Pyomo |
+|---------|---|---|---|
+| Primary role | Single-period convex LinDistFlow OPF | Multi-period LinDistFlow OPF with batteries and schedules | LinDistFlow, BranchFlow, or SOCP-relaxed BranchFlow |
+| Solver API | SciPy or CVXPY | CVXPY | Pyomo |
+| Default solver path | CVXPY with CLARABEL | CVXPY with CLARABEL | IPOPT |
+| Other supported solver choices | Depends on installed CVXPY/SciPy backends | Depends on installed CVXPY backend | MINLP solvers such as Bonmin/Couenne for supported discrete models |
+
+The default `Case.run_opf()` wrapper is Pyomo unless a `formulation` selects another wrapper. Matrix is intended for fast single-period convex models; Matrix BESS is the time-series/battery backend. Pyomo is the backend for nonlinear BranchFlow, SOCP, Pyomo dual extraction, and its supported discrete formulations. Solver availability depends on the installed backend and model.
 
 #### Solver Requirements
 - **IPOPT**: Install via `conda install -c conda-forge ipopt`. On Ubuntu, `apt-get install coinor-libipopt-dev` only installs headers and shared libraries; it does not provide the `ipopt` executable that Pyomo's `SolverFactory("ipopt")` expects.
@@ -200,11 +262,11 @@ DistOPF supports multiple optimization objectives for distribution system OPF:
 
 | Objective | String | Supported Wrappers | Description |
 |-----------|--------|-------------------|-------------|
-| **Loss Minimization** | `"loss"`, `"loss_min"` | All | Minimize distribution losses (most common) |
-| **Substation Power** | `"substation"`, `"substation_power"` | Pyomo, Matrix | Minimize power imported from substation |
+| **Loss Minimization** | `"loss"`, `"loss_min"` | Matrix, Matrix BESS, Pyomo | Minimize distribution losses (most common) |
+| **Substation Power** | `"substation"`, `"substation_power"` | Pyomo | Minimize power imported from substation |
 | **Voltage Deviation** | `"voltage_deviation"` | Pyomo | Minimize deviations from nominal voltage (1.0 p.u.) |
-| **Generation Curtailment** | `"curtail"`, `"curtail_min"`, `"curtailment"` | Pyomo | Minimize DER curtailment |
-| **Cost Minimization** | `"cost"`, `"cost_min"` | Pyomo (LinDistFlow, BranchFlow) | Minimize energy procurement cost from swing bus |
+| **Generation Curtailment** | `"curtail"`, `"curtail_min"`, `"curtailment"` | Matrix, Matrix BESS, Pyomo | Minimize DER curtailment |
+| **Cost Minimization** | `"cost"`, `"cost_min"` | Pyomo | Minimize energy procurement cost from the swing bus; requires price data and a time horizon |
 
 #### Cost Minimization with Price Data
 
@@ -214,10 +276,10 @@ To use cost minimization, add an hourly `price` column to the case schedules (in
 import pandas as pd
 import distopf as opf
 
-case = opf.create_case(opf.CASES_DIR / "csv" / "ieee123_30der")
+case = opf.create_case(opf.CASES_DIR / "csv" / "ieee123_30der", n_steps=24)
 
 # Add hourly electricity prices
-case.schedules['price'] = [38, 35, 34, 32, 30, 32, 38, 45, 52, 58, 62, 65, 
+case.schedules['price'] = [38, 35, 34, 32, 30, 32, 38, 45, 52, 58, 62, 65,
                             68, 65, 62, 58, 55, 60, 75, 82, 78, 65, 50, 42]
 
 # Run OPF minimizing energy cost
@@ -227,10 +289,15 @@ print(f"Total energy cost: ${result.objective_value:.2f}")
 
 ### Result Fields
 
-`PowerFlowResult` uses descriptive field names. Short aliases are also accepted for backward compatibility.
+`PowerFlowResult` uses descriptive field names. Short aliases are also accepted for backward compatibility. Fields are optional: availability depends on the analysis, backend, case devices, and requested options.
+
+Core fields include `voltages`/`voltage_magnitudes`, `voltage_angles`, active and reactive power flows, active and reactive generation, and active and reactive loads. FBS results provide `voltage_angles`, `currents`, and `current_angles` (angles are in degrees); these fields can also be present when another backend has computed them.
+
+Battery and device fields include `battery_active_power`, `battery_reactive_power`, `p_charge`, `p_discharge`, and `soc`; regulator/capacitor-related fields include `tap_ratios`, `reg_taps`, `z_caps`, and `u_caps`, where supported by the selected model. `capacitor_reactive_power` is also available for capacitor outputs. Mixed-integer binary details may remain available through `raw_result` rather than the unified result fields.
 
 | Field Name | Alias |
 |---|---|
+| `voltages` | — |
 | `active_power_flows` | `p_flows` |
 | `reactive_power_flows` | `q_flows` |
 | `active_power_generation` | `p_gens` |
@@ -239,19 +306,25 @@ print(f"Total energy cost: ${result.objective_value:.2f}")
 | `reactive_power_loads` | `q_loads` |
 | `capacitor_reactive_power` | `q_caps` |
 | `battery_active_power` | `p_bats` |
-| `voltage_magnitudes` | `voltages` |
+| `battery_reactive_power` | `q_bats` |
+
+#### Plotting and Dual Variables
 
-#### Dual Variables
-When running with `duals=True`, dual variables are accessible on the result object:
+The public plotting methods return Plotly figures: `plot_voltages(t=None)`, `plot_power_flows(t=None)`, `plot_gens(t=None)`, `plot_batteries()`, `plot_schedules()`, `plot_network(v_min=0.95, v_max=1.05, show_phases="abc", show_reactive_power=False, t=None)`, `plot_voltage_vs_distance(title=..., color_by="algorithm", include_secondary_phases=False)`, and `plot_line_flow_vs_distance(power_type="active", title=..., color_by="algorithm", include_secondary_phases=False)`. Methods that require unavailable result data or a case reference raise `RuntimeError`.
+
+When running with `duals=True` using the Pyomo wrapper, dual variables are accessible on the result object. The unified names are:
 
 ```python
 result = case.run_opf(wrapper="pyomo", objective="loss", duals=True)
 result.dual_power_balance_p
 result.dual_power_balance_q
 result.dual_voltage_drop
-result.dual_voltage_limits
+result.dual_voltage_limits_lower
+result.dual_voltage_limits_upper
 ```
 
+Dual extraction is Pyomo-only; matrix and FBS results do not populate these fields.
+
 ## Using a custom model.
 Create CSVs formatted as shown below and store them in a single folder. The csv names must match exactly as shown. 
 Column order is not important. 

distopf-1.1.0.dev5/docs/solver-failure-guide.md

@@ -0,0 +1,52 @@
+# Common Solver Failure Causes
+
+This guide covers data and model-configuration conditions that can produce
+infeasible, unconstrained, or otherwise misleading solves. It is diagnostic
+guidance, not a complete solver manual: the exact symptoms and available
+options depend on the selected `Case` analysis, wrapper, formulation, and
+installed solver. Check the returned result status and error message before
+assuming that a numerical solver failure is the root cause.
+
+The examples below use the public case data tables and validation helpers. They
+do not change solver behavior or repair input data automatically.
+
+## Bus Has Phases Missing From Its Incoming Branch
+
+The model creates voltage variables from `bus_data`, but voltage-drop equations
+only connect phases present on the incoming `branch_data` row. A declared phase
+with no incoming branch phase is therefore bounded but unconstrained.
+
+Observed in the converted ieee9500_wye case:
+
+- Bus `2827`: declared `ac`, incoming `a`, unconstrained `v[2827, c]`.
+- Bus `4440`: declared `ab`, incoming `a`, unconstrained `v[4440, b]`.
+
+With a constant objective, these variables can take their lower voltage bound.
+
+Check for this condition before solving:
+
+```python
+from distopf.utils import find_unconstrained_bus_phases
+
+bad_phases = find_unconstrained_bus_phases(case.bus_data, case.branch_data)
+print(bad_phases)
+```
+
+Remove invalid bus phases or add the corresponding incoming branch phases
+before building the voltage equations. This condition is especially important
+for radial multi-phase models; a successful solver return does not by itself
+prove that every declared phase was connected by a voltage-drop equation.
+
+## Interpreting solver failures
+
+- Distinguish input validation errors, infeasibility, unbounded objectives, and
+  backend/executable availability errors; they require different fixes.
+- Confirm that the requested wrapper and formulation support the requested
+  objective and controls. Matrix, Matrix BESS, Pyomo, and FBS expose different
+  capabilities and result fields.
+- For Pyomo nonlinear or discrete formulations, check the selected solver and
+  initialization options separately from the network data. For multi-period
+  cases, also check schedules, time-step bounds, and battery limits.
+- Preserve the original case and solver logs when reporting a failure. A
+  minimal reproduction with the case path, wrapper/formulation, objective,
+  control flags, and relevant options is more useful than a traceback alone.

{distopf-1.1.0.dev3 → distopf-1.1.0.dev5}/examples/README.md

@@ -3,8 +3,12 @@
 This directory contains a comprehensive set of examples showing how to use DistOPF
 for various optimal power flow (OPF) problems, organized by topic.
 
-Some examples are Marimo notebooks. To use these, run `marimo edit`. Marimo will
-open the browser and list the available notebooks.
+Most `.py` files in this directory are ordinary Python scripts. Run them from the
+repository root with, for example, `uv run examples/tutorials/01_simple_power_flow.py`.
+Some files are Marimo apps (marked `Marimo` in the tables below); open one with
+`uv run marimo edit examples/basics/basic_power_flow_examples.py` or start Marimo
+and select the file in its browser UI. A Marimo app is edited/run through Marimo,
+not executed as a plain script when interactive cells are required.
 
 ## Directory Structure
 
@@ -21,12 +25,16 @@ examples/
 
 ## How to Run Examples
 
-Each example is standalone and can be run independently:
+Each ordinary script is standalone and can be run independently:
 
     uv run examples/tutorials/01_simple_power_flow.py
-    uv run examples/pyomo/build_your_own_opf.py
+    uv run examples/pyomo/pyomo_multiperiod.py
     uv run examples/data_import/cim_example.py
 
+For a Marimo app, use Marimo's editor instead:
+
+    uv run marimo edit examples/basics/basic_power_flow_examples.py
+
 ---
 
 ## `tutorials/` — Start Here
@@ -129,8 +137,8 @@ Performance benchmarking, distributed algorithms, and experimental scripts.
 
 **Objective**
   The goal of optimization:
-  - `"loss_min"`: Minimize real power losses
-  - `"voltage_dev"`: Minimize voltage deviations
+  - `"loss_min"` (or `"loss"`): Minimize real power losses
+  - `"voltage_deviation"`: Minimize voltage deviations (Pyomo)
 
 **Control Variable**
   What DERs (generators, batteries, inverters) are allowed to control:
@@ -141,9 +149,14 @@ Performance benchmarking, distributed algorithms, and experimental scripts.
 
 **Wrapper / Formulation**
   Which optimization engine to use:
-  - `"matrix"`: CVXPY + CLARABEL (fast, convex problems)
-  - `"pyomo"`: Pyomo + IPOPT (flexible, nonlinear problems; supports `model_type="branchflow"` for exact NLP)
-  - `"matrix_bess"`: Multi-period with batteries (CVXPY + CLARABEL)
+  - `"matrix"`: Single-period matrix LinDistFlow models using CVXPY/SciPy backends
+  - `"pyomo"`: Pyomo models using `formulation="lindist"`, `"branchflow"`, or `"socp"`
+  - `"matrix_bess"`: Multi-period matrix models with batteries and schedules
+
+`model_type` is an internal wrapper/model-selection term; public users should
+prefer `Case.run_opf(formulation=...)` and the public `Case` APIs rather than
+constructing wrapper classes directly. `formulation="branchflow"` selects the
+nonlinear Pyomo model; it is not an argument named `model_type` on `run_opf()`.
 
 **Results**
   After solving, you get:
@@ -175,5 +188,5 @@ Performance benchmarking, distributed algorithms, and experimental scripts.
 ## Resources
 
 - [Project README](../README.md): Project overview
-- `src/distopf/wrappers/base.py`: Wrapper API documentation
+- [`src/distopf/wrappers/base.py`](../src/distopf/wrappers/base.py): Internal/advanced wrapper base reference; ordinary users should start with the public `Case` APIs in [`src/distopf/api.py`](../src/distopf/api.py)
 - `tests/`: Unit tests with more detailed usage patterns

distopf-1.1.0.dev5/examples/cli/example_ieee123_30der.toml

@@ -0,0 +1,14 @@
+# Minimal user-authored DistOPF scenario.
+# Paths are resolved relative to this file.
+
+[case]
+path = "../../src/distopf/cases/csv/ieee123_30der"
+
+[analysis]
+type = "opf"
+objective = "loss"
+
+# Optional: save results and the generated run_config.json here.
+[output]
+directory = "../../scratch/example_results_ieee123_30der"
+

distopf-1.1.0.dev5/examples/cli/example_ieee123_bat.toml

@@ -0,0 +1,16 @@
+# Minimal user-authored DistOPF scenario.
+# Paths are resolved relative to this file.
+
+[case]
+path = "../../src/distopf/cases/csv/ieee123_bat"
+n_steps = 24
+start_step = 0
+
+[analysis]
+type = "opf"
+objective = "loss"
+
+# Optional: save results and the generated run_config.json here.
+[output]
+directory = "../../scratch/example_results_ieee123_bat"
+

distopf-1.1.0.dev5/examples/cli/example_ieee13.toml

@@ -0,0 +1,31 @@
+# Minimal user-authored DistOPF scenario.
+# Paths are resolved relative to this file.
+
+[case]
+path = "../../src/distopf/cases/csv/ieee13"
+
+[analysis]
+type = "opf"
+objective = "loss"
+
+# Optional: save results and the generated run_config.json here.
+[output]
+directory = "../../scratch/example_results"
+
+# For ENAPP or ADMM, use this form instead:
+# [analysis]
+# type = "enapp"
+# objective = "loss"
+# parallel = false
+
+# [analysis.area_info.area1]
+# up_areas = []
+# down_areas = ["area2"]
+# up_buses = ["sourcebus"]
+# down_buses = ["632"]
+
+# [analysis.area_info.area2]
+# up_areas = ["area1"]
+# down_areas = []
+# up_buses = ["632"]
+# down_buses = []