Python API and command line¶
The studies are plain functions over the circuit document, and the browser is only one way to call them.
From the shell¶
opendss-designer run --list
opendss-designer run feeder.oneline.json --study solve --study qa --out results.json
opendss-designer run feeder.oneline.json --study hosting-capacity \
--options '{"method": "sensitivity", "criteria": {"deviation": false}}'
opendss-designer run feeder.dss --study reliability --level "Minimum daytime" --scenario sc1
run takes a saved project (.oneline.json) or a .dss file, runs the
named studies and writes one JSON object keyed by study name (to --out,
or stdout). --scenario and --level pick the scenario id and load
level; --options is JSON, keyed by study name when several studies run.
--list names every study with its options.
From Python¶
import json
from opendss_designer.core.model import Circuit
from opendss_designer.studies import STUDIES, run_study
circuit = Circuit.model_validate(json.load(open("feeder.oneline.json")))
hc = run_study("hosting-capacity", circuit, {"method": "sensitivity"})
for bus, r in sorted(hc["buses"].items(), key=lambda kv: kv[1]["kw"]):
print(bus, r["kw"], r["binding"])
STUDIES maps each name to (help, function). The functions and their
options are the modules of opendss_designer.studies: hosting_capacity,
screening, faults, contingency, voltvar, balancing, capacity,
secondary, allocation, protection_depth, harmonics, batch, and
the core studies engine.solve, engine.fault_study,
engine.solve_timeseries, protection.tcc_study,
reliability.reliability_study, qa.qa_report. Scenarios and load levels
are applied by studies.effective_circuit, or by setting activeScenario
and activeLevel on the circuit, as run does.
The engine is a process-wide singleton: every study runs on one engine
thread, so call them from one thread at a time. A long study accepts a
progress(done, total, message) callback and a threading.Event to
cancel.
REST¶
A running server documents its routes at /docs (OpenAPI). The long
studies are jobs: POST /api/jobs/<study> answers with a job id,
GET /api/jobs/<id>/events streams progress and the result as
server-sent events, GET /api/jobs/<id> reads it back, DELETE cancels.
GET /api/studies lists the study names.