/***************************************************************************

  PUserFcn.h

  Author: Andreas Suter
  e-mail: andreas.suter@psi.ch

***************************************************************************/

/***************************************************************************
 *   Copyright (C) 2007-2025 by Andreas Suter                              *
 *   andreas.suter@psi.ch                                                  *
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 *   This program is distributed in the hope that it will be useful,       *
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
 *   GNU General Public License for more details.                          *
 *                                                                         *
 *   You should have received a copy of the GNU General Public License     *
 *   along with this program; if not, write to the                         *
 *   Free Software Foundation, Inc.,                                       *
 *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
 ***************************************************************************/

#ifndef _PUSERFCN_H_
#define _PUSERFCN_H_

#include <vector>

#include "PUserFcnBase.h"

//--------------------------------------------------------------------------------------------
/**
 * \brief Example user function implementing a third-order polynomial.
 *
 * PUserFcn demonstrates how to create custom theory functions by deriving
 * from PUserFcnBase. This example implements a cubic polynomial:
 *
 * \f[ P(t) = a_0 + a_1 t + a_2 t^2 + a_3 t^3 \f]
 *
 * where \f$a_0, a_1, a_2, a_3\f$ are the polynomial coefficients passed
 * as fit parameters.
 *
 * \section puserfcn_usage Usage in MSR File
 *
 * To use this function in your analysis:
 *
 * \code
 * FITPARAMETER
 * #  No Name       Value  Step   Pos_Error Boundaries
 *     1 a0         1.0    0.1    none
 *     2 a1         0.01   0.001  none
 *     3 a2         0.001  0.0001 none
 *     4 a3         0.0001 0.00001 none
 *
 * THEORY
 * userFcn  libPUserFcn.so  PUserFcn  1 2 3 4  (a0, a1, a2, a3)
 * \endcode
 *
 * \section puserfcn_applications Applications
 *
 * Polynomial backgrounds are useful for:
 * - Modeling baseline drifts in long-time measurements
 * - Phenomenological fits to slowly varying relaxation
 * - Testing the user function infrastructure
 *
 * \section puserfcn_template As a Template
 *
 * This class serves as a minimal working example for creating custom
 * user functions. To create your own:
 *
 * 1. Copy PUserFcn.h and PUserFcn.cpp
 * 2. Rename the class and update the ClassDef/ClassImp macros
 * 3. Implement your physics in the operator() method
 * 4. Create a LinkDef.h and build as a shared library
 *
 * \see PUserFcnBase for the abstract interface and detailed implementation guide
 * \see PTheory for how user functions are loaded and evaluated
 */
class PUserFcn : public PUserFcnBase
{
  public:
    /// \brief Default constructor.
    PUserFcn();

    /// \brief Destructor.
    ~PUserFcn();

    /**
     * \brief Evaluates the third-order polynomial at time t.
     *
     * Computes:
     * \f[ P(t) = \texttt{param[0]} + \texttt{param[1]} \cdot t
     *          + \texttt{param[2]} \cdot t^2 + \texttt{param[3]} \cdot t^3 \f]
     *
     * \param t Time value (typically in microseconds)
     * \param param Vector of polynomial coefficients:
     *        - param[0]: constant term \f$a_0\f$
     *        - param[1]: linear coefficient \f$a_1\f$ (per μs)
     *        - param[2]: quadratic coefficient \f$a_2\f$ (per μs²)
     *        - param[3]: cubic coefficient \f$a_3\f$ (per μs³)
     *
     * \return The polynomial value at time t
     */
    Double_t operator()(Double_t t, const std::vector<Double_t> &param) const;

  ClassDef(PUserFcn, 1)
};

#endif // _PUSERFCN_H_