[UNDER-DISCUSSION] Plugin Entities Design

[PaulTalbot-INL]

---

Under Discussion Topic

Discussion Plugin Entities (Entities in Plugins that are meant to be available as RAVEN Entities such as Sampler, ROMs, PostProcessors, etc) can potentially be done a lot of ways philosophically.

1. New PluginBase types for each Entity (e.g. SamplerPluginBase) can be created that does not inherit from the base type (e.g. Sampler), but provides a simplified interface for users. This results in the loss of some potential entity functionality, but results in a streamlined experience for Plugin development.
2. New PluginBase types for each Entity can inherit directly from the base Entity. This results in keeping the messageHandler and similar base properties and preserves full flexibility; however, this results in a potentially complex and easily breakable API if RAVEN core changes its API.

Design decision March 15, 2021 Option 2, Each <Entity>PluginBase should inherit directly from the Entity base, preserving flexibility over simplicity. The discussion pointed out that if we used interfaces (option 1), as we steadily add more and more features to the interface, it will eventually converge on the actual base class, only duplicated in two places. We elected to preserve utility over simplicity.

NOTE this decision was reversed later that week, see comments below.

Discussion Given this decision, the question becomes what objects should be base Entities for plugins. Nominally, the base entities in Simulation.entityModules seems like a good start, as this is where the factories live; however, this includes Models as a single entity, which is in reality an umbrella for ROMs, PostProcessors, Codes, and ExternalModels. Also note that (with the exception of ongoing development in the PostProcessors) none of the actual algorithms used in these models inherits from the base Model; for example, the Model.ROM has a SupervisedLearningEngine member that does not inherit from Model but its own base class.

Does this mean that there should be a SupervisedLearning base class instead? If so, the factory for SupervisedLearning needs to be available to the PluginHandler alongside the other more "basic" entities.

---

For Change Control Board: Issue Review

This review should occur before any development is performed as a response to this issue.

• [ ] 1. Is it tagged with the under_discussion type?
• [ ] 2. If implemented, it will add a new requirement?
• [ ] 3. Is a rationale provided? (Such as explaining why the improvement is needed )

---

For Change Control Board: Issue Closure

This review should occur when the issue is imminently going to be closed.

• [ ] 1. The discussion determined the addition of a new task issue?

[PaulTalbot-INL]

Discussion Summary of several discussions ending March 19, 2021:

Glossary:

• Entities: RAVEN base classes, such as Samplers, Models[ROM, ExternalModel, PostProcessor, Code], OutStreams, Metrics, Distributions. Specifically we consider those that may be plugin-able.
• Handler: a class that acts as an interface between core RAVEN (Step, Simulation) and the Algorithms
• Algorithm/Strategy/Implementation: A specific algorithmic implementation of a concept, i.e. Sampler is an Entity, MonteCarlo is an Algorithm/Strategy/Implementation

The question is whether Entities should follow an “inheritance” approach or a “interfacing” approach.

• In “inheritance”, there is no Handler; an Algorithm inherits directly from the base Entity and overwrites the methods it needs to implement its Algorithm.
• In “interfacing”, the Handler specifies an API to allow the base Entity to implement Algorithms, which are minimal objects implementing the specific Algorithm.

Either way,

• The Entity, Handler, and Algorithm will inherit from common base classes to provide access to MessageHandling and InputParams
• The API for almost all Entities/Handlers will have to be cleaned up, simplified, and documented once that Entity is set up to be a plugin

The summary of pro-con for strategies we discussed, as I recall from my notes:

INHERITANCE

• Code is cleaner, in that we remove the “Hander” (e.g. Model.PostProcessor) layer and directly implement a base class in its place.
• Some notable work was already done on the PostProcessor, which limits somewhat the available resources to swap from Inheritance to Interfacing
• Provides nearly infinite flexibility to plugin developers to change how their plugin behaves
• API is defined mostly through documentation, which is not mechanically binding but preserves more flexibility

INTERFACING:

• There is clear separation between the Handler and the Algorithm, enabling use of the Algorithm elsewhere in RAVEN
• There is a mechanically-defined API from the Handler, limiting the Algorithm to calls specifically from the Handler

Current Entities that use Inheritance:

• OutStreams
• Samplers
• Models.PostProcessors
• Distributions

Current Entities that use Interfacing:

• Models.ROM
• Models.Code
• Metrics Current Entities that use Neither:
• Models.ExternalModel (like an Interface but through a container)

[PaulTalbot-INL]

Comments from Andrea via email:

I think we need to be in the middle of the two approaches. Inheritance to the base class of the “Plugin” (and not the base raven entity) with a clear light API and interface to the different algorithms. The basic Plugin base class should have the minimum required methods:

• Input registration and handling
• Initialization
• Execution
• Output interface
• Assembler request

[PaulTalbot-INL]

This decision using interfaces suggests an inheritance structure, for example:

BaseType

EntityType(BaseType) StrategyType(BaseType) or InterfaceType(BaseType)

SamplerHandler(EntityType) MonteCarlo(StrategyType/InterfaceType)

etc

[PaulTalbot-INL]

EntityBase.pptx Here is a PPT showing the current and proposed structures for this discussion.

As of discussion on March 22, 2021, we have the following "going forward" approach for my development work:

• Build a pseudocode for what concepts should be handled in the BaseType, BaseEntity, and BaseInterface; discuss this with the team
• Develop the three base classes, without changing the existing Entities and Interfaces; merge this into the code base
• As each plugin is needed, recast the Entity and Interface base classes to follow the new base classes structure.

[PaulTalbot-INL]

Things the BaseType currently knows about, and how they might be redistributed:

BaseType(MessageUser)

• Reading XML
• Generating and Reading InputParams
• Message Handling
• Printing "self" information (whoAreYou, printMe)
• initParams, currentSetting (are these used?)
• Metadata variables
• Solution Export Variables (names, validation)

Assembler(MessageUser)

• Object assembly

---

Proposed redistribution of these features:

MessageUser()

• Set message handler
• raising messages, errors

InputDataUser()

• Generating Input Specs
• Convert XML into InputParams

Assembler(MessageUser)

• Assembling requests

BaseType(MessageUser) -> add InputDataUser inheritance once everyone is using it

• Reading XML -> can be handled by InputDataUser, otherwise must be implemented

BaseEntity(BaseType, Assembler) -> not everyone is an InputDataUser

• Printing "self" information
• Metadata Variable: check for needs, request values
• check for Assembler requests

BaseInterface(BaseType) -> not everyone is an InputDataUser

• Metadata Variables: provide list, provide values
• provide Assembler needs

Other

• SolutionExport Variables -> Move to Sampler base

[PaulTalbot-INL]

On second glance, I don't think the Entity really reads any input; it's a handler that passes input to the Interfaces. This functionally seems to suggest there is no functionality for a BaseType; rather, everything is either BaseEntity or BaseInterface.

[wangcj05]

I would archive this issue, since we have implemented the plugin structure for most entities. Specific issue can be created if there is new request.