Refactoring and documentation based on "Universal" common interfaces

Broken rules:

There are some keys interfaces that drive everything, defining the formal structure, dependency and organization of the BHoM.

We need to push a reorganization of their arrangement, tweak some conventions and namings, and relocate appropriately certain Engine methods that use/depend on them.

Suggestions to restore compliance:

WIP diagram:

Engines

BHoM_Engine

[ ] Move the IGeometry and IGeometry3D methods into the Geometry_Engine.

Analytical_Engine-Graphics_Engine

[ ] Methods that generalize the IResult representation.
[ ]

Results_Engine

The Results engine should be deleted, as it currently depends on Structure_oM and Analytical_oM and Graphic_oM and its categorization is not meaningful.

[ ] Move the Max, Min, Total, AbsoluteMax methods into Structure.Query.
[ ] Move the DisplayMeshResults into Graphic_oM. Add Analytical_oM dependency in Graphic_oM.
[ ] Move Analytical_Engine: Group, IsNull, MapResults (to be renamedMappedResult).
[ ] Delete the Result_Engine.

Reflection_Engine

[ ] Review / action the historic issue: https://github.com/BHoM/BHoM_Engine/issues/1645. Current thought is that if we move all methods that can be moved from the Reflection_Engine in the BHoM_Engine, what remains really is something that should be placed in a Code or Framework Engine? i.e. is Reflection the right name anymore?

Any objects/methods left obviously is code that is needed as part of the Framework for Adapters, UIs etc. and is distinct from the already existing Programming namespace that is "Programming as a discipline". i.e. creating Programming representation of a concept much like a Structural or Acoustics representation say

Object models

Base_oM

[ ] Add description to the BHoMGroup and IBHoMGroup.
[ ] Move the ISpecification interface in the CIH_Toolkit.
[ ] Review the ComparisonConfig and if it makes sense to move it in the Diffing_oM.
[ ] Review the usage of ISettings interface - if not used, remove; or see if it can be moved below.

Analytical_oM

[ ] https://github.com/BHoM/BHoM/issues/1260
[ ] Reformulate the IResult interface, including creating a compositional set of interfaces: IResult, IObjectResult, ICaseResult, ITimedResult, Structure.IResult
[ ] Formalize the requirement of the IResult interface: a flat list of data primitives.

Graphical_oM

[ ] https://github.com/BHoM/BHoM/issues/1261

Reflection_oM / Programming_oM / Data_oM

[ ] Review / action the historic issue: https://github.com/BHoM/BHoM_Engine/issues/1645. And see above
[ ] Consider grouping Programming_oM with "Disciplines namespaces"; consider renaming to something more discipline-y (e.g. Scripting_oM)
[ ] Create a Library_oM and move there the Data, source from the Data_oM
[ ] Move out as much stuff as possible from the Data_oM to appropriate oMs: Requests -> Analytical_oM, etc. (see if dependency chain can be respected)

EDIT: Updated the diagram to latest WIP and point around Reflection namespace in light of updated diagram

Both https://github.com/BHoM/BHoM_Engine/issues/1645 and https://github.com/BHoM/BHoM_Engine/issues/2671 are related and focus on the same issue of migrating stuff from Reflection to Base as appropriate.

I am intending to close these out in sprint 1 of the 5.1 milestone in the new year. The following steps will be undertaken:

Move Attributes from Reflection_oM to BHoM - these are fundamental to the describing of the BHoM and should be easily accessible to all projects from Base rather than an additional dependency
Move Record_*, BHoMTypeList ExtensionMethodToCall and RunExtensionMethod methods from Reflection_Engine to BHoM_Engine - these are used by Base and are crucial to the running of the BHoM, so again removing dependency on Reflection_Engine unless a project is actually requiring some form of reflection
These will be PRed together on one branch name across oM and Engine
BHoMBot will then comb through all other installer repositories and make as many automatic updates as possible to the references for calling the above mentioned methods and attributes - some manual assistance may be required but check core and installer will assist with picking these up
This will then be reviewed and merged as appropriate (pending zero-code inclusions, see below)
A wiki page will be established outlining these changes for other repos which are not in the installers to aid people in making updates as necessary
BHoMBots functionality for auto-updating code will be made available for those wishing to use it on non-installer repos.

There are some non-installer repos which should be updated at the same time, namely around the zero-code tools. @adecler could you add a list of the repos you'd like to see updated at the same time for continuity to one of the linked issues (to avoid adding too much more to this issue than is necessary for this issue) (or as an edit to this comment for me)?

Hopefully that all makes sense. As I say, timeline is sprint 1 of 5.1 milestone, probably towards the end of the first week owing to the copyright updates which will happen first and would cause conflicts.

Thanks @FraserGreenroyd @adecler Plan sounding good.

N.B. I have updated the diagram in this issue above to latest iteration. Useful to ensure mapping all methods being migrated (as well as all methods to remain in Reflection Engine) to the classifications of this diagram. So we are all happy makes sense and is logical going forward.

Equally see updated comment above about any code remaining in current Reflection oM/Engine after migration. What will be left and should we rename the Engine to help clarify its purpose? Ideas welcome.

Agree with 95% of all the suggestions for changes in this issue. Some few things I slightly question are:

Move the IGeometry and IGeometry3D methods into the Geometry_Engine.

Personally, I want to get rid of any reference to any BHoMObject from the Geometry_Engine, and for it to only work with pure geometric concepts. This goes in line with the not yet fully closed out https://github.com/BHoM/BHoM/issues/756 issue (which probably could/should be added to this list to finally get levels and grids moved out of Geometry_oM).

Can understand the reasoning behind getting it out of the Base_oM, even if I kind of like to have it there myself, but if it needs to be moved I would argue a better fit for it would be the Spatial_Engine, for the same reasons as discussed in the linked BHoM issue.

Review the usage of ISettings interface - if not used, remove; or see if it can be moved below.

This is being used be analytics and Library, and more to come, and wonder if it is not best placed in the base oM? I personally at least have a hard time coming up with a better place for it. Know the whole statement starts with review, so might be the conclusion of that review. 😄

BHoM / admin