improve doxygen documentation of PFunction.* and PFunctionGrammar.h
This commit is contained in:
@@ -40,24 +40,34 @@
|
||||
// Constructor
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Constructor.
|
||||
* \brief Constructor that initializes the function from a parsed AST.
|
||||
*
|
||||
* info is an abstract syntax tree (AST) generate by the spirit parse library
|
||||
* (see http://spirit.sourceforge.net/distrib/spirit_1_8_5/libs/spirit/doc/trees.html).
|
||||
* It contains a single parsed msr-function in an ascii representation.
|
||||
* Here it takes the from
|
||||
* This constructor performs the following steps:
|
||||
* 1. Stores the AST generated by the Boost.Spirit parser
|
||||
* 2. Extracts the function number from the function label (FUNx)
|
||||
* 3. Converts the AST into an efficient evaluation tree structure
|
||||
* 4. Generates a human-readable string representation of the function
|
||||
*
|
||||
* The input AST has the following structure:
|
||||
* \verbatim
|
||||
* assignment (root node)
|
||||
* |_ 'FUNx'
|
||||
* |_ '='
|
||||
* |_ expression
|
||||
* |_ ...
|
||||
* |_ 'FUNx' (function label)
|
||||
* |_ '=' (assignment operator)
|
||||
* |_ expression (mathematical expression tree)
|
||||
* |_ term
|
||||
* |_ factor
|
||||
* |_ ...
|
||||
* \endverbatim
|
||||
*
|
||||
* <p>Since it would be inefficient to evaluate this AST directly it is transferred to
|
||||
* a more efficient tree fFuncs here in the constructor.
|
||||
* Direct evaluation of the AST would be inefficient due to its verbose structure.
|
||||
* Therefore, it is converted to a more compact evaluation tree (fFunc) optimized
|
||||
* for repeated evaluation with different parameter values during fitting.
|
||||
*
|
||||
* \param info AST parse tree holding a single parsed msr-function in an ascii representation
|
||||
* \param info AST parse tree from Boost.Spirit containing a parsed msr-function
|
||||
*
|
||||
* \see SetFuncNo for function number extraction
|
||||
* \see GenerateFuncEvalTree for AST to evaluation tree conversion
|
||||
* \see EvalTreeForString for string representation generation
|
||||
*/
|
||||
PFunction::PFunction(tree_parse_info<> info) : fInfo(info)
|
||||
{
|
||||
@@ -80,7 +90,12 @@ PFunction::PFunction(tree_parse_info<> info) : fInfo(info)
|
||||
// Destructor
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Destructor.
|
||||
* \brief Destructor that releases all resources.
|
||||
*
|
||||
* Cleans up:
|
||||
* - Parameter vector
|
||||
* - Map vector
|
||||
* - Evaluation tree (recursively frees all nodes and their children)
|
||||
*/
|
||||
PFunction::~PFunction()
|
||||
{
|
||||
@@ -112,9 +127,14 @@ void PFunction::InitNode(PFuncTreeNode &node)
|
||||
// SetFuncNo (protected)
|
||||
//-------------------------------------------------------------
|
||||
/**
|
||||
* <p>Extracts the function number of the AST tree.
|
||||
* \brief Extracts the function number from the AST tree.
|
||||
*
|
||||
* <b>return:</b> true if the function number (of FUNx, x being a number) could be extracted, otherwise false.
|
||||
* Navigates to the function label node in the AST and parses the numeric
|
||||
* identifier from the "FUNx" label. For example, "FUN3" yields 3.
|
||||
*
|
||||
* \return true if the function number was successfully extracted, false otherwise
|
||||
*
|
||||
* \note The function number is stored in the member variable fFuncNo
|
||||
*/
|
||||
Bool_t PFunction::SetFuncNo()
|
||||
{
|
||||
@@ -145,8 +165,15 @@ Bool_t PFunction::SetFuncNo()
|
||||
// GenerateFuncEvalTree (protected)
|
||||
//-------------------------------------------------------------
|
||||
/**
|
||||
* <p>Stub to generate the function evaluation tree from the AST tree. Needed for an efficient
|
||||
* evaluation.
|
||||
* \brief Initiates conversion of AST to evaluation tree.
|
||||
*
|
||||
* This function initializes the root node and triggers the recursive
|
||||
* conversion process. The evaluation tree is a more efficient representation
|
||||
* than the AST for repeated function evaluations during fitting.
|
||||
*
|
||||
* \return true (currently always successful)
|
||||
*
|
||||
* \see FillFuncEvalTree for the recursive conversion algorithm
|
||||
*/
|
||||
Bool_t PFunction::GenerateFuncEvalTree()
|
||||
{
|
||||
@@ -160,10 +187,23 @@ Bool_t PFunction::GenerateFuncEvalTree()
|
||||
// FillFuncEvalTree (protected)
|
||||
//-------------------------------------------------------------
|
||||
/**
|
||||
* <p>Recursive generation of the evaluation tree.
|
||||
* \brief Recursively converts AST nodes to evaluation tree nodes.
|
||||
*
|
||||
* \param i iterator of the AST tree
|
||||
* \param node of the evaluation tree
|
||||
* This function traverses the AST and builds a corresponding evaluation tree.
|
||||
* It handles all node types defined in PFunctionGrammar:
|
||||
* - Leaf nodes: real numbers, constants (PI, GAMMA_MU, B, EN, T), parameters, maps
|
||||
* - Operator nodes: arithmetic operations (+, -, *, /)
|
||||
* - Function nodes: mathematical functions (cos, sin, exp, etc.)
|
||||
* - Power nodes: POW(base, exponent)
|
||||
* - Composite nodes: factors, terms, expressions
|
||||
*
|
||||
* The resulting tree structure is optimized for efficient evaluation.
|
||||
*
|
||||
* \param i Iterator pointing to the current AST node to process
|
||||
* \param node Evaluation tree node to populate with data from the AST
|
||||
*
|
||||
* \see PFunctionGrammar for AST node type definitions
|
||||
* \see EvalNode for the evaluation algorithm that uses this tree
|
||||
*/
|
||||
void PFunction::FillFuncEvalTree(iter_t const& i, PFuncTreeNode &node)
|
||||
{
|
||||
@@ -340,10 +380,17 @@ void PFunction::FillFuncEvalTree(iter_t const& i, PFuncTreeNode &node)
|
||||
// CheckMapAndParamRange (public)
|
||||
//-------------------------------------------------------------
|
||||
/**
|
||||
* <p>Stub the check map and fit parameter ranges.
|
||||
* \brief Validates all map and parameter references in the function.
|
||||
*
|
||||
* \param mapSize size of the map vector
|
||||
* \param paramSize size of the parameter vector
|
||||
* Initiates a recursive traversal of the evaluation tree to verify that all
|
||||
* MAP# and PAR# references fall within valid ranges. This prevents runtime
|
||||
* errors during evaluation caused by out-of-bounds array access.
|
||||
*
|
||||
* \param mapSize Number of available map entries (MAP1 to MAP<mapSize>)
|
||||
* \param paramSize Number of available fit parameters (PAR1 to PAR<paramSize>)
|
||||
* \return true if all references are valid, false if any are out of range
|
||||
*
|
||||
* \see FindAndCheckMapAndParamRange for the recursive validation algorithm
|
||||
*/
|
||||
Bool_t PFunction::CheckMapAndParamRange(UInt_t mapSize, UInt_t paramSize)
|
||||
{
|
||||
@@ -354,11 +401,20 @@ Bool_t PFunction::CheckMapAndParamRange(UInt_t mapSize, UInt_t paramSize)
|
||||
// FindAndCheckMapAndParamRange (protected)
|
||||
//-------------------------------------------------------------
|
||||
/**
|
||||
* <p>Recursive checking of map and fit parameter ranges.
|
||||
* \brief Recursively validates map and parameter references in the tree.
|
||||
*
|
||||
* \param node of the evaluation tree
|
||||
* \param mapSize size of the map vector
|
||||
* \param paramSize size of the fit parameter vector
|
||||
* Traverses the evaluation tree depth-first, checking each node:
|
||||
* - For parameter nodes (PAR#): verifies # <= paramSize
|
||||
* - For map nodes (MAP#): verifies # <= mapSize
|
||||
* - For other nodes: recursively checks all children
|
||||
*
|
||||
* The validation ensures that array indices will be valid during evaluation,
|
||||
* preventing potential segmentation faults or undefined behavior.
|
||||
*
|
||||
* \param node Current evaluation tree node being checked
|
||||
* \param mapSize Number of available map entries
|
||||
* \param paramSize Number of available fit parameters
|
||||
* \return true if this node and all descendants have valid references, false otherwise
|
||||
*/
|
||||
Bool_t PFunction::FindAndCheckMapAndParamRange(PFuncTreeNode &node, UInt_t mapSize, UInt_t paramSize)
|
||||
{
|
||||
@@ -416,11 +472,25 @@ Bool_t PFunction::FindAndCheckMapAndParamRange(PFuncTreeNode &node, UInt_t mapSi
|
||||
// Eval (public)
|
||||
//-------------------------------------------------------------
|
||||
/**
|
||||
* <p>Stub starting the evaluation of the evaluation tree.
|
||||
* \brief Evaluates the function with given parameters and metadata.
|
||||
*
|
||||
* <b>return:</b> the value of the function call.
|
||||
* This is the main evaluation entry point. It:
|
||||
* 1. Stores the current parameter values and metadata
|
||||
* 2. Initiates recursive evaluation of the tree
|
||||
* 3. Returns the computed result
|
||||
*
|
||||
* \param param fit parameter vector
|
||||
* The function can be evaluated multiple times with different parameter
|
||||
* values without re-parsing or rebuilding the evaluation tree, making it
|
||||
* efficient for iterative fitting algorithms.
|
||||
*
|
||||
* \param param Vector of fit parameter values (PAR1, PAR2, ...)
|
||||
* \param metaData Experimental metadata (field, energy, temperature, etc.)
|
||||
* \return Computed function value
|
||||
*
|
||||
* \see EvalNode for the recursive evaluation algorithm
|
||||
*
|
||||
* \warning Ensure CheckMapAndParamRange has been called before evaluation
|
||||
* to prevent out-of-bounds access
|
||||
*/
|
||||
Double_t PFunction::Eval(std::vector<Double_t> param, PMetaData metaData)
|
||||
{
|
||||
@@ -434,9 +504,27 @@ Double_t PFunction::Eval(std::vector<Double_t> param, PMetaData metaData)
|
||||
// EvalNode (protected)
|
||||
//-------------------------------------------------------------
|
||||
/**
|
||||
* <p>Recursive evaluation of the evaluation tree.
|
||||
* \brief Recursively evaluates an evaluation tree node.
|
||||
*
|
||||
* \param node of the evaluation tree
|
||||
* This is the core evaluation algorithm that computes the function value
|
||||
* by recursively processing the tree structure. Each node type is handled
|
||||
* appropriately:
|
||||
*
|
||||
* - Leaf nodes (constants, parameters, maps): Return their values directly
|
||||
* - Operator nodes (+, -, *, /): Evaluate children and apply operation
|
||||
* - Function nodes (cos, sin, exp, etc.): Evaluate argument and apply function
|
||||
* - Power nodes: Evaluate base and exponent, compute power
|
||||
*
|
||||
* Special handling:
|
||||
* - Division by zero: Triggers an error and assertion
|
||||
* - Negative bases in power: Takes absolute value if exponent is non-integer
|
||||
* - Logarithms and square roots: Use absolute value to avoid complex numbers
|
||||
* - Maps: Returns 0 if map value is 0, otherwise returns the mapped parameter
|
||||
*
|
||||
* \param node Current evaluation tree node to evaluate
|
||||
* \return Computed value for this node
|
||||
*
|
||||
* \see Eval for the public evaluation entry point
|
||||
*/
|
||||
Double_t PFunction::EvalNode(PFuncTreeNode &node)
|
||||
{
|
||||
@@ -570,7 +658,12 @@ Double_t PFunction::EvalNode(PFuncTreeNode &node)
|
||||
// CleanupFuncEvalTree (protected)
|
||||
//-------------------------------------------------------------
|
||||
/**
|
||||
* <p>Stub to clean up the evaluation tree.
|
||||
* \brief Initiates cleanup of the evaluation tree.
|
||||
*
|
||||
* Starts the recursive cleanup process from the root node to free all
|
||||
* dynamically allocated child nodes in the tree.
|
||||
*
|
||||
* \see CleanupNode for the recursive cleanup algorithm
|
||||
*/
|
||||
void PFunction::CleanupFuncEvalTree()
|
||||
{
|
||||
@@ -582,9 +675,13 @@ void PFunction::CleanupFuncEvalTree()
|
||||
// CleanupNode (protected)
|
||||
//-------------------------------------------------------------
|
||||
/**
|
||||
* <p>Recursive clean up of the evaluation tree.
|
||||
* \brief Recursively cleans up evaluation tree nodes and their children.
|
||||
*
|
||||
* \param node of the evaluation tree
|
||||
* Performs depth-first traversal to clean up all child nodes before
|
||||
* clearing the current node's children vector. This ensures proper
|
||||
* resource deallocation and prevents memory leaks.
|
||||
*
|
||||
* \param node Current evaluation tree node to clean up
|
||||
*/
|
||||
void PFunction::CleanupNode(PFuncTreeNode &node)
|
||||
{
|
||||
@@ -600,9 +697,15 @@ void PFunction::CleanupNode(PFuncTreeNode &node)
|
||||
// EvalTreeForString (private)
|
||||
//-------------------------------------------------------------
|
||||
/**
|
||||
* <p>Stub to generate the function string (clean and tidy).
|
||||
* \brief Initiates generation of human-readable function string from AST.
|
||||
*
|
||||
* \param info AST tree
|
||||
* Creates a formatted, readable string representation of the function by
|
||||
* traversing the AST. The resulting string is stored in fFuncString and
|
||||
* can be used for display, logging, or debugging purposes.
|
||||
*
|
||||
* \param info AST parse tree to convert to string
|
||||
*
|
||||
* \see EvalTreeForStringExpression for the recursive string generation algorithm
|
||||
*/
|
||||
void PFunction::EvalTreeForString(tree_parse_info<> info)
|
||||
{
|
||||
@@ -614,9 +717,24 @@ void PFunction::EvalTreeForString(tree_parse_info<> info)
|
||||
// EvalTreeForStringExpression (private)
|
||||
//-------------------------------------------------------------
|
||||
/**
|
||||
* <p>Recursive generation of the function string (clean and tidy).
|
||||
* \brief Recursively generates formatted function string from AST.
|
||||
*
|
||||
* \param i iterator of the AST tree
|
||||
* Traverses the AST and builds a human-readable string representation.
|
||||
* The function handles:
|
||||
* - Proper parenthesization to maintain operator precedence
|
||||
* - Formatting of constants (PI -> Pi, GAMMA_MU -> gamma_mu)
|
||||
* - Proper spacing around operators
|
||||
* - Special handling for division denominators (adds parentheses if needed)
|
||||
* - Function call formatting with arguments
|
||||
*
|
||||
* The resulting string is formatted for readability while maintaining
|
||||
* mathematical correctness.
|
||||
*
|
||||
* \param i Iterator pointing to current AST node
|
||||
* \param funcFlag Flag indicating if currently processing inside a function argument
|
||||
* (affects parenthesization rules)
|
||||
*
|
||||
* \note Uses a static variable termOp to track operator nesting depth
|
||||
*/
|
||||
void PFunction::EvalTreeForStringExpression(iter_t const& i, bool funcFlag)
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user