Class naming and functionality

[sethrj]

Can we do a better job of naming our classes (e.g. with Params/Store/View/TrackView/...) so that they're consistent and understandable without having to dive into what they're actually doing? To help, I've tabulated essentially all of the current classes in src/ and expanded on what they do under the hood and how they're used.

---

Here are essentially all the classes in the main Celeritas codebase, with annotations about being host/device and several other groupings.

For data model:

• Own: it has values and shared/unique pointers to data -- it doesn't depend on the scope of the construction arguments. The data doesn't necessarily have to be complex host-only data; it could be device-compatible POD.
• Reference: it relies on data from an external source and indeed can be invalidated if the construction arguments go out of scope. Sometimes it can "own" some data but it's a trivial copy. Spans, raw pointers, and const references are all "references".
• An en dash means it has no data and is purely a collection of functions and/or types.

The interface is a little fuzzier.

• Struct: a struct that has only public data and a default constructor. (It can also have additional convenience methods.)
• Traits: simply defines a set of typedefs.
• Functor: meant to act like a function by defining an operator().
• RAII: its constructor and destructor are the main methods (i.e. its scope is the only thing that matters).
• Interface: its main purpose is to provide an encapsulated interface to data.

I've also tagged whether the class constructor is "no-op" meaning it's effectively free -- it doesn't do anything except perhaps a pointer increment. We shouldn't in practice have to worry about whether a class constructor is cheap or not, so perhaps that should factor into the naming.

Finally, I've tagged most of the classes on whether the data they own/operate on is:

• Track-parallel data
• Shared and mutable among different classes and tracks
• Static and effectively constant at construction time
• Local in that it's particular to a track but might be inside a branch or depend on some other local context

---

Device-compatible classes are grouped first since their meaning is the least consistent and we should address those. Then they're sorted by data model, then interface.

