Data Model Abstraction Refactor

[pseudocubic]

This PR contains the result of a refactor of the default user-facing data model in PowerModelsDistribution to a new ENGINEERING data model

A merge of this PR will result in the v0.9.0 release of PowerModelsDistribution

What is the New Data Model

We have designed a data model that more closely matches the engineering realities of a distribution network, that allows for easy transformation and visualization of the case and includes more component types than are represented in the original (and still existing under the hood) MATHEMATICAL data model with which previous users will be familiar.

The new data model is documented in detail in the documentation, including all of the currently supported component types are their individual fields, the types of values, and any defaults we might assume.

Why Do We Need a New Data Model?

In distribution networks the variety of components in a standard network is much more diverse than in a traditional transmission network, and their mathematical representations are comparatively complex. For example, in order to represent n-winding multiphase transformers with loss models we have to represent a single transformer with a large number of lines, buses, and lossless 2-winding transformers, which previously users have found confusing when attempting to compare their parsed network to the originating file. To simplify the user experience, and to introduce the ability to easily make transformations of the networks, we formulated the ENGINEERING data model.

How Does It Work?

For the most part, the commands that you were using before will not change appreciably. parse_file is still the standard way to import data, run_mc_ commands will still run problem specifications, and PowerModel types should not be different at all. The workflow for most users should be identical; although there are now some intermediate steps to building the JuMP model from the default data dictionary, these steps should be largely invisible to the user unless they want to expose them. Users should experience the following workflow by default:

parse_file returns ENGINEERING data model -> run_mc_{} runs optimization problem and returns result in ENGINEERING model format

What is happening behind the scenes is the following:

parse_file returns ENGINEERING data model -> run_mc_{} converts to MATHEMATICAL data model in per-unit, builds JuMP model, runs optimization, converts results in MATHEMATICAL model format to SI units and converts back to ENGINEERING format.

We have exposed to the user the functions that do these conversions if they wish to use them, and have provided examples in Jupyter Notebooks in the /examples folder that demonstrates both of these types of workflows.

If the user experience is the same, what changed besides the default model?

There were a multitude of changes that happened in order to support the functionality for this new data model, as well as some other changes that address concerns and comments of users

• We have eliminated some problem types. This is perhaps one of the biggest changes users will notice; variants of problems like run_mc_opf_iv and run_mc_opf_bf are eliminated in favor of having users use run_mc_opf only, and redirecting to the appropriate problem definitions using multiple dispatch. The only variants that should continue to exist are truly unique problem specifications, e.g. run_mc_opf_oltc or run_mc_mld, etc.
• We have changed the names of variable and constraint functions to support PowerModels v0.17
• We have updated the solution building to use the capabilities in InfrastructureModels v0.5
• We have made updates to the mathematical models for transformers to make them more accurate
• We have added new capabilities to the DSS parser, parsing additional components such as loadshapes, xycurves, xfmrcodes
• We have squashed a lot of outstanding bugs in the DSS parser
• We have ensured that the component naming conventions, particularly for virtual components in the MATHEMATICAL model, are consistent across the package
• We have added helper functions to create models from the REPL or scripts, e.g. Model, add_bus!, etc., rather than rely solely on dss inputs (see notebook in /examples)
• parse_dss originally followed a similar parsing pattern as parse_pti in PowerModels, parsing component dictionaries into Vectors. Instead, we now parse into a structure that is much closer to the final data structures that users utilize, in order to make debugging and future parsing easier
• fixed broken SDP/SOC relaxations (see fix broken SDP relaxations #262)

Feature X that I want isn't in the new data model

Definitely make a new Github Issue. We view any additions to the data model to be additive and therefore not a breaking change, which means we can make rapid releases containing those additions without any problem.

Related Issues

Closes #221
Closes #256
Closes #260
Closes #242
Closes #245
Closes #33
Closes #249
Closes #253
Closes #193
Closes #257
Closes #246
Closes #248
Closes #247
Closes #252
Closes #175
Closes #251
Closes #234
Closes #238
Closes #240
Closes #236
Closes #237
Closes #230
Closes #239
Closes #243
Closes #227
Closes #264
Closes #235
Closes #56
Closes #274

[pseudocubic]

This PR is ready for review/merge. I will leave this open until the end of next Tuesday May 12 for comments. If you have any changes that you think should be made before merge that would be breaking please make them before this time.

[sanderclaeys]

I will go through the PR this weekend.

[frederikgeth]

small comments, I may do another pass later after running the code

[sanderclaeys]

I added several figures, but they won't display until this is merged in master (@pseudocubic can you check that the path is correct? I followd the logo as an example)