distopf 1.1.0.dev2__tar.gz → 1.1.0.dev4__tar.gz

{distopf-1.1.0.dev2 → distopf-1.1.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: distopf
-Version: 1.1.0.dev2
+Version: 1.1.0.dev4
 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>
@@ -104,6 +104,47 @@ result = case.run_opf(objective="curtail_min", control_variable="P", v_max=1.05,
 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.
+
+```python
+area_info = {
+    "area1": {
+        "up_areas": [],
+        "down_areas": ["area2"],
+        "up_buses": ["sourcebus"],
+        "down_buses": ["632"],
+    },
+    "area2": {
+        "up_areas": ["area1"],
+        "down_areas": [],
+        "up_buses": ["632"],
+        "down_buses": [],
+    },
+}
+case = opf.create_case(opf.CASES_DIR / "csv" / "ieee13")
+result = case.run_enapp(
+    area_info=area_info,
+    objective="substation_power",
+    parallel=True,
+    max_iterations=25,
+)
+```
+
+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:1140):
+
+```python
+result.save("results/ieee13-enapp")
+replayed = opf.replay("results/ieee13-enapp/run_config.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.
+
+
+
 ## Optimization Wrappers
 
 DistOPF supports multiple optimization wrappers for solving OPF problems:
@@ -129,6 +170,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:
 
@@ -171,7 +233,7 @@ 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 |
+| Model Type | LinDistFlow (linear) | LinDistFlow, BranchFlow, or SOCP-relaxed BranchFlow |
 | Formulation | Matrix-based | Algebraic equations |
 | Solver API | Scipy or CVXPY | Pyomo |
 | Prefered Solver | HiGHs or Clarabel | IPOPT, Gurobi, Knitro |
@@ -189,7 +251,7 @@ DistOPF supports multiple optimization objectives for distribution system OPF:
 | **Substation Power** | `"substation"`, `"substation_power"` | Pyomo, Matrix | 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 |
+| **Cost Minimization** | `"cost"`, `"cost_min"` | Pyomo (LinDistFlow, BranchFlow, SOCP) | Minimize energy procurement cost from swing bus |
 
 #### Cost Minimization with Price Data
 

{distopf-1.1.0.dev2 → distopf-1.1.0.dev4}/README.md

@@ -80,6 +80,47 @@ result = case.run_opf(objective="curtail_min", control_variable="P", v_max=1.05,
 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.
+
+```python
+area_info = {
+    "area1": {
+        "up_areas": [],
+        "down_areas": ["area2"],
+        "up_buses": ["sourcebus"],
+        "down_buses": ["632"],
+    },
+    "area2": {
+        "up_areas": ["area1"],
+        "down_areas": [],
+        "up_buses": ["632"],
+        "down_buses": [],
+    },
+}
+case = opf.create_case(opf.CASES_DIR / "csv" / "ieee13")
+result = case.run_enapp(
+    area_info=area_info,
+    objective="substation_power",
+    parallel=True,
+    max_iterations=25,
+)
+```
+
+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:1140):
+
+```python
+result.save("results/ieee13-enapp")
+replayed = opf.replay("results/ieee13-enapp/run_config.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.
+
+
+
 ## Optimization Wrappers
 
 DistOPF supports multiple optimization wrappers for solving OPF problems:
@@ -105,6 +146,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:
 
@@ -147,7 +209,7 @@ 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 |
+| Model Type | LinDistFlow (linear) | LinDistFlow, BranchFlow, or SOCP-relaxed BranchFlow |
 | Formulation | Matrix-based | Algebraic equations |
 | Solver API | Scipy or CVXPY | Pyomo |
 | Prefered Solver | HiGHs or Clarabel | IPOPT, Gurobi, Knitro |
@@ -165,7 +227,7 @@ DistOPF supports multiple optimization objectives for distribution system OPF:
 | **Substation Power** | `"substation"`, `"substation_power"` | Pyomo, Matrix | 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 |
+| **Cost Minimization** | `"cost"`, `"cost_min"` | Pyomo (LinDistFlow, BranchFlow, SOCP) | Minimize energy procurement cost from swing bus |
 
 #### Cost Minimization with Price Data
 

distopf-1.1.0.dev4/examples/advanced/TEMPORAL_README.md

@@ -0,0 +1,249 @@
+"""
+Temporal Decomposition Examples README
+
+This directory contains examples demonstrating the use of TENAPP (Temporal 
+Alternating/Approximate/ADMM-based Multi-period OPF) algorithms for solving 
+multi-period optimal power flow problems using temporal decomposition.
+
+## Background
+
+Temporal decomposition breaks a large multi-period OPF problem into smaller 
+per-time-step subproblems, which are solved iteratively while coordinating 
+through battery state-of-charge (SOC) constraints. This approach is useful for:
+
+- Large time horizons (many hours/days)
+- Limited computational resources
+- Distributed optimization
+- Privacy-preserving solutions
+
+## Files
+
+### 1. run_temporal_quick.py
+**Simplest example - 6 lines of solving code**
+
+- Loads IEEE 123-bus network with 6-hour horizon
+- Sets realistic energy prices
+- Solves with TENAPP-1O algorithm
+- Prints results
+
+**Run with:**
+```bash
+uv run examples/advanced/run_temporal_quick.py
+```
+
+**Use when:** You just want to get started quickly
+
+### 2. run_temporal_tenapp.py
+**Comprehensive example - All three algorithms in detail**
+
+- Loads multi-period case (4 time steps)
+- Configures battery parameters
+- Runs all three algorithms:
+  - TENAPP-1O (first-order method)
+  - TENAPP-APRX (approximate dual method)
+  - TENAPP-ADMM (ADMM-based method)
+- Generates detailed comparison CSV
+- Extracts and displays battery dispatch
+- Shows convergence iteration histories
+
+**Run with:**
+```bash
+uv run examples/advanced/run_temporal_tenapp.py
+```
+
+**Output files:**
+- `scratch/temporal_results/temporal_results_summary.csv` - Algorithm comparison
+- `scratch/temporal_results/tenapp_*o_iterations.csv` - Iteration details per algorithm
+- `scratch/temporal_results/*.csv` - Full results
+
+**Use when:** You want to understand algorithm behavior and compare performance
+
+### 3. run_temporal_comparison.py
+**Advanced example - Flexible comparison framework**
+
+- Creates configurable multi-period cases
+- Sets dynamic pricing signals with peak hours
+- Runs comparison with custom parameters
+- Generates detailed analysis:
+  - Cost breakdown
+  - Convergence metrics
+  - Battery scheduling
+  - Iteration timings
+- Saves all results to CSV for further analysis
+
+**Run with:**
+```bash
+uv run examples/advanced/run_temporal_comparison.py
+```
+
+**Key features:**
+- Modular functions for reuse
+- Configurable number of time steps
+- Dynamic pricing scenarios
+- Comprehensive spreadsheet outputs
+
+**Use when:** You want to run parameter studies and custom scenarios
+
+## Core Algorithms
+
+### TENAPP-1O (First-Order)
+```python
+from distopf.distributed.temporal import solve_tenapp_1o
+result = solve_tenapp_1o(case, objective=energy_cost_min, max_iterations=20)
+```
+
+**Pros:**
+- Simple dual-based coordination
+- Direct interpretation of price signals
+- Good for reactive dispatch
+
+**Cons:**
+- May need many iterations
+- Sensitive to convergence tolerance
+
+### TENAPP-APRX (Approximate Dual)
+```python
+from distopf.distributed.temporal import solve_tenapp_aprx
+result = solve_tenapp_aprx(case, objective=energy_cost_min, alpha2=0.33, alpha3=0.33)
+```
+
+**Pros:**
+- Gradient-based dual estimates
+- Good practical performance
+- Tunable approximation accuracy
+
+**Cons:**
+- Hyperparameters (alpha2, alpha3) may need tuning
+- Approximation may not be exact
+
+### TENAPP-ADMM (ADMM-based)
+```python
+from distopf.distributed.temporal import solve_tenapp_admm
+result = solve_tenapp_admm(case, objective=energy_cost_min, weight=1e2)
+```
+
+**Pros:**
+- Provable convergence under certain conditions
+- Natural dual variable updates
+- Adaptable penalty weights
+
+**Cons:**
+- Requires careful weight selection
+- More computationally intensive per iteration
+
+## Common Output Fields
+
+All algorithms return a dictionary with:
+
+```python
+result = {
+    "models": [list of LinDistMPL per-time-step models],
+    "results": [list of OptimizeResult per time step],
+    "iterations": int,                        # Iterations to convergence
+    "converged": bool,                        # Whether algorithm converged
+    "total_cost": float,                      # Sum of per-time-step costs ($)
+    "solve_time": float,                      # Total solve time (seconds)
+    "iteration_summaries": pd.DataFrame,      # Iteration-by-iteration details
+}
+```
+
+## Common Parameters
+
+```python
+solve_tenapp_*(
+    case,                          # distopf.Case object (n_steps > 1)
+    objective=energy_cost_min,     # Objective function
+    max_iterations=100,            # Max coordination iterations
+    tolerance=1e-3,                # Convergence tolerance
+    parallel=False,                # Parallel per-time-step solves
+    cost_curve=np.array([...]),    # Hourly electricity prices ($/MWh)
+    solver="CLARABEL",             # CVXPY solver (CLARABEL, SCS, MOSEK, etc.)
+)
+```
+
+## Setting Up a Case
+
+```python
+import distopf as opf
+import numpy as np
+
+# Create multi-period case
+case = opf.create_case(
+    opf.CASES_DIR / "csv" / "ieee123_30der_bat",
+    n_steps=6,                    # 6-hour horizon
+    start_step=0,
+)
+
+# Configure voltage limits
+case.bus_data.v_max = 1.05
+case.bus_data.v_min = 0.95
+
+# Configure generator control mode
+case.gen_data.control_variable = "PQ"  # Active and reactive power
+
+# Configure battery parameters
+case.bat_data.control_variable = "P"   # Active power control only
+case.bat_data["start_soc"] = 0.5       # 50% initial SOC
+case.bat_data["max_soc"] = 0.9         # 90% max SOC
+
+# Define hourly electricity costs
+cost_curve = np.array([50, 50, 80, 90, 70, 45])  # $/MWh for each hour
+```
+
+## Analyzing Results
+
+```python
+# Check convergence
+if result["converged"]:
+    print(f"Solved in {result['iterations']} iterations")
+    print(f"Total cost: ${result['total_cost']:.2f}")
+else:
+    print(f"Did not converge after {result['iterations']} iterations")
+
+# View iteration history
+print(result["iteration_summaries"])
+
+# Extract battery dispatch from first time step
+model_t0 = result["models"][0]
+optim_result_t0 = result["results"][0]
+p_batt = model_t0.get_p_batt(optim_result_t0.x)
+soc = model_t0.get_soc(optim_result_t0.x)
+```
+
+## Performance Tips
+
+1. **Start small**: Begin with short horizons (4-6 hours) before scaling up
+2. **Set tolerances carefully**: Looser tolerance (1e-2) = faster, stricter (1e-5) = more accurate
+3. **Choose algorithm wisely**: 
+   - 1O for first quick solve
+   - APRX for practical implementations
+   - ADMM for convergence guarantees
+4. **Adjust weights**: ADMM weight scaling affects convergence speed
+5. **Use realistic pricing**: Include peak hours and time-of-use rates
+6. **Monitor iterations**: Check if converging monotonically or oscillating
+
+## Troubleshooting
+
+**Algorithm doesn't converge:**
+- Increase `max_iterations`
+- Loosen `tolerance` (use 1e-2 instead of 1e-4)
+- Check if case is feasible with `opf.run_opf(case, objective="loss_min")`
+
+**Very slow iterations:**
+- Disable solver verbosity in CVXPY
+- Use `parallel=True` if multi-core available
+- Try different solver (SCS faster on some problems, MOSEK more robust)
+
+**Inconsistent results:**
+- Check battery efficiency settings
+- Verify cost curve values are reasonable
+- Ensure schedules/loads are properly formatted
+
+## References
+
+For detailed algorithm descriptions, see parent documentation in:
+- `distopf.distributed.temporal.solve_tenapp_1o`
+- `distopf.distributed.temporal.solve_tenapp_aprx`
+- `distopf.distributed.temporal.solve_tenapp_admm`
+
+"""

distopf-1.1.0.dev4/examples/advanced/debug_enapp_123.py

@@ -0,0 +1,87 @@
+from pathlib import Path
+
+import pandas as pd
+
+import distopf as opf
+from distopf.distributed.spatial.decompose import decompose
+from distopf.distributed.spatial.enapp import solve_enapp
+
+AREA_INFO = {
+    "area1": {
+        "up_areas": [],
+        "down_areas": ["area2", "area3"],
+        "up_buses": ["150"],
+        "down_buses": ["152", "135"],
+    },
+    "area2": {
+        "up_areas": ["area1"],
+        "down_areas": ["area4"],
+        "up_buses": ["152"],
+        "down_buses": ["160"],
+    },
+    "area3": {
+        "up_areas": ["area1"],
+        "down_areas": [],
+        "up_buses": ["135"],
+        "down_buses": [],
+    },
+    # Assumption: area4 is a leaf area under area2.
+    "area4": {
+        "up_areas": ["area2"],
+        "down_areas": [],
+        "up_buses": ["160"],
+        "down_buses": [],
+    },
+}
+
+OUTPUT_DIR = Path("scratch/enapp_123_debug")
+PHASES = ("a", "b", "c")
+
+
+def _voltage_row(result, bus_name: str) -> pd.Series:
+    row = result.voltages.loc[
+        result.voltages.name.astype(str) == str(bus_name), ["name", "t", "a", "b", "c"]
+    ]
+    if row.empty:
+        raise ValueError(f"Missing voltage row for bus {bus_name}")
+    return row.iloc[0]
+
+
+def _power_row(result, to_bus: str) -> pd.Series:
+    flows = result.active_power_flows.merge(
+        result.reactive_power_flows,
+        on=["fb", "tb", "from_name", "to_name", "t"],
+        suffixes=("_p", "_q"),
+    )
+    row = flows.loc[flows.to_name.astype(str) == str(to_bus)]
+    if row.empty:
+        raise ValueError(f"Missing power-flow row for boundary bus {to_bus}")
+    return row.iloc[0]
+
+
+def _write_table(df: pd.DataFrame, file_name: str) -> None:
+    df.to_csv(OUTPUT_DIR / file_name, index=False)
+
+
+def main() -> None:
+    case = opf.create_case(
+        opf.CASES_DIR / "csv" / "ieee123_30der",
+        n_steps=1,
+        ignore_schedule=True,
+        ignore_gen=True,
+        ignore_bat=True,
+    )
+    case.modify(control_variable="", v_max=1.06)
+    central = case.run_opf()
+
+    sources = {area_name: data["up_buses"][0] for area_name, data in AREA_INFO.items()}
+    subcases = decompose(case, sources)
+    r4 = subcases["area4"].run_opf()
+
+    result_enapp = solve_enapp(
+        case, AREA_INFO, objective="min_loss", tol=1e-3, parallel=False
+    )
+
+
+if __name__ == "__main__":
+    main()

{distopf-1.1.0.dev2 → distopf-1.1.0.dev4}/examples/advanced/run_enapp.py

@@ -1,17 +1,10 @@
-import multiprocessing as mp
-from copy import deepcopy
-from pathlib import Path
-import numpy as np
-import pandas as pd
 import distopf as opf
-from distopf.matrix_models.matrix_bess.solvers import cvxpy_solve
-from distopf.matrix_models.matrix_bess.lindist_loads_mp import LinDistMPL
 from distopf.matrix_models.matrix_bess.lindist_mp import LinDistMP
 from distopf.matrix_models.matrix_bess.objectives import cp_obj_cost_min
-from distopf.matrix_models.matrix_bess.spatial_decomposition.enapp import solve_enapp
+
+from distopf.distributed.spatial.enapp import solve_enapp
 from distopf.api import create_case
 from distopf import CASES_DIR
-import plotly.express as px
 import cvxpy as cp
 
 
@@ -30,7 +23,7 @@ def main():
     m = LinDistMP(case=case)
     m.build()
     # plot_network(m).show()
-    area_info_ = {
+    area_info = {
         "area1": {
             "up_areas": [],
             "down_areas": ["area2", "area3"],
@@ -51,41 +44,36 @@ def main():
         },
     }
 
-    # area_models = decompose(m, sources)
-    result_c = cvxpy_solve(
-        m,
-        cp_obj_cost_min,
+    result_c = case.run_opf(
+        objective=cp_obj_cost_min,
         solver=cp.CLARABEL,
         demand_charge=demand_charge,
         cost_curve=case.schedules.price.to_numpy(),
+        formulation="lindist_mp",
     )
-    print(result_c.fun, " in ", result_c.runtime)
+    print(result_c.objective_value, " in ", result_c.solve_time)
     result_enapp = solve_enapp(
-        m,
-        area_info_,
+        case,
+        area_info,
         tol=1e-6,
         solver=cp.CLARABEL,
         objective=cp_obj_cost_min,
         demand_charge=demand_charge,
         cost_curve=case.schedules.price.to_numpy(),
+        formulation="lindist_mp",
     )
-    print(result_enapp.fun)
-
-    def at_time(df: pd.DataFrame, t):
-        names = [name for name in df.columns if name != "t"]
-        _df = deepcopy(df.loc[df.t == t, names])
-        return _df
+    print(result_enapp.objective_value)
 
-    v_d = m.get_voltages(result_enapp.x)
-    v_c = m.get_voltages(result_c.x)
-    print(m.get_q_gens(result_enapp.x))
-    print(m.get_q_gens(result_c.x))
+    v_d = result_enapp.voltages
+    v_c = result_c.voltages
+    print(result_enapp.q_gens)
+    print(result_c.q_gens)
 
     opf.compare_voltages(v_c, v_d, t=12).show(renderer="browser")
     opf.compare_voltages(v_c, v_d, t=13).show(renderer="browser")
     # np.savetxt("copf33x.csv", result_c.x)
     # np.savetxt("dopf33x.csv", result_enapp.x)
-    px.scatter(result_c.x - result_enapp.x).show(renderer="browser")
+    # px.scatter(result_c.x - result_enapp.x).show(renderer="browser")
     print()