Making sense of C++ core code

Let’s try log the classes and their meaning and usage. The documents and relations may then be converted to doxygen.

General notes

• The virtual inhertance is implemented via CRTP mechanism.

• See also CppCoreGuidlines.

Glossary

Trasnformation, trasnformation node, calculation node, node

calculation unit with arbitrary number of inputs and at least one output

Input, argument, source

calculation node input data

Output, return value, sink

calculation node output data

Connection, connect

procedure of the connection between one TransformationBase::Entry’s output to the other TransformationBase::Entry’s input

GNAObject header

GNAObjectclass

• Carries lists of:

  • variable isntances via VariableDescriptor

  • evaluable isntances via EvaluableDescriptor

  • transformation instances via TransformationDescriptor

• Inherits TransformationBase::Base

  • carries list of TransformationBase::Entry instances

  • has transformation member function used to initialize transformations

• Inherits ParametrizedTypes::Base

  • carries list of ParametrizedTypes::Entry instances

  • has variable_ member function used to define variables

GNASingleObjectclass

• Implements some shorcuts for GNAObject with only one output

• Inherits GNAObject and SingleOutput

Parameters header

The header contains classes representing individual parameters. The base class is changeable.

Data

inconstant_datastruct template

• elementary data item (usually double) with taint flag propagation

• may handle a function pointer to calculate the data value

• may handle a callback function to be called on data change

inconstant_headerstruct

• carries information to track dependencies:

  • taintflag

  • list of taint signal emitters

  • list of taint signal observers

• base for inconstant_data

referencesstruct

• a container for changeable instances

• used in inconstant_header

• why manually allocated? TBD

Variables

Variables represent simple data types (double) with taintflag propagation feature. Variables within same namespace (python side) are distinguished by their name. Creating several variable or parameter instances with the same name will manage the same data.

Variables are mostly used on C++ side. On python side the Parameter, Variable, etc are used as accessors.

callbackclass

• TBD

changeableclass

• keeps data as inconstant_data (usually inconstant_data_<double>)

• propagates taintflag among denepdants

• base for variable

dependantclass template

• inherits evaluable

• implements evaluable, which value depends on other parameters

• usuall created via mkdep() function

evaluableclass template

• inherits variable

• a parameter, which value is evaluated with a function

parameterclass template

• inherits variable

• may set the variable’s value

references : class

taintflagclass

• indicates (cast too bool) if the value/transformation should be recalculated

variableclass template

• inherits changeable

• base for evaluable and parameter clasees

• can return the variable’s value

• can not set the varialbe_s value, see parameter

• calls updating function if the value is tainted

Parametrized header

EvaluableDescriptor : class

VariableDescriptor : class

ParametrizedTypes namespace

Main classes

Baseclass

• base class for GNAObject

• contains list of ParametrizedTypes::Entry instances

• contains list of ParametrizedTypes::EvaluableEntry instances

• contains list of callback instances

• implements variable_ member function used to define variables

• shares it’s taintflag with all the entries

Entryclass

• a class to access variable’s value

• contains pointers to:

  • parameter par — the parameter

  • variable var — pointer to par (of the base class)

  • variable field

EvaluableEntry : class

Indirect access classes

EvaluableHandleclass template

• indirect access to ParametrizedTypes::EvaluableEntry instance

• base for EvaluableDescriptor

VariableHandleclass template

• indirect access to ParametrizedTypes::Entry instance

• base for VariableDescriptor

TransformationBase header

SingleOutputclass

• copmlements TransformationBase::Base class

• used for the cases when there is only one output

• parent to GNASingleObject

Transformationclass template

• manages MemFunction instances

• contains

  • list of MemFunction instances

  • list of MemTypesFunction instances

• lists of functions are filled within Initializer

• CRTP base for GNAObject

• requires ancestor to also inherit GNAObject

TransformationTypes namespace (TransformationBase)

The header is now fully documented via Doxygen.

Functions

Functionstd::function

• (Args, Rets)

• an implementation of the particular transformation

TypesFunctionstd::function

• (Atypes, Rtypes)

• an transformation input/output types initialization and checking

MemFunctionstd::function

• template

