Meta model architecture

[pelesh]

@abirchfield says:

My opinion on this "meta model" architecture:

Good things

• We need a better way to interface with various methods of I/O, which will of course include the text format but also a future GUI, custom scripts, etc. Ideally this would be a library anybody could interface with.
• It helps provide a layer with the "factory" concept where we can later implement validation, checking parameter bounds, and default values. We need this or catching data errors is going to get harder and harder.
• It would potentially help with preprocessing techniques, like partitioning. The "meta model" could be searched like a graph to find what buses are connected to what components
• The way it is currently set up for buses is pretty good, where there is one bus data type that handles data for any type of bus. (I'll explain why I think components should be done the same way.)

Not good things

• The "src/Model/PhasorDynamics" directory needs some cleanup (this is kind of a separate but related issue). Some folders like "Bus" have multiple components inside (Bus, BusInfinite), others have just a folder with one model inside (Load, which we may in the future have multiple load models), and category folders with multiple model subfolders (Synchronous Machine). The Bus-Component distinction kind of breaks down. Instead I suggest the following structure

    Buses/
        BaseBus.hpp
        BusData.hpp
        BusFactory.hpp
        Bus/
            Bus.hpp
            Bus.cpp
        BusInfinite/
            BusInfinite.hpp
            BusInfinite.cpp
        SignalBus/
            SignalBus.hpp
            SignalBus.cpp
    Components/
        BaseComponent.hpp
        ComponentData.hpp
        ComponentFactory.hpp
        SynchronousMachines/
            Genrou/
                Genrou.hpp
                Genrou.cpp
            Gensal/
                Gensal.hpp
                Gensal.cpp
            GenClassical/
                GenClassical.hpp
                GenClassical.cpp
        Loads/
            LoadZ/
                LoadZ.hpp
                LoadZ.cpp
        Branches/
            PiBranch/
                PiBranch.hpp
                PiBranch.cpp
        Exciters/
            IeeeT1/
                IeeeT1.hpp
                IeeeT1.cpp
            Esst4a/
                Esst4a.hpp
                Esst4a.cpp
        Events/
            BusFault/
                BusFault.hpp
                BusFault.cpp

Here I set it up with Buses and Components separate, and then components further divided into categories, and then one folder per bus class or component class. Of course I left out all the cmake and doc files.

• With the current setup each new component class is going to have huge overhead to implement. For example, we would need to do
  1. the model code itself [listing all parameters]
  2. the model header [listing all parameters]
  3. the model data header [listing all parameters]
  4. the code within the factory to create the model [listing all parameters]
  5. the code in the file parser to create the data object [listing all parameters].
• Instead, we should just keep the parameters as generic (string, double) pairs until we are ready to create the model component. The file parser does not need to know anything about the parameters. For each component it just needs to save a std::string class_name, std::vector<int> terminal_bus_numbers, and std::map<std::string, double> params (kind of like the file format). Then the ComponentFactory will map the class_name to the correct object, find the buses referenced by terminal_bus_numbers to connect it to, and then initialize the object with the params argument. The code for validating and correcting the parameters, and putting them into class variables, could then live inside the component itself. I am just thinking forward to having hundreds of component classes to support and having component-specific code all over the place.

Originally posted by @abirchfield in #138 (comment)

[pelesh]

With the current setup each new component class is going to have huge overhead to implement. For example, we would need to do

1. the model code itself [listing all parameters]
2. the model header [listing all parameters]
3. the model data header [listing all parameters]
4. the code within the factory to create the model [listing all parameters]
5. the code in the file parser to create the data object [listing all parameters].

One way to simplify things could be for the model to own the data structure with parameters (i.e. the metamodel). That way one would be listing all parameters at only one place.

The purpose of the structure with all component parameters is to simplify component API. One does not need a constructor with a lengthy list of parameters and one might avoid creating multiple accessor functions for setting parameters.

[superwhiskers]

as stated in #169, i don't think this is the approach to go with. for one, working with strings is error-prone and requiring consumers of the library to work with components that way is not a very friendly interface (in terms of discoverability, etc). the approach i drafted in #169 isn't perfect for sure, but i think it points toward a much better interface (in terms of what you can get away with in c++) relative to what is proposed here, as it requires you explicitly list out component parameters, etc in order to get your data structure. additionally, it has type safety in the form of enums keying the parameter and port maps instead of strings.

to add on, i don't think a "factory" approach is the way to go about this. honestly my preferred approach would be to instead remove all constructors from our components save for one taking in the created *Data structure that corresponds to a component and validating the inputs at that point. by doing this, you keep the "locality" of having validation and ingress in the same place as the target structure itself, which i think is nicer for people working with the code. i also think doing this complicates the code more, as there are more places in the code to trace through to get an idea of how we're consuming in a model.

if we do end up going with this, though, i would prefer that we don't treat all input parameters as real values and instead use an std::variant<bool, IdxT, RealT> as i do in my own proposal, as it just doesn't make sense to muddle types like this (in my opinion).

[lukelowry]

to add on, i don't think a "factory" approach is the way to go about this. honestly my preferred approach would be to instead remove all constructors from our components save for one taking in the created *Data structure that corresponds to a component and validating the inputs at that point. by doing this, you keep the "locality" of having validation and ingress in the same place as the target structure itself, which i think is nicer for people working with the code.

I second this part. We could significantly reduce the model implementation burden if we are only passing a Data structure to the constructor. Then the 'linking' of models would become a system-level task and it would be much more readable than passing pointers of models to constructors of other models. This would also make identifying adjacent model variables easier.

[superwhiskers]

to elaborate a little further, what i have in #169 only requires you to list out parameters in:

• the component data file
• the component itself (in both the source and header file)

this is managed by the parser code enumerating the values in the enums within the component data file. we might be able to reduce this further but it'd need even more template hacking over what i've already done and i think what is there strikes a pretty good balance.

we could remove the data file as an alternative which would bring it closer to what is proposed here, but again, this would remove the advantage #169 has with not using strings to identify parameters in the data structures, which provides a better interface for people interacting with gridkit through a c++ api rather than json or something else.

[pelesh]

@abirchfield @lukelowry @superwhiskers : I believe issues discussed here have been resolved through a series of PRs. Can we close this issue?

[abirchfield]

Yes we can close this.