Choose your tutorial

The sidebar follows the workflow from understanding network data to preparing, solving, and verifying a case. Advanced explanations, automation, and reference material provide separate routes. This page helps you choose by goal; the homepage learning map shows how the sections connect. Choose an advanced route for equation encodings, model extensions and numerical experiments.

If you are new, follow Installation & first steps, then First case: inspect, solve and verify. The first case uses a bundled synthetic feeder and needs no external data. You can stop after inspection if you do not need a solver yet.

The utility-data end-to-end tutorial is a later, optional route. Its external dataset and license requirements are stated at the start of that page; its dataset examples are not executed by the docs build.

Route by goal

I want to…	Start here	Then
Explore a network visually in the browser	Visualizing a case with Tellegen	Analysis & reports, Buses & terminals primer
Convert OpenDSS into a BMOPF case	Conversion guide	Analysis & reports, Utility-data end-to-end tutorial
Derive model inputs from nameplate data	From nameplate data to a defensible model	Case augmentation, Data model conventions
Triage a messy import (warnings, provenance, repairs)	Findings triage	Finding-code reference, Analysis & reports
Turn transformer test data into model fields	From test report to transformer model	Transformer models, Transformer spec
Understand four-wire physics (why terminals, neutrals, matrices)	Buses & terminals primer	Impedance models & OPF decisions, Line geometry
Get grounding, neutrals, and sequence coordinates right	Ground, neutral, and earth return	Grounding spec, SWER case study
Get units, per-unit bases, and cost right	Units, bases, scaling, and economics	Units and scaling, Objective spec
Pick a defensible load model (CVR, hosting, collapse)	Choosing and identifying a load model	Load spec, Impedance models & OPF decisions
Build a benchmark an optimizer can respect	Case augmentation	From nameplate data to a defensible model, DER placement
Diagnose an infeasible case	Infeasibility diagnosis	Bounds & feasibility, Trusting the solver
Verify a solved OPF you don't yet trust	Trust but verify	Solution projection, Engine validation evidence
Model a specific device (STATCOM, MVDC, regulator, PV droop)	D-STATCOM study	MVDC, Tap optimization, VVWO
Change the formulation (custom objectives, constraints, multi-period)	Custom formulations	OPF model, Units, bases & economics
Assemble a network matrix or understand ideal-device boundaries	Nodal admittance builders	Exact substitutions, Engine validation evidence
Choose numerical coordinates or inspect initialization	Scaling, initialization and diagnostics	Solver guide, Trusting the solver
Update coefficients and re-solve safely	Repeated solves	Case families, Model extensions
Build a differentiable or bilevel research extension	Model extensions and sensitivities	Custom formulations, OPF engine
Extend or debug the solver	OPF engine: scope & status	OPF model, Contributing

The judgment spine

Six of the tutorials, read in order, teach the reasoning a defensible study needs — not just how to call the tools, but when to trust the answer:

Triage — Findings triage. A raw import arrives with dozens of findings; learn to separate defects (fix), judgment calls (decide and document), and disclosures (keep — they are the case's provenance record).
Assumptions — From nameplate data to a defensible model. Incomplete datasheets in; a model out. What can be derived, what needs an assumption, and what must stay unknown — and the difference between standards-derived, standards-inspired, and synthetic values.
Solve — First case and Developing OPF case families. Solve a supplied operating case, then compare explicit study scenarios.
Verify — Trust but verify. Take one solved OPF and independently recompute KCL, voltage bounds, thermal loading, losses, and the objective — learning what a solver's LOCALLY_SOLVED status does and does not guarantee.
Consequences — Impedance models & OPF decisions and Trusting the solver. How the modeling choices made in step 2 change the answer, and where the remaining traps live.
Formulation — Custom formulations. When least-cost dispatch is not your question: hooks, replaced objectives, and multi-period coupling — with the discipline each rung demands.

Read top to bottom you get the missing arc: triage → model assumptions → solve → independent verification → fidelity consequences → your own formulation.

The modeling-choices track

Step 2's "assumptions" fan out into deep dives, one per modeling choice — each demonstrating live how that choice writes the answer:

Units, bases, scaling, and economics — the three unit systems every result rests on.
Impedance models & OPF decisions — network fidelity, symmetry, and what balanced models hide.
Choosing and identifying a load model — when constant-P/I/Z, ZIP, or exponential behavior is defensible.
From test report to transformer model — test data into validated fields, with the conventions made explicit.
Ground, neutral, and earth return — grounding assumptions, Kron reduction, and sequence coordinates.

Prerequisites and example coverage

Route	Software and data
First case, inspection steps	BMOPFTools and the bundled feeder; no solver or external dataset.
First case, solve and verify steps	BMOPFTools, JuMP and Ipopt; the same bundled feeder.
Nodal admittance builders	BMOPFTools and Julia standard libraries; synthetic examples run in the docs build.
DiffOpt worked example	Repository checkout and the optional `test/diffopt` environment (DiffOpt, JuMP, Ipopt); executed by the optional integration test job.
Case families	BMOPFTools, JuMP and Ipopt; the bundled feeder and example script.
Utility-data tutorials, including end-to-end, DER placement and PV controls	Follow each page's external-dataset notice and software prerequisites. Reading a page does not require acquiring its data.

The first-case Julia blocks execute during the docs build. Utility-data examples marked External dataset are displayed as code and are not executed by that build. Other pages state their own prerequisites; a data-modeling tutorial may also run a solve to demonstrate the consequences of a modeling choice.

For the advanced smooth-droop encoding note, start with the PV control study for the practical context, or read Power-flow inverter controls for the solver interface. Running the external-data study is not required to read the note.