LMU/musrfit
5
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases 4 Activity

improve doxygen documentation of PFunction.* and PFunctionGrammar.h
All checks were successful
Build and Deploy Documentation / build-and-deploy (push) Successful in 18s
Details

Browse Source
This commit is contained in:
suter_a
2025-11-14 07:50:50 +01:00
parent f8a2d646dc
commit 40a797c0da
3 changed files with 463 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

249
src/include/PFunction.h
View File

@@ -48,85 +48,256 @@
#include "PFunctionGrammar.h"
//----------------------------------------------------------------------------
#define OP_ADD 0
#define OP_SUB 1
#define OP_MUL 2
#define OP_DIV 3
// Operator tags for arithmetic operations
//----------------------------------------------------------------------------
#define OP_ADD 0 ///< Addition operator tag
#define OP_SUB 1 ///< Subtraction operator tag
#define OP_MUL 2 ///< Multiplication operator tag
#define OP_DIV 3 ///< Division operator tag
#define FUN_COS 0
#define FUN_SIN 1
#define FUN_TAN 2
#define FUN_COSH 3
#define FUN_SINH 4
#define FUN_TANH 5
#define FUN_ACOS 6
#define FUN_ASIN 7
#define FUN_ATAN 8
#define FUN_ACOSH 9
#define FUN_ASINH 10
#define FUN_ATANH 11
#define FUN_LOG 12
#define FUN_LN 13
#define FUN_EXP 14
#define FUN_SQRT 15
#define FUN_POW 16
//----------------------------------------------------------------------------
// Function tags for mathematical functions
//----------------------------------------------------------------------------
#define FUN_COS 0 ///< Cosine function tag
#define FUN_SIN 1 ///< Sine function tag
#define FUN_TAN 2 ///< Tangent function tag
#define FUN_COSH 3 ///< Hyperbolic cosine function tag
#define FUN_SINH 4 ///< Hyperbolic sine function tag
#define FUN_TANH 5 ///< Hyperbolic tangent function tag
#define FUN_ACOS 6 ///< Inverse cosine (arccos) function tag
#define FUN_ASIN 7 ///< Inverse sine (arcsin) function tag
#define FUN_ATAN 8 ///< Inverse tangent (arctan) function tag
#define FUN_ACOSH 9 ///< Inverse hyperbolic cosine function tag
#define FUN_ASINH 10 ///< Inverse hyperbolic sine function tag
#define FUN_ATANH 11 ///< Inverse hyperbolic tangent function tag
#define FUN_LOG 12 ///< Base-10 logarithm function tag
#define FUN_LN 13 ///< Natural logarithm function tag
#define FUN_EXP 14 ///< Exponential function tag
#define FUN_SQRT 15 ///< Square root function tag
#define FUN_POW 16 ///< Power function tag (base^exponent)
//----------------------------------------------------------------------------
/**
* <p>Structure needed to evaluate a function tree (see FUNCTIONS block of an msr-file).
* \brief Tree node structure for efficient function evaluation.
*
* This structure represents a node in the evaluation tree used to compute
* function values. The abstract syntax tree (AST) generated by the parser
* is converted into this more efficient tree structure for faster evaluation.
*
* Each node can represent:
* - A leaf node (constant, parameter, map reference)
* - An operator node (arithmetic operation)
* - A function node (mathematical function)
*
* The tree is evaluated recursively by traversing from the root to the leaves.
*
* \see PFunction::EvalNode for the recursive evaluation algorithm
*/
typedef struct func_tree_node {
Int_t fID; ///< tag showing what tree element this is
Int_t fOperatorTag; ///< tag for '+', '-', '*', '/'
Int_t fFunctionTag; ///< tag got "cos", "sin", ...
Int_t fIvalue; ///< for parameter numbers and maps
Bool_t fSign; ///< for sign, true means '-', false '+'
Double_t fDvalue; ///< for numbers
std::vector<func_tree_node> children; ///< holding sub-tree
Int_t fID; ///< Node type identifier (from PFunctionGrammar constants)
Int_t fOperatorTag; ///< Operator type: OP_ADD, OP_SUB, OP_MUL, OP_DIV
Int_t fFunctionTag; ///< Function type: FUN_COS, FUN_SIN, FUN_EXP, etc.
Int_t fIvalue; ///< Integer value for parameter numbers, map indices, or temperature indices
Bool_t fSign; ///< Sign flag: true for negative, false for positive
Double_t fDvalue; ///< Numeric value for constants and real number literals
std::vector<func_tree_node> children; ///< Child nodes forming the sub-tree
} PFuncTreeNode;
//----------------------------------------------------------------------------
/**
* <p>Class handling a function from the msr-file FUNCTIONS block.
* \brief Class for parsing and evaluating mathematical functions from msr-file FUNCTIONS blocks.
*
* This class handles the complete lifecycle of a function definition:
* 1. Parses the function string using PFunctionGrammar into an AST
* 2. Converts the AST into an efficient evaluation tree
* 3. Validates parameter and map references
* 4. Evaluates the function with given parameters and metadata
*
* Functions can reference:
* - Fit parameters (PAR1, PAR2, ...)
* - Map values (MAP1, MAP2, ...)
* - Constants (PI, GAMMA_MU)
* - Metadata (magnetic field B, energy EN, temperature T)
* - Other functions (FUN1, FUN2, ...)
*
* Example function definition:
* \code
* FUN1 = PAR1 * COS(2.0 * PI * GAMMA_MU * B * PAR2)
* \endcode
*
* \see PFunctionGrammar for the grammar definition
* \see PFuncTreeNode for the evaluation tree structure
*/
class PFunction {
public:
//------------------------------------------------------------------------
/**
* \brief Constructor that parses and prepares a function for evaluation.
*
* \param info Abstract syntax tree (AST) from parsing a function expression
*/
PFunction(tree_parse_info<> info);
//------------------------------------------------------------------------
/**
* \brief Destructor that cleans up the evaluation tree.
*/
virtual ~PFunction();
//------------------------------------------------------------------------
/**
* \brief Checks if the function was successfully parsed and initialized.
*
* \return true if the function is valid, false otherwise
*/
virtual Bool_t IsValid() { return fValid; }
//------------------------------------------------------------------------
/**
* \brief Returns the function number extracted from the function label.
*
* \return Function number (x from FUNx), or -1 if invalid
*/
virtual Int_t GetFuncNo() { return fFuncNo; }
//------------------------------------------------------------------------
/**
* \brief Validates that all parameter and map references are within valid ranges.
*
* \param mapSize Number of available map entries
* \param paramSize Number of available fit parameters
* \return true if all references are valid, false otherwise
*/
virtual Bool_t CheckMapAndParamRange(UInt_t mapSize, UInt_t paramSize);
//------------------------------------------------------------------------
/**
* \brief Evaluates the function with given parameters and metadata.
*
* \param param Vector of fit parameter values
* \param metaData Metadata containing field, energy, temperature, etc.
* \return Computed function value
*/
virtual Double_t Eval(std::vector<Double_t> param, PMetaData metaData);
//------------------------------------------------------------------------
/**
* \brief Sets the map vector for parameter indirection.
*
* Maps allow indirect parameter references. MAP# references fMap[#-1],
* which then indexes into the parameter vector.
*
* \param map Vector of parameter indices (1-based)
*/
virtual void SetMap(std::vector<Int_t> map) { fMap = map; }
//------------------------------------------------------------------------
/**
* \brief Returns the human-readable string representation of the function.
*
* \return Pointer to formatted function string
*/
virtual TString* GetFuncString() { return &fFuncString; }
protected:
//------------------------------------------------------------------------
/**
* \brief Initializes all fields of an evaluation tree node to default values.
*
* \param node Node to initialize
*/
virtual void InitNode(PFuncTreeNode &node);
//------------------------------------------------------------------------
/**
* \brief Extracts the function number from the AST.
*
* Parses the function label (FUN#) to extract the numeric identifier.
*
* \return true if successful, false otherwise
*/
virtual Bool_t SetFuncNo();
//------------------------------------------------------------------------
/**
* \brief Recursively validates parameter and map references in the tree.
*
* \param node Current node being checked
* \param mapSize Number of available map entries
* \param paramSize Number of available fit parameters
* \return true if all references are valid, false otherwise
*/
virtual Bool_t FindAndCheckMapAndParamRange(PFuncTreeNode &node, UInt_t mapSize, UInt_t paramSize);
//------------------------------------------------------------------------
/**
* \brief Initiates the conversion from AST to evaluation tree.
*
* \return true if successful, false otherwise
*/
virtual Bool_t GenerateFuncEvalTree();
//------------------------------------------------------------------------
/**
* \brief Recursively builds the evaluation tree from the AST.
*
* \param i Iterator pointing to current AST node
* \param node Evaluation tree node to fill
*/
virtual void FillFuncEvalTree(iter_t const& i, PFuncTreeNode &node);
//------------------------------------------------------------------------
/**
* \brief Recursively evaluates an evaluation tree node.
*
* \param node Node to evaluate
* \return Computed value for this node and its subtree
*/
virtual Double_t EvalNode(PFuncTreeNode &node);
//------------------------------------------------------------------------
/**
* \brief Initiates cleanup of the evaluation tree.
*/
virtual void CleanupFuncEvalTree();
//------------------------------------------------------------------------
/**
* \brief Recursively cleans up evaluation tree nodes and their children.
*
* \param node Node to clean up
*/
virtual void CleanupNode(PFuncTreeNode &node);
private:
tree_parse_info<> fInfo; ///< AST parse tree holding a single parsed msr-function in an ascii representation
std::vector<Double_t> fParam; ///< parameter vector (from the msr-file Fit Parameter block)
std::vector<Int_t> fMap; ///< map vector
PFuncTreeNode fFunc;
tree_parse_info<> fInfo; ///< AST parse tree from Boost.Spirit parser
std::vector<Double_t> fParam; ///< Current fit parameter values for evaluation
std::vector<Int_t> fMap; ///< Map vector for indirect parameter references
PFuncTreeNode fFunc; ///< Root node of the evaluation tree
Bool_t fValid; ///< flag showing if the function is valid
Int_t fFuncNo; ///< function number, i.e. FUNx with x the function number
Bool_t fValid; ///< Validity flag: true if function parsed and initialized successfully
Int_t fFuncNo; ///< Function number extracted from label (x in FUNx)
//------------------------------------------------------------------------
/**
* \brief Initiates generation of human-readable function string.
*
* \param info AST parse tree to convert to string
*/
virtual void EvalTreeForString(tree_parse_info<> info);
virtual void EvalTreeForStringExpression(iter_t const& i, bool funcFlag=false);
TString fFuncString; ///< text representation of the function
PMetaData fMetaData; ///< keeps meta data from data files (field, energy, temperature, ...)
//------------------------------------------------------------------------
/**
* \brief Recursively generates formatted function string from AST.
*
* \param i Iterator pointing to current AST node
* \param funcFlag Flag indicating if currently inside a function call
*/
virtual void EvalTreeForStringExpression(iter_t const& i, bool funcFlag=false);
TString fFuncString; ///< Formatted, human-readable function representation
PMetaData fMetaData; ///< Metadata from experimental data (field, energy, temperature, etc.)
};
#endif // _PFUNCTION_H_