• (T* this, Args, Rets)

• an implementation of the particular transformation

• requires the object to be passed as the first argument (needs binding)

MemTypesFunctionstd::function

• template

• (T*, Atypes, Rtypes)

• an transformation input/output types initialization and checking

• requires the object to be passed as the first argument (needs binding)

Main classes

Baseclass

• base class for GNAObject

• contains list of TransformationBase::Entry instances

• accessed via Accessor class

• may be connected

• implements transformation_ member function used to define any transformation (returns Initializer instance)

Entrystruct

• base class for the calculation node representation

• has methods to:

  • add sources/sinks

  • evaluate/update types/values

  • freeze/unfreeze/touch

• gives access to:

  • sources/sinks

  • data

  • taintflag

• accessed via Handle class

• named

Initializerclass template

• used to initialize transformation via CRTP chain

• created via inherited TransformationBase::Base::transformation_

• creates TransformationBase::Entry instance and assignes it to the caller

• assigns inputs, outputs, types functions, etc

Indirect access classes

Accessorclass

• limited indirect access to TransformationBase::Base instance

• access to TransformationBase::Entry by name or index via Handle

Argsstruct

• limited indirect access to Source instances through TransformationBase::Entry instance

• transformation input implementation

• access to TransformationBase::Entry’s data

Atypesstruct

• limited indirect access to Source types through TransformationBase::Entry instance

• used for inputs’ type checking

• access to TransformationBase::Entry’s DataType

Handleclass

• indirect access to TransformationBase::Entry instance

• implements and redirects TransformationBase::Entry methods

InputHandleclass

• limited indirect access to Source

• may be connected to OutputHandle

Retsstruct

• limited indirect access to Sink instances through TransformationBase::Entry instance

• transformation output implementation

• access to TransformationBase::Entry’s data

• may be (un)frozen

Rtypesstruct

• limited indirect access to Sink types through TransformationBase::Entry instance

• used for outputs’ type checking

• access to TransformationBase::Entry’s DataType

Sinkstruct

• public indirect access to TransformationBase::Entry instance

• named

Sourcestruct

• public indirect access to TransformationBase::Entry instance

• may be connected to Sink instance

• named

OutputHandleclass

• limited indirect access to Sink

• may be:

  • checked if depends on changeable instance

Errors

TypeErrorclass

• Base class for type errors

• Just pass a message to std::runtime_error constructor

CalculationErrorclass

• Can be throwed if transformation cannot be computed: invalid source and etc..

• Appears only in operator[](int i) for Args, Rets and in Entry::data(int i)

SinkTypeErrorclass

• Inherits from TypeError

• Throwed when type function fails on constructing sink via rets.error(message)

SourceTypeErrorclass

• Inherits from TypeError

• Throwed when type function fails on constructing source via args.error(message)

Transformation header

InputDescriptorclass

• a wrapper to the InputHandle

• implements various forms of the connect() function

OutputDescriptorclass

• a wrapper to the OutputHandle

TransformationDescriptorclass

• a wrapper to the TransformationBase::Entry

• carries also lists of InputDescriptor instances and OutputDescriptor instances

UncertainParameter header

The header contains variaous variable and parameter views, defined as transformations and used on python side.

GaussianParameterclass template

• a nickname for Parameter (Variable)

• represents normally distributed variable with central value and sigma

• carries also information about variable’s uncertainty

Parameterclass template

• derives _Variable

• carries parameter instance for the variable, i.e. may set it’s value

• may:

  • set parameter’s value

  • set parameter’s value in terms of sigma relative to it’s central position

  • define limits (used for minimization)

• the class is used as an input for the minimization

ParameterWrapperclass template

• a simple wrapper for the parameter class meant to use on python side

• has set and get methods

• carries also information about variable’s central value

Variableclass template

• GNAObject represending a transformation with no inputs and one output

• output is connected with variable instance (connection is name based)

UniformAngleParameterclass template

• derives Parameter

• represents an angle in radiance defined in \([-\pi, \pi)\)

ParametricLazy.hpp header

Defines code for the evaluable creation based on math expressions.

Defines mkdep() function which does the job.

No additional reference for now (it’s magic).