Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

SQLite Export

GDM-Flow can export solver results to a SQLite database for downstream analysis, archival, or integration with other tools.

Quick Start

Via CLI

gdm-flow export examples/models/p5r.json --db results.db

Via Python

from gdm_flow import (
    optimize_ac_power_flow_from_components,
    solve_dc_opf_from_components,
    solve_lindistflow,
    export_all_results_to_sqlite,
)
from gdm.distribution import DistributionSystem

system = DistributionSystem.from_json("model.json")
ac = optimize_ac_power_flow_from_components(system)
dc = solve_dc_opf_from_components(system)
ldf = solve_lindistflow(system)

export_all_results_to_sqlite(
    db_path="results.db",
    ac_result=ac,
    dc_result=dc,
    lindistflow_result=ldf,
)

Database Schema

runs

Metadata for every solver execution.

ColumnTypeDescription
run_idTEXT PKUnique run identifier (ac_<hex>, dc_<hex>, ldf_<hex>)
implementationTEXTSolver type: ac_opf, dc_opf, lindistflow
successINTEGER1 = converged, 0 = failed
messageTEXTSolver status message
created_at_utcTEXTISO 8601 timestamp

ac_opf_summary

AC OPF solver-level results.

ColumnTypeDescription
run_idTEXT PKForeign key → runs
iterationsINTEGERNumber of solver iterations
initial_objectiveREALStarting objective value
final_objectiveREALConverged objective value

ac_opf_nodes

Per-node AC OPF results (one row per bus-phase).

ColumnTypeDescription
run_idTEXTForeign key → runs
bus_nameTEXTBus name
phaseTEXTPhase label (A, B, C)
voltage_mag_vREALVoltage magnitude (V)
voltage_min_vREALMinimum voltage limit (V), when available
voltage_max_vREALMaximum voltage limit (V), when available
voltage_angle_radREALVoltage angle (radians)
p_injection_wREALActive power injection (W)
q_injection_varREALReactive power injection (var)

ac_opf_branches

Per-branch AC OPF loading and flow results (when branch loading data is available during export).

ColumnTypeDescription
run_idTEXTForeign key → runs
branch_nameTEXTBranch identifier
phaseTEXTPhase label
p_flow_wREALActive power flow from sending side (W)
q_flow_varREALReactive power flow from sending side (var)
loading_vaREALApparent loading magnitude (VA)
loading_limit_vaREALBranch loading limit (VA), when available

dc_opf_summary

DC OPF solver-level results.

ColumnTypeDescription
run_idTEXT PKForeign key → runs
objectiveREALMinimized total cost
iterationsINTEGERSolver iterations
slack_injection_wREALTotal slack bus injection (W)

dc_opf_generators

Per-generator DC OPF dispatch.

ColumnTypeDescription
run_idTEXTForeign key → runs
generator_nameTEXTGenerator identifier
dispatch_wREALOptimal dispatch (W)

dc_opf_nodes

Per-node DC OPF results.

ColumnTypeDescription
run_idTEXTForeign key → runs
bus_nameTEXTBus name
phaseTEXTPhase label
theta_radREALVoltage angle (radians)
nodal_balance_wREALNet power balance (W)

dc_opf_branches

Per-branch DC OPF loading and flow results (post-processed from solved angles).

ColumnTypeDescription
run_idTEXTForeign key → runs
branch_nameTEXTBranch identifier
phaseTEXTPhase label
p_flow_wREALApproximate active power flow (W)
q_flow_varREALReactive flow placeholder (0.0 in DC model)
loading_vaREALApparent loading proxy (abs(p_flow_w))
loading_limit_vaREALBranch loading limit (VA), when available

lindistflow_summary

LinDistFlow solver-level results.

ColumnTypeDescription
run_idTEXT PKForeign key → runs
source_busTEXTRoot bus name

lindistflow_nodes

Per-node LinDistFlow results.

ColumnTypeDescription
run_idTEXTForeign key → runs
bus_nameTEXTBus name
phaseTEXTPhase label
voltage_vREALVoltage magnitude (V)
voltage_min_vREALMinimum voltage limit (V), when available
voltage_max_vREALMaximum voltage limit (V), when available
p_net_wREALNet active power (W)
q_net_varREALNet reactive power (var)

lindistflow_branches

Per-branch LinDistFlow power flows.

ColumnTypeDescription
run_idTEXTForeign key → runs
branch_nameTEXTBranch identifier
phaseTEXTPhase label
p_flow_wREALActive power flow (W)
q_flow_varREALReactive power flow (var)
loading_vaREALApparent branch loading magnitude (VA)
loading_limit_vaREALBranch loading limit (VA), when available

voltage_violations

Persisted voltage violations generated during export for AC OPF and LinDistFlow runs.

ColumnTypeDescription
run_idTEXTForeign key → runs
implementationTEXTac_opf or lindistflow
bus_nameTEXTBus name
phaseTEXTPhase label
voltage_vREALActual voltage magnitude (V)
voltage_min_vREALConfigured minimum voltage limit (V)
voltage_max_vREALConfigured maximum voltage limit (V)
violation_vREALPositive violation magnitude (V)
violation_kindTEXTovervoltage or undervoltage

loading_violations

Persisted branch loading violations generated during export for AC OPF, DC OPF, and LinDistFlow runs.

ColumnTypeDescription
run_idTEXTForeign key → runs
implementationTEXTac_opf, dc_opf, or lindistflow
branch_nameTEXTBranch identifier
phaseTEXTPhase label
p_flow_wREALActive power flow (W)
q_flow_varREALReactive power flow (var)
loading_vaREALApparent loading magnitude (VA)
loading_limit_vaREALLoading limit (VA)
loading_pctREALLoading percent (100 * loading_va / loading_limit_va)

losses

Per-run system loss summary persisted during export.

ColumnTypeDescription
run_idTEXT PKForeign key → runs
implementationTEXTac_opf, dc_opf, or lindistflow
p_loss_wREALTotal active loss estimate (W)
q_loss_varREALTotal reactive loss estimate (var)
methodTEXTLoss computation method/assumption

Querying Results

-- Compare source power across all runs
SELECT r.implementation, r.success,
       CASE r.implementation
           WHEN 'ac_opf' THEN (SELECT SUM(p_injection_w) FROM ac_opf_nodes n
                                WHERE n.run_id = r.run_id AND n.bus_name = 'source_bus')
           WHEN 'dc_opf' THEN (SELECT slack_injection_w FROM dc_opf_summary s
                                WHERE s.run_id = r.run_id)
       END AS source_p_w
FROM runs r;

-- Get all bus voltages from the latest AC run
SELECT bus_name, phase, voltage_mag_v
FROM ac_opf_nodes
WHERE run_id = (SELECT run_id FROM runs
                WHERE implementation = 'ac_opf'
                ORDER BY created_at_utc DESC LIMIT 1)
ORDER BY bus_name, phase;

Export Functions

FunctionDescription
export_ac_opf_result_to_sqlite(result, db_path)Export a single AC OPF result
export_dc_opf_result_to_sqlite(result, db_path)Export a single DC OPF result
export_lindistflow_result_to_sqlite(result, db_path)Export a single LinDistFlow result
export_all_results_to_sqlite(db_path, ac_result, dc_result, lindistflow_result)Export all results in one call

All functions accept an optional run_id parameter; if omitted, a unique ID is auto-generated.