Model Hierarchy

[rb004f]

We have a software engineering challenge centered around having essentially three different modeling choices

1) Mathematical Model, i.e. MINLP or MISCOP, etc.

2) Direction, i.e. whether or not the flow directions are fixed or not

3) Pipeflow physics, i.e. Hazen-Williams or Darcy-Weichbach

At the moment, the code is controlling these choices via if/then/else statements. I suggest we control these choices based on typing the the model. GasModels has already done this for the equivalents of 1) and 2) using types and union operators - see https://github.com/lanl-ansi/GasModels.jl

Thus, I suggest the following hierarchy

AbstractWaterFormulation - top level formulation object, all common constraints/variables/etc. are defined at this level, equivalent of AbstractGasFormulation in https://github.com/lanl-ansi/GasModels.jl/blob/master/src/core/base.jl

AbstractDirectedWaterFormulation <: AbstractWaterFormulation and AbstractUndirectedWaterFormulation <: AbstractWaterFormulation - defines formulation types for directed vs. undirected, This is like AbstractDirectedGasFormulation and AbstractUndirectedGasFormulation in https://github.com/lanl-ansi/GasModels.jl/blob/master/src/core/base.jl

AbstractDarcyWeisbachWaterFormulation <: AbstractWaterFormulation and AbstractHazenWilliamsWaterFormulation <: AbstractWaterFormulation - defines formulation types for Hazen Williams and Darcy Weisbach

Now, I suggest we use the union operator to combine the formulations into types

i.e. AbstractHazenWilliamsDirectedForm = Union{AbstractHazenWilliamsWaterFormulation, AbstractDirectedWaterFormulation}

This will then allow you defined the mathematical objects on the form of the model, i.e. for MINLPs, you will have things like

"" @compat abstract type AbstractMINLPHazenWilliamsDirectedForm <: AbstractHazenWilliamsDirectedWaterFormulation end

"" @compat abstract type StandardMINLPHazenWilliamsDirectedForm <: AbstractMINLPHazenWilliamsDirectedForm end

See https://github.com/lanl-ansi/GasModels.jl/blob/master/src/form/minlp.jl for an example.

If you run into situations where combinations of the modeling choices share common code, you can use the union operator to combine types.

See for example AbstractMINLPForms = Union{AbstractMINLPDirectedForm, AbstractMINLPForm} in GasModels. - this is used for MINLP features that don't care if the model is directed or undirected.

At the end of the day, the only thing that really differs across all three combinations of modeling choices is the pipeflow equations, and this will allow us to switch between them through the definition of the mathematical form.

[ccoffrin]

Concerning these three points, 1) Mathematical Model, i.e. MINLP or MISCOP, etc. 2) Direction, i.e. whether or not the flow directions are fixed or not 3) Pipeflow physics, i.e. Hazen-Williams or Darcy-Weichbach

Following the lessons from PowerModels I would recomend: (1) be solved with a model types; (2) be handed with different problem specifications, not types; (3) I am inclined to say this should also be different problem specifications as well, but it might also be reasonable to do with types. I would need to discuss the differences in the physics.

[tasseff]

Concerning (2), I think this should be done through problem specification, not type. This is primarily because there may be occasions where it is useful to assume fixed directions for a only a subset of flow variables.

Concerning (3), I think this should also be handled via problem specification. Otherwise, the model will need to be constructed with the proper type after inspection of the friction formulation being used, as specified by the user's input file. We could, of course, read in the input data, then make this choice, but that seems to diverge from the way PowerModels and GasModels models are constructed.

[rb004f]

I am open to discussion on how we engineer this. I would prefer to keep conditional statements out of the definitions of the constraints and variables. (i.e. if darcy do this. if directed do this). So, I'd like to see separate functions for each of these definitions. Then it can be the responsibility of the problem definition or type definition to determine which function to call.

In other words, I don't think the determination of the directed vs undirected etc should live in the data, rather that should be defined in the model type or problem definition. Maybe we can discuss this afternoon?

[tasseff]

Regarding our discussion today, the following decisions were made:

1) Mathematical models will be typed. 2) Direction will be specified through the data model. Separate sets of directed and undirected edges will be maintained in ref. These sets will be looped over in the corresponding model post method, where different constraints will be applied within each loop. 3) The physical model used (i.e., Hazen-Williams or Darcy-Weisbach) will be typed.

[rb004f]

Just to clarify, on #3, these will be typed at the problem specification level, i.e. having something like post_wf_hw and post_wf_dw

[ccoffrin]

I second @rb004f's remark.