127
src/include/PFunctionGrammar.h
View File

@@ -44,35 +44,91 @@
using namespace boost::spirit;
#endif
//--------------------------------------------------------------------------
/**
* \brief Iterator type for parsing characters.
*/
typedef char const* iterator_t;
//--------------------------------------------------------------------------
/**
* \brief Type for parse tree matching results.
*/
typedef tree_match<iterator_t> parse_tree_match_t;
//--------------------------------------------------------------------------
/**
* \brief Iterator type for traversing the parse tree.
*/
typedef parse_tree_match_t::tree_iterator iter_t;
//--------------------------------------------------------------------------
/**
* <p>EBNF like grammar definition of a function entry in the msr-file FUNCTION block.
* \brief EBNF-like grammar definition for parsing function entries in msr-file FUNCTION blocks.
*
* This grammar defines the syntax for parsing mathematical function expressions in msr-files.
* It supports:
* - Basic arithmetic operations (+, -, *, /)
* - Mathematical functions (trigonometric, hyperbolic, logarithmic, exponential, etc.)
* - Constants (PI, GAMMA_MU, field B, energy EN, temperature T)
* - Parameters (PAR) and maps (MAP)
* - Function references (FUN)
*
* The grammar follows an EBNF-like structure with the following hierarchy:
* \verbatim
* assignment = fun_label '=' expression
* expression = term { ('+' | '-') term }
* term = factor { ('*' | '/') factor }
* factor = real | constant | parameter | map | function | power | '(' expression ')'
* \endverbatim
*
* \see PFunction for the class that uses this grammar to evaluate parsed expressions
*/
struct PFunctionGrammar : public grammar<PFunctionGrammar>
{
static const int realID = 1;
static const int constPiID = 2;
static const int constGammaMuID = 3;
static const int constFieldID = 4;
static const int constEnergyID = 5;
static const int constTempID = 6;
static const int funLabelID = 7;
static const int parameterID = 8;
static const int mapID = 9;
static const int functionID = 10;
static const int powerID = 11;
static const int factorID = 12;
static const int termID = 13;
static const int expressionID = 14;
static const int assignmentID = 15;
static const int realID = 1; ///< Identifier for real number literals
static const int constPiID = 2; ///< Identifier for PI constant
static const int constGammaMuID = 3; ///< Identifier for GAMMA_MU constant (muon gyromagnetic ratio)
static const int constFieldID = 4; ///< Identifier for magnetic field constant (B or -B)
static const int constEnergyID = 5; ///< Identifier for energy constant (EN or -EN)
static const int constTempID = 6; ///< Identifier for temperature constant (T# or -T#)
static const int funLabelID = 7; ///< Identifier for function label (FUN#)
static const int parameterID = 8; ///< Identifier for parameter reference (PAR# or -PAR#)
static const int mapID = 9; ///< Identifier for map reference (MAP#)
static const int functionID = 10; ///< Identifier for mathematical functions (cos, sin, exp, etc.)
static const int powerID = 11; ///< Identifier for power function (POW)
static const int factorID = 12; ///< Identifier for factor in expression
static const int termID = 13; ///< Identifier for term in expression
static const int expressionID = 14; ///< Identifier for expression
static const int assignmentID = 15; ///< Identifier for assignment statement
//------------------------------------------------------------------------
/**
* \brief Inner template structure defining the grammar rules.
*
* This template structure contains the actual grammar rule definitions
* using Boost.Spirit syntax. It defines how the parser should recognize
* and build an abstract syntax tree (AST) for function expressions.
*
* \tparam ScannerT Scanner type used by Boost.Spirit for parsing
*/
template <typename ScannerT>
struct definition
{
//--------------------------------------------------------------------
/**
* \brief Constructor that defines all grammar rules.
*
* Sets up the complete grammar hierarchy for parsing function expressions:
* - Terminals: real numbers, constants (PI, GAMMA_MU, B, EN, T), parameters (PAR), maps (MAP)
* - Functions: trigonometric (cos, sin, tan), hyperbolic (cosh, sinh, tanh),
* inverse trigonometric (acos, asin, atan), inverse hyperbolic (acosh, asinh, atanh),
* logarithmic (log, ln), exponential (exp), square root (sqrt), power (pow)
* - Operators: addition (+), subtraction (-), multiplication (*), division (/)
* - Expressions: Hierarchical structure following operator precedence
*
* \param self Reference to the enclosing PFunctionGrammar (unused but required by Boost.Spirit)
*/
definition(PFunctionGrammar const& /*self*/)
{
// Start grammar definition
@@ -163,22 +219,31 @@ struct PFunctionGrammar : public grammar<PFunctionGrammar>
BOOST_SPIRIT_DEBUG_RULE(assignment);
}
rule<ScannerT, parser_context<>, parser_tag<assignmentID> > assignment;
rule<ScannerT, parser_context<>, parser_tag<expressionID> > expression;
rule<ScannerT, parser_context<>, parser_tag<termID> > term;
rule<ScannerT, parser_context<>, parser_tag<factorID> > factor;
rule<ScannerT, parser_context<>, parser_tag<functionID> > function;
rule<ScannerT, parser_context<>, parser_tag<powerID> > power;
rule<ScannerT, parser_context<>, parser_tag<mapID> > map;
rule<ScannerT, parser_context<>, parser_tag<parameterID> > parameter;
rule<ScannerT, parser_context<>, parser_tag<funLabelID> > fun_label;
rule<ScannerT, parser_context<>, parser_tag<constTempID> > const_temp;
rule<ScannerT, parser_context<>, parser_tag<constEnergyID> > const_energy;
rule<ScannerT, parser_context<>, parser_tag<constFieldID> > const_field;
rule<ScannerT, parser_context<>, parser_tag<constGammaMuID> > const_gamma_mu;
rule<ScannerT, parser_context<>, parser_tag<constPiID> > const_pi;
rule<ScannerT, parser_context<>, parser_tag<realID> > real;
rule<ScannerT, parser_context<>, parser_tag<assignmentID> > assignment; ///< Rule for assignment: FUN# = expression
rule<ScannerT, parser_context<>, parser_tag<expressionID> > expression; ///< Rule for expression: term { ('+' | '-') term }
rule<ScannerT, parser_context<>, parser_tag<termID> > term; ///< Rule for term: factor { ('*' | '/') factor }
rule<ScannerT, parser_context<>, parser_tag<factorID> > factor; ///< Rule for factor: operand or parenthesized expression
rule<ScannerT, parser_context<>, parser_tag<functionID> > function; ///< Rule for mathematical functions
rule<ScannerT, parser_context<>, parser_tag<powerID> > power; ///< Rule for power function POW(base, exponent)
rule<ScannerT, parser_context<>, parser_tag<mapID> > map; ///< Rule for map reference MAP#
rule<ScannerT, parser_context<>, parser_tag<parameterID> > parameter; ///< Rule for parameter reference PAR# or -PAR#
rule<ScannerT, parser_context<>, parser_tag<funLabelID> > fun_label; ///< Rule for function label FUN#
rule<ScannerT, parser_context<>, parser_tag<constTempID> > const_temp; ///< Rule for temperature constant T# or -T#
rule<ScannerT, parser_context<>, parser_tag<constEnergyID> > const_energy; ///< Rule for energy constant EN or -EN
rule<ScannerT, parser_context<>, parser_tag<constFieldID> > const_field; ///< Rule for field constant B or -B
rule<ScannerT, parser_context<>, parser_tag<constGammaMuID> > const_gamma_mu;///< Rule for muon gyromagnetic ratio constant
rule<ScannerT, parser_context<>, parser_tag<constPiID> > const_pi; ///< Rule for PI constant
rule<ScannerT, parser_context<>, parser_tag<realID> > real; ///< Rule for real number literals
//--------------------------------------------------------------------
/**
* \brief Returns the starting rule for the grammar.
*
* The parser begins by matching the assignment rule, which represents
* a complete function definition (e.g., FUN1 = PAR1 * cos(PAR2 * PI)).
*
* \return Reference to the assignment rule as the grammar entry point
*/
rule<ScannerT, parser_context<>, parser_tag<assignmentID> > const&
start() const { return assignment; }
};