Class name	H	D	Data model	Interface	No-op constructor	State locality
KernelParamCalculator	✅	✅	—	Functor	✅	—
GenerateCanonical		✅	—	Functor	✅	—
UnitDivide	✅	✅	—	Traits	✅	—
UnitProduct	✅	✅	—	Traits	✅	—
SoftZero	✅	✅	Own	Functor	✅	Local
SoftEqual	✅	✅	Own	Functor		Local
BernoulliDistribution		✅	Own	Functor		Local
BetheBlochInteractor		✅	Own	Functor		Track
BremRelInteractor		✅	Own	Functor		Track
ExponentialDistribution		✅	Own	Functor		Local
Interpolator		✅	Own	Functor		Local
IsotropicDistribution		✅	Own	Functor		Local
PhotoelectricInteractor		✅	Own	Functor		Track
RadialDistribution		✅	Own	Functor		Local
UniformRealDistribution		✅	Own	Functor		Local
Array	✅	✅	Own	Interface	✅	Any
OpaqueId	✅	✅	Own	Interface	✅	Local
Quantity	✅	✅	Own	Interface	✅	Local
UniformGrid	✅	✅	Own	Interface	✅	Local
ElementDef	✅	✅	Own	Struct	✅	Static
ParticleDef	✅	✅	Own	Struct	✅	Static
MaterialTrackState		✅	Own	Struct	✅	Track
ModelInteractState		✅	Own	Struct	✅	Track
ParticleTrackState		✅	Own	Struct	✅	Track
PhysicsTrackState		✅	Own	Struct	✅	Track
Primary		✅	Own	Struct	✅	Local
RngSeed		✅	Own	Struct	✅	Track
Secondary		✅	Own	Struct	✅	Local
SimTrackState		✅	Own	Struct	✅	Track
TrackInitializer		✅	Own	Struct	✅	Track
LinearPropagator		✅	Reference	Functor	✅	Track
PhotoelectricMicroXsCalculator		✅	Reference	Functor	✅	Track
RngEngine		✅	Reference	Functor	✅	Track
ElementSelector		✅	Reference	Functor		Track
Span	✅	✅	Reference	Interface	✅
ElementView		✅	Reference	Interface	✅	Static
GeoTrackView		✅	Reference	Interface	✅	Track
MaterialTrackView		✅	Reference	Interface	✅	Track
MaterialView		✅	Reference	Interface	✅	Static
ParticleTrackView		✅	Reference	Interface	✅	Track
PhysicsTrackView		✅	Reference	Interface	✅	Track
SimTrackView		✅	Reference	Interface	✅	Track
StackAllocatorView		✅	Reference	Interface	✅	Static
MaterialDef	✅	✅	Reference	Struct	✅	Static
GeoStateInitializer		✅	Reference	Struct	✅	Track
Interaction		✅	Reference	Struct	✅	Track
LivermoreElement		✅	Reference	Struct	✅	Static
LivermoreSubshell		✅	Reference	Struct	✅	Static
MatElementComponent		✅	Reference	Struct	✅	Static
TypeDemangler	✅		—	Functor	✅	–
Model	✅		—	Interface	—	–
Process	✅		—	Interface	—	–
ValueGridBuilder	✅		—	Interface	—	–
ScopedMpiInit	✅		—	RAII		–
EventReader	✅		Own	Functor
LivermoreParamsReader	✅		Own	Functor
Logger	✅		Own	Functor
ModelIdGenerator	✅		Own	Functor
RootImporter	✅		Own	Functor
SpanRemapper	✅		Own	Functor
Stopwatch	✅		Own	Functor
DebugError	✅		Own	Interface	✅
GdmlGeometryMap	✅		Own	Interface	✅
Communicator	✅		Own	Interface
ComptonProcess	✅		Own	Interface
DeviceAllocation	✅		Own	Interface
DeviceVector	✅		Own	Interface
EPlusAnnihilationProcess	✅		Own	Interface
EPlusGGModel	✅		Own	Interface
GeoParams	✅		Own	Interface
GeoStateStore	✅		Own	Interface		Track
KleinNishinaModel	✅		Own	Interface
LivermoreParams	✅		Own	Interface		Static
MaterialParams	✅		Own	Interface		Static
MaterialStateStore	✅		Own	Interface		Track
ModelInteractParams	✅		Own	Interface		Static
ParamStore	✅		Own	Interface		Track
ParticleParams	✅		Own	Interface		Static
ParticleStateStore	✅		Own	Interface		Track
RngStateStore	✅		Own	Interface		Track
SimStateStore	✅		Own	Interface		Track
StackAllocatorStore	✅		Own	Interface		Shared
StateStore	✅		Own	Interface		Track
TrackInitializerStore	✅		Own	Interface+		Track
Applicability	✅		Own	Struct	✅
ImportElement	✅		Own	Struct	✅
ImportMaterial	✅		Own	Struct	✅
ImportParticle	✅		Own	Struct	✅
ImportPhysicsTable	✅		Own	Struct	✅
ImportPhysicsVector	✅		Own	Struct	✅
ImportProcess	✅		Own	Struct	✅
ImportVolume	✅		Own	Struct	✅
Provenance	✅		Own	Struct	✅

[sethrj]

I've also left off all the Pointers classes, which uniformly mean Host+Device/Reference/Struct/No-op constructor. We should think of a better name for those (*Data? *Interface?) or just leave off Pointers.

[sethrj]

Nomenclature plusses:

• Functors are consistently "agent noun"s, with the exception of RNG and
  distribution which follow the pattern of the standard library
• Reference interfaces are consistently named "view".

Exceptions that stand out:

• Stopwatch is the only non-RNG functor that's not an agent noun.
• ElementSelector references most of its data but also has an expensive
  constructor.
• TrackInitializerStore encapsulates a lot of kernel launches and additional
  functionality in addition to just storing the states.

I wonder if we can universally replace XStateStore with XStates. It has a little better symmetry with XParams.