PUserFcnBase Class Reference

Abstract base class for user-defined theory functions in musrfit. More...

#include <PUserFcnBase.h>

Inheritance diagram for PUserFcnBase:

Collaboration diagram for PUserFcnBase:

Public Member Functions
	PUserFcnBase ()
	Default constructor.
virtual	~PUserFcnBase ()
	Virtual destructor.
virtual Bool_t	NeedGlobalPart () const
virtual void	SetGlobalPart (std::vector< void * > &globalPart, UInt_t idx)
virtual Bool_t	GlobalPartIsValid () const
virtual Double_t	operator() (Double_t t, const std::vector< Double_t > &param) const =0

Detailed Description

Abstract base class for user-defined theory functions in musrfit.

PUserFcnBase enables extending musrfit with custom theory functions beyond the 34 built-in functions. Users create derived classes implementing specific physics models, compile them into shared libraries, and load them dynamically at runtime via ROOT's plugin mechanism.

Use Cases

User functions are valuable for:

• Novel relaxation mechanisms not in standard library
• Material-specific models (e.g., Skyrmion lattices, spin ice)
• Complex multi-component functions requiring custom logic
• Proprietary or experimental theory functions under development
• Functions requiring external libraries (GSL, CUDA, MKL, etc.)
• Performance-critical implementations with custom optimization

Implementation Guide

Step 1: Create header file (MyUserFcn.h)

#ifndef MY_USER_FCN_H
#define MY_USER_FCN_H
 
#include "PUserFcnBase.h"
 
class TMyRelaxation : public PUserFcnBase {
  public:
    TMyRelaxation() {}
    virtual ~TMyRelaxation() {}
 
    virtual Double_t operator()(Double_t t, const std::vector<Double_t> &par) const;
 
    ClassDef(TMyRelaxation, 1)
};
 
#endif

Step 2: Implement source file (MyUserFcn.cpp)

#include "MyUserFcn.h"
#include <cmath>
 
ClassImp(TMyRelaxation)
 
Double_t TMyRelaxation::operator()(Double_t t, const std::vector<Double_t> &par) const {
    // par[0] = rate (lambda), par[1] = exponent (beta)
    if (t < 0) return 1.0;
    return exp(-pow(par[0] * t, par[1]));
}

Step 3: Create LinkDef file (MyUserFcnLinkDef.h)

#ifdef __CINT__
#pragma link off all globals;
#pragma link off all classes;
#pragma link off all functions;
 
#pragma link C++ class TMyRelaxation+;
#endif

Step 4: Build shared library

rootcint -f MyUserFcnDict.cxx -c MyUserFcn.h MyUserFcnLinkDef.h
g++ -shared -fPIC -o libMyUserFcn.so MyUserFcn.cpp MyUserFcnDict.cxx \
    $(root-config --cflags --libs) -I$MUSRFIT/include

Step 5: Use in MSR file

THEORY
asymmetry    1
userFcn  libMyUserFcn.so  TMyRelaxation  2  3  (rate, exponent)

Global Part for Expensive Computations

For functions requiring expensive one-time setup (lookup tables, matrix decompositions, file loading), implement the global part interface:

class TMyComplexFcn : public PUserFcnBase {
  private:
    mutable void *fGlobal;  // Pointer to global data
 
  public:
    virtual Bool_t NeedGlobalPart() const { return true; }
 
    virtual void SetGlobalPart(std::vector<void*> &globalPart, UInt_t idx) {
        if (idx < globalPart.size() && globalPart[idx] != nullptr) {
            fGlobal = globalPart[idx];  // Reuse existing
        } else {
            fGlobal = new MyGlobalData();  // Create new
            static_cast<MyGlobalData*>(fGlobal)->Initialize();
            if (idx < globalPart.size())
                globalPart[idx] = fGlobal;
            else
                globalPart.push_back(fGlobal);
        }
    }
 
    virtual Bool_t GlobalPartIsValid() const {
        return fGlobal != nullptr;
    }
 
    // ... operator() uses fGlobal for fast lookup
};

Parameter Conventions

In the MSR file THEORY block:

userFcn  libName.so  ClassName  param1  param2  ...  paramN

Parameters can be:

• Direct numbers: 1, 2 → parameter indices from FITPARAMETER block
• Map references: map1, map2 → via RUN block map
• Function references: fun1, fun2 → evaluated FUNCTIONS

Convention: The last parameter is typically a time shift.

See also

PTheory for how user functions are loaded and called

PUserFcn for a simple example implementation

Definition at line 169 of file PUserFcnBase.h.

Constructor & Destructor Documentation

PUserFcnBase()

PUserFcnBase::PUserFcnBase ( )

inline

Default constructor.

Definition at line 173 of file PUserFcnBase.h.

Referenced by operator()().

~PUserFcnBase()

virtual PUserFcnBase::~PUserFcnBase ( )

inlinevirtual

Virtual destructor.

Definition at line 176 of file PUserFcnBase.h.

Member Function Documentation

GlobalPartIsValid()

virtual Bool_t PUserFcnBase::GlobalPartIsValid ( ) const

inlinevirtual

Checks if the global part initialized correctly.

Override to validate your global data structure after SetGlobalPart().

Returns

true if global part is valid and ready, false otherwise (default: false)

Definition at line 207 of file PUserFcnBase.h.

NeedGlobalPart()

virtual Bool_t PUserFcnBase::NeedGlobalPart ( ) const

inlinevirtual

Indicates if this function requires global initialization.

Override to return true if your function needs expensive one-time setup (e.g., calculating lookup tables, loading external data). The global part is computed once and reused across fit iterations.

Returns

true if global part needed, false otherwise (default: false)

Definition at line 187 of file PUserFcnBase.h.

operator()()

virtual Double_t PUserFcnBase::operator() ( Double_t t, const std::vector< Double_t > & param ) const

pure virtual

Evaluates the user function at time t (pure virtual).

This is the core evaluation method called for each data point during fitting. Must be implemented by derived classes.

Parameter convention: The last parameter is typically the time shift. Earlier parameters are model-specific (rates, amplitudes, exponents, etc.).

Parameters

t	Time in microseconds (μs)
param	Vector of function parameters (from MSR file + maps)

Returns

Function value at time t

Implemented in PUserFcn.

References PUserFcnBase().

SetGlobalPart()

virtual void PUserFcnBase::SetGlobalPart ( std::vector< void * > & globalPart, UInt_t idx )

inlinevirtual

Sets up the global part of the user function.

Called once during initialization if NeedGlobalPart() returns true. Use this to allocate and initialize shared data structures.

Parameters

globalPart	Vector of global objects (one per run)
idx	Index of this run's global object in the vector

Definition at line 198 of file PUserFcnBase.h.

---

The documentation for this class was generated from the following file:

• /workspace/LMU/musrfit/src/include/PUserFcnBase.h