Skip to content

Model quality, libraries and the secondary

The model a planner will sign: where its data comes from, what is checked, and how the secondary side is drawn.

Conductors and geometries

The Line codes tab has three views. Line codes are the impedance matrices lines refer to by name. Conductors are the wires themselves (OpenDSS WireData, or CNData / TSData for a concentric-neutral or tape-shield cable): resistance, GMR, radius and ampacity in the units the conductor table gives them. Geometries (LineGeometry) hang conductors on a pole or lay them in a trench: which conductor, where (x and height), how many are phases and whether the neutral is Kron-reduced. A line's Geometry field names one; the engine then builds the impedance matrix from the conductors and their spacing with Carson's equations, and the line needs no line code and no rating of its own (the conductors carry one).

From the library… adds a conductor from config/wiredata.csv, a starter set of standard ACSR, AAC, copper and 15 kV concentric-neutral sizes with the values the standard tables publish. It is a CSV beside linecodes.csv: add the conductors your utility strings. Imported .dss files keep their wires and geometries whole, so a pole configuration can be edited after import.

Transformer catalogue

A transformer's Pick from catalogue field lists config/transformers.csv — typical pole, pad and substation units — and applies the nameplate: phases, kV, kVA, connections, impedance and losses. Edit the CSV to make it your standards list.

The 120/240 V service transformer

Tick 120/240 V centre-tapped service unit on a single-phase transformer and it compiles as the engine's single-phase three-winding form: the primary on one phase, the two secondary half-windings between leg 1 and the centre tap and the centre tap and leg 2. Downstream, a 120 V load pins to phase A (leg 1) or B (leg 2) and a 240 V load takes A-B; a triplex secondary is a two-phase line. The impedance is split the way Kersting's interlaced model does (XHL = XHT = 1.2 X, XLT = 0.8 X, %r of ½R, R, R), and 0.208 kV joins the voltage bases so the 120 V legs read 1 pu.

Model QA

Studies → Model QA is the one-click check to run on a converted model, beyond the live validation that stops a solve. It lists, per element, what a planner wants fixed: impedances still at the editor's placeholder, lengths that cannot be right for the voltage class, loads without a kW, customers or a class, voltage bases no winding matches, sources with no short-circuit strength, devices with no interrupting rating, loops in a radial feeder, normally-open breakers not marked as ties, elements out of service and elements with no place on the map. A completeness table gives the share of expected fields present per element class and an overall score; the findings export to CSV and print in the report.

Service transformers

Studies → Service transformers runs a day or a year of the loadshapes and, for every service transformer (a split-phase unit, or any with a secondary under 1 kV), reports the peak loading, the hours above 100 % and 150 % of rating, the hottest-spot temperature and the loss of insulation life by IEEE C57.91 Clause 7 (65 °C-rise unit, loss ratio 5, exponents 0.8, the ambient you give), scaled to a year; and for every load under 1 kV the lowest voltage over the run in volts on the 120 V base against 114 V at the meter (ANSI C84.1 Range A). This is where an electrification study is decided: four 7 kW chargers behind a 25 kVA transformer fail here long before anything on the primary does.

Load allocation

Analysis → Allocate loads from meter data… takes pasted CSV — billing kWh for a period, demand kW, or AMI kW intervals — matched to the loads by name, bus or class (a bus or class row splits evenly over its loads). kWh becomes kW by the hours in the period and a load factor, one for all or per class (residential=0.45, commercial=0.6); intervals become a loadshape per load, normalised to the peak that becomes the load's kW. An optional metered feeder head scales every load so the solved head power matches it (two passes, since losses move with the loads). The preview lists what matched, what did not and the head before and after; apply it as a new scenario or to the open circuit.

Adoption scenarios

Analysis → Adoption scenario… draws EV chargers, heat pumps or rooftop PV at random among the loads of a class at a given adoption rate and size, each adopter a new load (or PV system) on the parent load's bus with a built-in shape — a home Level 2 charger in the evening, a workplace charger by day, a heat pump on a cold day, a clear-day roof — or any shape of the project's. Several draws with different seeds become several scenarios, so Run all in the Scenarios tab shows the spread of outcomes. The built-in shapes are typical, not measured; replace them with a utility's own when there is one.

Growth levels

In Project properties → Load levels, Add growth levels turns a base year, a growth rate and a list of years ahead into load levels (×1.015⁵ for five years at 1.5 %), so a study year is a level like any other and the batch solves every scenario at every year.

Change log

Every parameter change is logged: when, by whom (the engineer named in the study block), which element, which parameter, from what to what, and in which scenario. Project properties shows the latest; the report's Change log section prints it all. The log is saved with the project and is not undone by Undo.

What has been checked

tests/test_m15.py holds: a geometry compiles, solves, carries its conductors' ampacity to the line and round-trips through .dss to the same voltages; a split-phase transformer serves 120 V and 240 V loads and compiles to the expected windings and impedances; the QA report finds a long line, a placeholder impedance, a default rating and a loop; the service-transformer run flags an overloaded unit with a hot spot above 110 °C and ranks the lowest meter voltage; allocation reproduces the kWh arithmetic, splits a class row evenly, makes a shape from intervals and hits a head target within 2 %; and the catalogues load with no errors.