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

improve doxygen documentation of PRgeHandler.*

Browse Source
This commit is contained in:
suter_a
2025-11-14 10:05:36 +01:00
parent 8de507441c
commit 019a16e1aa
2 changed files with 330 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

163
src/classes/PRgeHandler.cpp
View File

@@ -45,7 +45,10 @@ ClassImpQ(PXmlRgeHandler)
// OnStartDocument
//--------------------------------------------------------------------------
/**
* <p>Called on start of the XML file reading. Initializes all necessary variables.
* \brief SAX callback invoked at the start of XML document parsing.
*
* Initializes the parsing state by resetting the key to empty. This ensures
* clean state for processing the XML content.
*/
void PXmlRgeHandler::OnStartDocument()
{
@@ -56,7 +59,14 @@ void PXmlRgeHandler::OnStartDocument()
// OnEndDocument
//--------------------------------------------------------------------------
/**
* <p>Called on end of XML file reading.
* \brief SAX callback invoked at the end of XML document parsing.
*
* Performs final validation to ensure all required fields were parsed:
* - TrimSP data path must be set
* - RGE filename prefix must be set
* - At least one implantation energy must be specified
*
* Sets fIsValid to false and calls OnError() if any validation fails.
*/
void PXmlRgeHandler::OnEndDocument()
{
@@ -85,11 +95,19 @@ void PXmlRgeHandler::OnEndDocument()
// OnStartElement
//--------------------------------------------------------------------------
/**
* <p>Called when a XML start element is found. Filters out the needed elements
* and sets a proper key.
* \brief SAX callback invoked when an XML start tag is encountered.
*
* Processes recognized elements within the <trim_sp> section:
* - <data_path>: Directory containing RGE files
* - <rge_fln_pre>: RGE filename prefix
* - <energy>: Single implantation energy value
* - <energy_vect>: Energy range with start/stop/step attributes
*
* For <energy_vect>, parses the attributes and generates the energy list.
* Performs extensive validation on attribute values and ranges.
*
* \param str XML element name
* \param attributes used only for energy_vect
* \param attributes Element attributes (only used for energy_vect)
*/
void PXmlRgeHandler::OnStartElement(const Char_t *str, const TList *attributes)
{
@@ -182,9 +200,12 @@ void PXmlRgeHandler::OnStartElement(const Char_t *str, const TList *attributes)
// OnEndElement
//--------------------------------------------------------------------------
/**
* <p>Called when a XML end element is found. Resets the handler key.
* \brief SAX callback invoked when an XML end tag is encountered.
*
* \param str not used
* Resets the parsing state when leaving the <trim_sp> section and
* clears the current element key for all end tags.
*
* \param str XML element name
*/
void PXmlRgeHandler::OnEndElement(const Char_t *str)
{
@@ -199,10 +220,17 @@ void PXmlRgeHandler::OnEndElement(const Char_t *str)
// OnCharacters
//--------------------------------------------------------------------------
/**
* <p>Content of a given XML element. Filters out the data and feeds them to
* the internal variables.
* \brief SAX callback invoked for text content between XML tags.
*
* \param str XML element string
* Processes the content based on the current parsing state (fKey):
* - eDataPath: Stores the data directory path
* - eFlnPre: Stores the RGE filename prefix
* - eEnergy: Parses integer energy value and adds to energy list
*
* Performs validation and error handling for energy values, ensuring
* they are valid integers within range.
*
* \param str Text content from XML element
*/
void PXmlRgeHandler::OnCharacters(const Char_t *str)
{
@@ -249,9 +277,11 @@ void PXmlRgeHandler::OnCharacters(const Char_t *str)
// OnComment
//--------------------------------------------------------------------------
/**
* <p>Called when a XML comment is found. Not used.
* \brief SAX callback invoked for XML comments.
*
* \param str not used.
* Currently not used - comments are ignored.
*
* \param str Comment text
*/
void PXmlRgeHandler::OnComment(const Char_t *str)
{
@@ -262,9 +292,11 @@ void PXmlRgeHandler::OnComment(const Char_t *str)
// OnWarning
//--------------------------------------------------------------------------
/**
* <p>Called when the XML parser emits a warning.
* \brief SAX callback invoked when the parser emits a warning.
*
* \param str warning string
* Prints warning message to stderr.
*
* \param str Warning message from parser
*/
void PXmlRgeHandler::OnWarning(const Char_t *str)
{
@@ -276,9 +308,12 @@ void PXmlRgeHandler::OnWarning(const Char_t *str)
// OnError
//--------------------------------------------------------------------------
/**
* <p>Called when the XML parser emits an error.
* \brief SAX callback invoked when the parser encounters an error.
*
* \param str error string
* Prints error message to stderr. Called both by the parser and
* by this handler's own validation code.
*
* \param str Error message
*/
void PXmlRgeHandler::OnError(const Char_t *str)
{
@@ -290,9 +325,11 @@ void PXmlRgeHandler::OnError(const Char_t *str)
// OnFatalError
//--------------------------------------------------------------------------
/**
* <p>Called when the XML parser emits a fatal error.
* \brief SAX callback invoked when the parser encounters a fatal error.
*
* \param str fatal error string
* Prints fatal error message to stderr. Fatal errors typically stop parsing.
*
* \param str Fatal error message
*/
void PXmlRgeHandler::OnFatalError(const Char_t *str)
{
@@ -304,10 +341,12 @@ void PXmlRgeHandler::OnFatalError(const Char_t *str)
// OnCdataBlock
//--------------------------------------------------------------------------
/**
* <p>Not used.
* \brief SAX callback invoked for CDATA blocks.
*
* \param str not used
* \param len not used
* Currently not used - CDATA blocks are ignored.
*
* \param str CDATA content
* \param len Length of CDATA content
*/
void PXmlRgeHandler::OnCdataBlock(const Char_t *str, Int_t len)
{
@@ -322,8 +361,18 @@ ClassImp(PRgeHandler)
// Ctor
//--------------------------------------------------------------------------
/**
* @brief PRgeHandler::PRgeHandler
* @param fln
* \brief Constructor that loads TrimSP range distribution data.
*
* Performs the following steps:
* 1. Validates that XML configuration filename is provided
* 2. Parses XML file using PXmlRgeHandler to get file paths and energies
* 3. Reads all specified .rge files from TrimSP
* 4. Calculates total particle counts for each energy
* 5. Computes normalized distributions nn(z) where ∫nn(z)dz = 1
*
* Sets fValid to false if any errors occur during loading.
*
* \param fln Path to XML configuration file (empty triggers error)
*/
PRgeHandler::PRgeHandler(const std::string fln)
{
@@ -440,10 +489,18 @@ PRgeHandler::PRgeHandler(const std::string fln)
// ReadRgeFile
//--------------------------------------------------------------------------
/**
* <p>Read the content of a rge-file.
* \brief Reads a single TrimSP .rge file and populates a PRgeData structure.
*
* @param fln file name of the rge-file
* @return true on success.
* Parses the two-column format from TrimSP output:
* - Column 1: Depth in Ångström (converted to nm by dividing by 10)
* - Column 2: Number of particles (amplitude)
*
* Skips empty lines and non-numeric lines. Performs extensive validation
* on numeric values with detailed error messages.
*
* \param fln Path to the .rge file
* \param data PRgeData structure to populate with depth and amplitude vectors
* \return True on success, false if file cannot be opened or contains invalid data
*/
bool PRgeHandler::ReadRgeFile(const std::string fln, PRgeData &data)
{
@@ -553,10 +610,13 @@ bool PRgeHandler::ReadRgeFile(const std::string fln, PRgeData &data)
// GetZmax via energy
//--------------------------------------------------------------------------
/**
* <p>Get maximal depth for a given energy.
* \brief Returns maximum penetration depth for a given implantation energy.
*
* @param energy energy in (eV)
* @return zMax if energy is found, -1 otherwise.
* Searches for a data set matching the specified energy (within 0.9 keV
* tolerance) and returns its maximum depth value.
*
* \param energy Implantation energy in eV
* \return Maximum depth in nm, or -1 if energy not found
*/
Double_t PRgeHandler::GetZmax(const Double_t energy)
{
@@ -567,7 +627,7 @@ Double_t PRgeHandler::GetZmax(const Double_t energy)
break;
}
}
if (idx != -1)
return GetZmax(idx);
@@ -578,10 +638,13 @@ Double_t PRgeHandler::GetZmax(const Double_t energy)
// GetZmax via index
//--------------------------------------------------------------------------
/**
* <p>Get maximal depth for a given index.
* \brief Returns maximum penetration depth for a given data set index.
*
* @param idx index for which zMax is requested.
* @return zMax if idx is in range, -1 otherwise.
* Returns the last depth value from the depth vector, which represents
* the maximum penetration depth for this energy.
*
* \param idx Data set index (0 to GetNoOfRgeDataSets()-1)
* \return Maximum depth in nm, or -1 if idx out of range
*/
Double_t PRgeHandler::GetZmax(const Int_t idx)
{
@@ -595,11 +658,14 @@ Double_t PRgeHandler::GetZmax(const Int_t idx)
// Get_n via energy
//--------------------------------------------------------------------------
/**
* <p>Get the normalized n(E,z) value.
* \brief Returns normalized particle distribution at given energy and depth.
*
* @param energy (eV)
* @param z (nm)
* @return n(E,z) if energy and z are in proper range, -1.0 otherwise.
* Searches for a data set matching the specified energy (within 0.9 keV
* tolerance) and returns the normalized distribution value at depth z.
*
* \param energy Implantation energy in eV
* \param z Depth in nm
* \return Normalized distribution nn(E,z), or 0.0 if energy not found or z out of range
*/
Double_t PRgeHandler::Get_n(const Double_t energy, const Double_t z)
{
@@ -620,11 +686,17 @@ Double_t PRgeHandler::Get_n(const Double_t energy, const Double_t z)
// Get_n via index
//--------------------------------------------------------------------------
/**
* <p>Get the normalized n(idx,z) value.
* \brief Returns normalized particle distribution at given index and depth.
*
* @param idx index of the rge-dataset
* @param z (nm)
* @return n(idx,z) if idx and z are in proper range, -1.0 otherwise.
* Uses linear interpolation between adjacent data points to compute the
* distribution value at the requested depth. The normalization ensures
* that ∫nn(z)dz = 1 over the entire depth range.
*
* Special handling for z near zero: extrapolates linearly from first data point.
*
* \param idx Data set index (0 to GetNoOfRgeDataSets()-1)
* \param z Depth in nm
* \return Normalized distribution nn(idx,z), or 0.0 if idx or z out of range
*/
Double_t PRgeHandler::Get_n(const Int_t idx, const Double_t z)
{
@@ -658,10 +730,13 @@ Double_t PRgeHandler::Get_n(const Int_t idx, const Double_t z)
// GetEnergyIndex
//--------------------------------------------------------------------------
/**
* <p>Get the energy index by providing an energy in (eV).
* \brief Finds the data set index corresponding to a given implantation energy.
*
* @param energy in (eV).
* @return energy index if energy was found, -1 otherwise.
* Searches through loaded data sets for a matching energy value using a
* tolerance of 0.9 keV (i.e., |E_data - E_query| < 0.9 keV).
*
* \param energy Implantation energy in eV
* \return Data set index (0 to GetNoOfRgeDataSets()-1), or -1 if not found
*/
Int_t PRgeHandler::GetEnergyIndex(const Double_t energy)
{

237
src/include/PRgeHandler.h
View File

@@ -41,86 +41,271 @@
//-----------------------------------------------------------------------------
/**
* <p>Keep a single rge table from TrimSP for a given energy.
* \brief Data structure for a single TrimSP range distribution at a given energy.
*
* PRgeData stores the muon/particle implantation depth profile calculated by
* TrimSP (Transport of Ions in Matter - Stopping and Range) for a specific
* implantation energy. It contains the depth distribution n(z) and normalized
* distribution nn(z) where ∫nn(z)dz = 1.
*
* \see PRgeHandler for the class that reads and manages RGE data
* \see PRgeDataList for collections of RGE data sets
*/
struct PRgeData {
Double_t energy;
PDoubleVector depth;
PDoubleVector amplitude;
PDoubleVector nn; // normalized int n(z) dz = 1 amplitudes
Double_t noOfParticles;
Double_t energy; ///< Implantation energy in eV
PDoubleVector depth; ///< Depth values in nanometers (nm)
PDoubleVector amplitude; ///< Number of particles at each depth (raw counts from TrimSP)
PDoubleVector nn; ///< Normalized particle density where ∫nn(z)dz = 1
Double_t noOfParticles; ///< Total number of particles (sum of amplitudes)
};
//-----------------------------------------------------------------------------
/**
* <p>Keep all rge tables from TrimSP.
* \brief Container for multiple TrimSP range distributions at different energies.
*
* PRgeDataList is a vector of PRgeData structures, typically containing
* implantation profiles for a range of energies (e.g., 1-30 keV).
*/
typedef std::vector<PRgeData> PRgeDataList;
//-----------------------------------------------------------------------------
/**
* <p>Reads the xml-startup file in order to extract all necessary information
* about the RGE files (TrimSP) needed.
* \brief XML SAX parser handler for TrimSP configuration files.
*
* PXmlRgeHandler parses XML configuration files to extract TrimSP (Transport
* of Ions in Matter) data file locations and parameters. The XML file specifies:
* - Data path: Directory containing .rge files
* - Filename prefix: Base name for RGE files (e.g., "LCCO_E")
* - Energy list: Implantation energies (individual values or start/stop/step)
*
* This handler implements ROOT's TSAXParser callbacks for event-driven XML parsing.
*
* \par XML Format Example:
* \code{.xml}
* <trim_sp>
* <data_path>/path/to/rge/files</data_path>
* <rge_fln_pre>Material_E</rge_fln_pre>
* <energy>1000</energy>
* <energy>5000</energy>
* <energy_vect start="10000" stop="30000" step="1000"/>
* </trim_sp>
* \endcode
*
* \see PRgeHandler for the main RGE data manager
* \see TSAXParser for ROOT's SAX parser implementation
*/
class PXmlRgeHandler : public TObject, public TQObject
{
public:
/// Default constructor
PXmlRgeHandler() {}
/// Destructor
virtual ~PXmlRgeHandler() {}
/// Called at start of XML document parsing (SLOT)
virtual void OnStartDocument(); // SLOT
/// Called at end of XML document parsing, performs validation (SLOT)
virtual void OnEndDocument(); // SLOT
virtual void OnStartElement(const char*, const TList*); // SLOT
virtual void OnEndElement(const char*); // SLOT
virtual void OnCharacters(const char*); // SLOT
virtual void OnComment(const char*); // SLOT
virtual void OnWarning(const char*); // SLOT
virtual void OnError(const char*); // SLOT
virtual void OnFatalError(const char*); // SLOT
virtual void OnCdataBlock(const char*, Int_t); // SLOT
/**
* \brief Called when XML start tag is encountered (SLOT)
* \param str Element name
* \param attributes Element attributes (used for energy_vect)
*/
virtual void OnStartElement(const char* str, const TList* attributes); // SLOT
/**
* \brief Called when XML end tag is encountered (SLOT)
* \param str Element name
*/
virtual void OnEndElement(const char* str); // SLOT
/**
* \brief Called for element content between tags (SLOT)
* \param str Character data
*/
virtual void OnCharacters(const char* str); // SLOT
/**
* \brief Called for XML comments (SLOT)
* \param str Comment text
*/
virtual void OnComment(const char* str); // SLOT
/**
* \brief Called when parser emits a warning (SLOT)
* \param str Warning message
*/
virtual void OnWarning(const char* str); // SLOT
/**
* \brief Called when parser encounters an error (SLOT)
* \param str Error message
*/
virtual void OnError(const char* str); // SLOT
/**
* \brief Called when parser encounters a fatal error (SLOT)
* \param str Fatal error message
*/
virtual void OnFatalError(const char* str); // SLOT
/**
* \brief Called for CDATA blocks (SLOT)
* \param str CDATA content
* \param len Length of CDATA
*/
virtual void OnCdataBlock(const char* str, Int_t len); // SLOT
/**
* \brief Returns validity status of parsed configuration.
* \return True if XML was parsed successfully and all required fields are present
*/
virtual bool IsValid() { return fIsValid; }
/**
* \brief Returns the TrimSP data directory path.
* \return Directory path containing .rge files
*/
virtual std::string GetTrimSpDataPath() { return fTrimSpDataPath; }
/**
* \brief Returns the RGE filename prefix.
* \return Filename prefix (e.g., "LCCO_E" for files like LCCO_E1000.rge)
*/
virtual std::string GetTrimSpFlnPre() { return fTrimSpFlnPre; }
/**
* \brief Returns the list of implantation energies.
* \return Vector of energies in eV
*/
virtual const PIntVector GetTrimSpDataVectorList() const { return fTrimSpDataEnergyList; }
private:
/// Enum for tracking which XML element is currently being parsed
enum EKeyWords {eEmpty, eDataPath, eFlnPre, eEnergy};
EKeyWords fKey;
EKeyWords fKey; ///< Current parsing context/state
bool isTrimSp{false};
bool fIsValid{true};
bool isTrimSp{false}; ///< True when inside <trim_sp> element
bool fIsValid{true}; ///< Validity flag (false if parsing errors occur)
std::string fTrimSpDataPath{""}; //< where to find the rge-files
std::string fTrimSpFlnPre{""}; //< keeps the preface of the rge file name, e.g. LCCO_E
PIntVector fTrimSpDataEnergyList; //< TrimSP implantation energy list (in eV)
std::string fTrimSpDataPath{""}; ///< Directory path to RGE files
std::string fTrimSpFlnPre{""}; ///< RGE filename prefix (e.g., "LCCO_E" for LCCO_E1000.rge)
PIntVector fTrimSpDataEnergyList; ///< List of implantation energies in eV
ClassDef(PXmlRgeHandler, 1)
};
//-----------------------------------------------------------------------------
/**
* @brief The PRegHandler class
* \brief Manager for TrimSP range distribution data.
*
* PRgeHandler reads and manages muon/particle implantation depth profiles
* calculated by TrimSP (Transport of Ions in Matter - Stopping and Range).
* It provides access to:
* - Particle implantation depth distributions n(E,z)
* - Normalized distributions nn(E,z) where ∫nn(z)dz = 1
* - Maximum penetration depths for different energies
*
* The class loads RGE files specified in an XML configuration file, which
* can contain data for multiple implantation energies. RGE files contain
* depth (in Ångström) vs. particle count data from TrimSP simulations.
*
* \par Typical Usage:
* \code
* PRgeHandler rge("config.xml");
* if (rge.IsValid()) {
* Double_t zmax = rge.GetZmax(5000.0); // Max depth at 5 keV
* Double_t n = rge.Get_n(5000.0, 10.0); // Distribution at 5 keV, 10 nm depth
* }
* \endcode
*
* \see PRgeData for the data structure holding individual distributions
* \see PXmlRgeHandler for XML configuration parsing
*/
class PRgeHandler : public TObject
{
public:
/**
* \brief Constructor that loads TrimSP data from XML configuration.
* \param fln Path to XML configuration file (empty string for manual setup)
*
* Parses the XML file to get RGE file locations and energies, then loads
* all specified RGE files. Sets fValid to false if any errors occur.
*/
PRgeHandler(std::string fln="");
/// Destructor
virtual ~PRgeHandler() {}
/**
* \brief Returns validity status.
* \return True if all RGE files loaded successfully, false if errors occurred
*/
virtual bool IsValid() { return fValid; }
/**
* \brief Returns number of loaded RGE data sets.
* \return Number of energy data sets (one per energy value)
*/
virtual UInt_t GetNoOfRgeDataSets() { return (UInt_t)fData.size(); }
/**
* \brief Returns all RGE data sets.
* \return Vector of all loaded PRgeData structures
*/
virtual PRgeDataList GetRgeData() { return fData; }
/**
* \brief Returns maximum penetration depth for a given energy.
* \param energy Implantation energy in eV
* \return Maximum depth in nm, or -1 if energy not found
*/
virtual Double_t GetZmax(const Double_t energy);
/**
* \brief Returns maximum penetration depth for a data set index.
* \param idx Data set index (0 to GetNoOfRgeDataSets()-1)
* \return Maximum depth in nm, or -1 if idx out of range
*/
virtual Double_t GetZmax(const Int_t idx);
/**
* \brief Returns normalized particle distribution at given energy and depth.
* \param energy Implantation energy in eV
* \param z Depth in nm
* \return Normalized distribution nn(E,z), or 0.0 if out of range
*
* Uses linear interpolation between data points. The normalization ensures
* that ∫nn(z)dz = 1 over the entire depth range.
*/
virtual Double_t Get_n(const Double_t energy, const Double_t z);
/**
* \brief Returns normalized particle distribution at given index and depth.
* \param idx Data set index (0 to GetNoOfRgeDataSets()-1)
* \param z Depth in nm
* \return Normalized distribution nn(idx,z), or 0.0 if out of range
*
* Uses linear interpolation between data points. The normalization ensures
* that ∫nn(z)dz = 1 over the entire depth range.
*/
virtual Double_t Get_n(const Int_t idx, const Double_t z);
/**
* \brief Finds the data set index for a given energy.
* \param energy Implantation energy in eV
* \return Data set index, or -1 if energy not found
*
* Uses tolerance of 0.9 keV for matching energies.
*/
virtual Int_t GetEnergyIndex(const Double_t energy);
private:
bool fValid{false};
PRgeDataList fData;
bool fValid{false}; ///< Validity flag (true if all RGE files loaded successfully)
PRgeDataList fData; ///< Collection of RGE data sets (one per energy)
/**
* \brief Reads a single RGE file and populates a PRgeData structure.
* \param fln Path to the .rge file
* \param data PRgeData structure to populate
* \return True on success, false on error
*
* Parses the two-column format (depth amplitude) from TrimSP output.
* Converts depth from Ångström to nanometers.
*/
virtual bool ReadRgeFile(const std::string fln, PRgeData &data);
ClassDef(PRgeHandler, 1)