[u/mrichter/AliRoot.git] / HLT / MUON / AliHLTMUONUtils.cxx

/**************************************************************************
 * Copyright(c) 1998-2007, ALICE Experiment at CERN, All rights reserved. *
 *                                                                        *
 * Author: The ALICE Off-line Project.                                    *
 * Contributors are mentioned in the code where appropriate.              *
 *                                                                        *
 * Permission to use, copy, modify and distribute this software and its   *
 * documentation strictly for non-commercial purposes is hereby granted   *
 * without fee, provided that the above copyright notice appears in all   *
 * copies and that both the copyright notice and this permission notice   *
 * appear in the supporting documentation. The authors make no claims     *
 * about the suitability of this software for any purpose. It is          *
 * provided "as is" without express or implied warranty.                  *
 **************************************************************************/

/* $Id$ */

///
/// @file   AliHLTMUONUtils.cxx
/// @author Artur Szostak <artursz@iafrica.com>
/// @date   
/// @brief  Implementation of AliHLTMUONUtils utility routines.
///

#include "AliHLTMUONUtils.h"
#include "AliHLTMUONConstants.h"
#include "AliHLTMUONTriggerRecordsBlockStruct.h"
#include "AliHLTMUONTrigRecsDebugBlockStruct.h"
#include "AliHLTMUONTriggerChannelsBlockStruct.h"
#include "AliHLTMUONRecHitsBlockStruct.h"
#include "AliHLTMUONClustersBlockStruct.h"
#include "AliHLTMUONChannelsBlockStruct.h"
#include "AliHLTMUONMansoTracksBlockStruct.h"
#include "AliHLTMUONMansoCandidatesBlockStruct.h"
#include "AliHLTMUONSinglesDecisionBlockStruct.h"
#include "AliHLTMUONPairsDecisionBlockStruct.h"
#include <cstring>
#include <cassert>


AliHLTUInt32_t AliHLTMUONUtils::PackTriggerRecordFlags(
		AliHLTMUONParticleSign sign, const bool hitset[4]
	)
{
	///
	/// This packs the given parameters into the bits of a word appropriate
	/// for AliHLTMUONTriggerRecordStruct::fFlags.
	/// @param sign    The particle sign.
	/// @param hitset  Flags to indicate if the corresponding fHits[i] elements
	///                was set/filled.
	/// @return  Returns the 32 bit packed word.
	///
	
	AliHLTUInt32_t flags;
	switch (sign)
	{
	case kSignMinus: flags = 0x80000000; break;
	case kSignPlus:  flags = 0x40000000; break;
	default:         flags = 0x00000000; break;
	}

	return flags | (hitset[0] ? 0x1 : 0) | (hitset[1] ? 0x2 : 0)
		| (hitset[2] ? 0x4 : 0) | (hitset[3] ? 0x8 : 0);
}


void AliHLTMUONUtils::UnpackTriggerRecordFlags(
		AliHLTUInt32_t flags, AliHLTMUONParticleSign& sign, bool hitset[4]
	)
{
	///
	/// This unpacks the AliHLTMUONTriggerRecordStruct::fFlags bits into
	/// its component fields.
	/// @param flags  The flags from an AliHLTMUONTriggerRecordStruct structure.
	/// @param sign    Sets this to the particle sign.
	/// @param hitset  Sets the array elements to indicate if the corresponding
	///                fHits[i] element was set/filled.
	///
	
	AliHLTUInt32_t signbits = flags & 0xC0000000;
	switch (signbits)
	{
	case 0x80000000: sign = kSignMinus;   break;
	case 0x40000000: sign = kSignPlus;    break;
	default:         sign = kSignUnknown; break;
	}
	hitset[0] = (flags & 0x1) == 0x1;
	hitset[1] = (flags & 0x2) == 0x2;
	hitset[2] = (flags & 0x4) == 0x4;
	hitset[3] = (flags & 0x8) == 0x8;
}


AliHLTUInt32_t AliHLTMUONUtils::PackTrackDecisionBits(bool highPt, bool lowPt)
{
	///
	/// This packs the given parameters into the bits of a word appropriate
	/// for AliHLTMUONTrackDecisionStruct::fTriggerBits.
	/// @param highPt  Has the track passed the high pt cut.
	/// @param lowPt   Has the track passed the low pt cut.
	/// @return  Returns the 32 bit packed word.
	///
	
	return (highPt ? 0x2 : 0) | (lowPt ? 0x1 : 0);
}


void AliHLTMUONUtils::UnpackTrackDecisionBits(
		AliHLTUInt32_t bits, bool& highPt, bool& lowPt
	)
{
	///
	/// This unpacks the AliHLTMUONTrackDecisionStruct::fTriggerBits bits into
	/// its component fields.
	/// @param bits  The trigger bits from an AliHLTMUONTrackDecisionStruct
	///              structure.
	/// @param highPt Sets this to the value of the high pt cut bit.
	/// @param lowPt  Sets this to the value of the low pt cut bit.
	///
	
	lowPt  = (bits & 0x1) == 0x1;
	highPt = (bits & 0x2) == 0x2;
}


AliHLTUInt32_t AliHLTMUONUtils::PackPairDecisionBits(
		bool highMass, bool lowMass, bool unlike,
		AliHLTUInt8_t highPtCount, AliHLTUInt8_t lowPtCount
	)
{
	///
	/// This packs the given parameters into the bits of a word appropriate
	/// for AliHLTMUONPairDecisionStruct::fTriggerBits.
	///
	/// @param highMass Has the track pair passed the high invariant mass cut.
	/// @param lowMass  Has the track pair passed the low invariant mass cut.
	/// @param unlike   Does the track pair have unlike signs.
	/// @param highPtCount The number of tracks that passed the high pt cut
	///                    in the pair.
	/// @param lowPtCount  The number of tracks that passed the low pt cut
	///                    in the pair.
	/// @return  Returns the 32 bit packed word.
	///
	/// Note: Must have highPtCount + lowPtCount <= 2 and unlike == true if
	/// highMass or lowMass is true.
	///
	
	assert( highPtCount + lowPtCount <= 2 );
	// highMass and lowMass must be false if unlike is false:
	assert( not unlike ? (highMass == false and lowMass == false) : true );
	
	return (highMass ? 0x40 : 0) | (lowMass ? 0x20 : 0) | (unlike ? 0x10 : 0)
		| ((highPtCount & 0x3) << 2) | (lowPtCount & 0x3);
}


void AliHLTMUONUtils::UnpackPairDecisionBits(
		AliHLTUInt32_t bits, bool& highMass, bool& lowMass, bool& unlike,
		AliHLTUInt8_t& highPtCount, AliHLTUInt8_t& lowPtCount
	)
{
	///
	/// This unpacks the AliHLTMUONPairDecisionStruct::fTriggerBits bits into
	/// its component fields.
	/// @param bits  The trigger bits from an AliHLTMUONPairDecisionStruct
	///              structure.
	/// @param highMass Sets this to the value of the high invariant mass cut bit.
	/// @param lowMass  Sets this to the value of the low invariant mass cut bit.
	/// @param unlike   Sets this if the pair is unlike sign.
	/// @param highPtCount Sets this to the high pt count bits.
	/// @param lowPtCount  Sets this to the low pt count bits.
	///
	
	highMass = (bits & 0x40) == 0x40;
	lowMass  = (bits & 0x20) == 0x20;
	unlike   = (bits & 0x10) == 0x10;
	highPtCount = (bits & 0xC) >> 2;
	lowPtCount = bits & 0x3;
}


AliHLTUInt32_t AliHLTMUONUtils::PackSpecBits(
		const bool ddl[22]
	)
{
	///
	/// This packs the given parameters into the 32bit Pub/Sub specification
	/// word in the data block descriptor.
	///
	/// @param ddl  The list of DDLs forming part of the readout. ddl[0]
	///             indicates DDL number 2560, ddl[1] is for DDL 2561 and so
	///             on up to ddl[19]. ddl[20] and ddl[21] will be for the
	///             trigger DDLs 2816 and 2817 respectively.
	/// @return  Returns the 32 bit packed specification word.
	///
	
	// Pack the bits into the following format:
	//   bit:   [        31 - 22        ][     21     ][     20     ][  19 - 0 ]
	//   field: [ reserved, set to zero ][ TRGDDL2817 ][ TRGDDL2816 ][ TRKDDLS ]
	// Meaning of field acronyms:
	//   TRGDDL2816 - Trigger DDL number 2816.
	//   TRGDDL2817 - Trigger DDL number 2817.
	//   TRKDDLS - Tracking DDL flags where bit 0 will be for DDL number 2560,
	//             bit 1 for DDL no. 2561 etc. up to bit 19 which is for DDL 2579.
	AliHLTUInt32_t bits = 0;
	for (int i = 0; i < 22; i++)
		bits |= (ddl[i] ? 0x1 : 0x0) << i;
	return bits;
}


void AliHLTMUONUtils::UnpackSpecBits(
		AliHLTUInt32_t bits, bool ddl[22]
	)
{
	///
	/// This unpacks the AliHLTMUONPairDecisionStruct::fTriggerBits bits into
	/// its component fields.
	/// @param bits  The Pub/Sub specification word from a data block descriptor.
	/// @param ddl  The output list of DDLs forming part of the readout. ddl[0]
	///             indicates DDL number 2560, ddl[1] is for DDL 2561 and so
	///             on up to ddl[19]. ddl[20] and ddl[21] will be for the
	///             trigger DDLs 2816 and 2817 respectively.
	///
	
	// Perform the inverse operation of PackSpecBits.
	for (int i = 0; i < 22; i++)
		ddl[i] = ((bits >> i) & 0x1) == 1;
}


AliHLTInt32_t AliHLTMUONUtils::DDLNumberToEquipId(AliHLTInt32_t ddlNo)
{
	///
	/// This method converts the DDL number for the muon spectrometer in the
	/// range [0..21] to the equipment ID number.
	/// @param ddlNo  The DDL number in the range [0..21].
	/// @return  Returns the equipment ID number or -1 if ddlNo was invalid.
	///
	
	if (0 <= ddlNo and ddlNo <= 19)
	{
		return 2560 + ddlNo;
	}
	else if (20 <= ddlNo and ddlNo <= 21)
	{
		return 2816 + (ddlNo - 20);
	}
	else
	{
		return -1;
	}
}


AliHLTInt32_t AliHLTMUONUtils::EquipIdToDDLNumber(AliHLTInt32_t id)
{
	///
	/// This method converts the equipment ID number for a muon spectrometer
	/// DDL to the DDL number in the range [0..21].
	/// @param id  The equipment ID of the DDL.
	/// @return  Returns the DDL number in the range [0..21] or -1 if the
	///          equipment ID was invalid.
	///
	
	if (2560 <= id and id <= 2560+19)
	{
		return id - 2560;
	}
	else if (2816 <= id and id <= 2817)
	{
		return id - 2816 + 20;
	}
	else
	{
		return -1;
	}
}


AliHLTInt32_t AliHLTMUONUtils::SpecToEquipId(AliHLTUInt32_t spec)
{
	///
	/// This method converts a 32 bit data block specification for a MUON-HLT
	/// data block into its corresponding DDL equipment ID number.
	/// It is assumed that the specification is for a data block comming from
	/// a single DDL source. If more than one DDL contributed to the data block
	/// then -1 is returned.
	/// @param spec  The 32 bit specification for a data block.
	/// @return  Returns the equipment ID corresponding to the specification
	///          or -1 if the specification was invalid.
	///
	
	for (AliHLTInt32_t ddlNo = 0; ddlNo < 20; ddlNo++)
	{
		if (spec == AliHLTUInt32_t(0x1 << ddlNo))
			return ddlNo + 2560;
	}
	for (AliHLTInt32_t ddlNo = 20; ddlNo < 22; ddlNo++)
	{
		if (spec == AliHLTUInt32_t(0x1 << ddlNo))
			return ddlNo - 20 + 2816;
	}
	return -1;
}


AliHLTUInt32_t AliHLTMUONUtils::EquipIdToSpec(AliHLTInt32_t id)
{
	///
	/// This method converts a equipment ID number for a DDL into its corresponding
	/// 32 bit data block specification for the MUON-HLT.
	/// @param id  The equipment ID number of the DDL.
	/// @return  Returns the 32 bit data block specification or 0x0 if the
	///          equipment ID was invalid.
	///
	
	if (2560 <= id and id <= 2560+19)
	{
		return 0x1 << (id - 2560);
	}
	else if (2816 <= id and id <= 2817)
	{
		return 0x1 << (id - 2816 + 20);
	}
	else
	{
		return 0x0;
	}
}


AliHLTInt32_t AliHLTMUONUtils::SpecToDDLNumber(AliHLTUInt32_t spec)
{
	///
	/// This method converts a 32 bit data block specification for a MUON-HLT
	/// data block into its corresponding DDL number in the range [0..21].
	/// It is assumed that the specification is for a data block comming from
	/// a single DDL source. If more than one DDL contributed to the data block
	/// then -1 is returned.
	/// @param spec  The 32 bit specification for a data block.
	/// @return  Returns the corresponding DDL number for the specification
	///          or -1 if the specification was invalid.
	///
	
	for (AliHLTInt32_t ddlNo = 0; ddlNo < 22; ddlNo++)
	{
		if (spec == AliHLTUInt32_t(0x1 << ddlNo))
			return ddlNo;
	}
	return -1;
}


AliHLTUInt32_t AliHLTMUONUtils::DDLNumberToSpec(AliHLTInt32_t ddlNo)
{
	///
	/// This method converts a DDL number in the range [0..21] into its
	/// corresponding 32 bit data block specification for the MUON-HLT.
	/// @param ddlNo  The equipment ID number of the DDL.
	/// @return  Returns the 32 bit data block specification or 0x0 if the
	///          DDL number was invalid (out of range).
	///
	
	if (0 <= ddlNo and ddlNo <= 21)
	{
		return 0x1 << ddlNo;
	}
	else
	{
		return 0x0;
	}
}


AliHLTMUONDataBlockType AliHLTMUONUtils::ParseCommandLineTypeString(const char* type)
{
	/// Parses the string containing the type name of a dHLT data block and
	/// returns the corresponding AliHLTMUONDataBlockType value.
	/// \param  type  The string containing the type name.
	/// \returns  The data block type or kUnknownDataBlock if the type name
	///      is invalid.

	if (strcmp(type, "trigrecs") == 0)
	{
		return kTriggerRecordsDataBlock;
	}
	else if (strcmp(type, "trigrecsdebug") == 0)
	{
		return kTrigRecsDebugDataBlock;
	}
	else if (strcmp(type, "trigchannels") == 0)
	{
		return kTriggerChannelsDataBlock;
	}
	else if (strcmp(type, "rechits") == 0)
	{
		return kRecHitsDataBlock;
	}
	else if (strcmp(type,"channels") == 0)
	{
		return kChannelsDataBlock;
	}
	else if (strcmp(type,"clusters") == 0)
	{
		return kClustersDataBlock;
	}
	else if (strcmp(type, "mansotracks") == 0)
	{
		return kMansoTracksDataBlock;
	}
	else if (strcmp(type, "mansocandidates") == 0)
	{
		return kMansoCandidatesDataBlock;
	}
	else if (strcmp(type, "singlesdecision") == 0)
	{
		return kSinglesDecisionDataBlock;
	}
	else if (strcmp(type, "pairsdecision") == 0)
	{
		return kPairsDecisionDataBlock;
	}
	
	return kUnknownDataBlock;
}


const char* AliHLTMUONUtils::FailureReasonToString(WhyNotValid reason)
{
	/// This method converts the WhyNotValid enumeration to a string representation.
	
	switch (reason)
	{
	case kNoReason: return "kNoReason";
	case kHeaderContainsWrongType: return "kHeaderContainsWrongType";
	case kHeaderContainsWrongRecordWidth: return "kHeaderContainsWrongRecordWidth";
	case kReservedBitsNotZero: return "kReservedBitsNotZero";
	case kParticleSignBitsNotValid: return "kParticleSignBitsNotValid";
	case kHitNotMarkedAsNil: return "kHitNotMarkedAsNil";
	case kFoundDuplicateIDs: return "kFoundDuplicateIDs";
	case kPtValueNotValid: return "kPtValueNotValid";
	case kFoundDuplicateTriggers: return "kFoundDuplicateTriggers";
	case kPairTrackIdsAreIdentical: return "kPairTrackIdsAreIdentical";
	case kMassValueNotValid: return "kMassValueNotValid";
	case kLowPtCountInvalid: return "kLowPtCountInvalid";
	case kHighPtCountInvalid: return "kHighPtCountInvalid";
	default: return "INVALID";
	}
}


const char* AliHLTMUONUtils::FailureReasonToMessage(WhyNotValid reason)
{
	/// This method returns a string containing a user readable message explaining
	/// the reason for failure described by the WhyNotValid enumeration.
	
	switch (reason)
	{
	case kNoReason:
		return "There was no problem with the data block.";
	case kHeaderContainsWrongType:
		return "The common data header contains an incorrect type identifier.";
	case kHeaderContainsWrongRecordWidth:
		return "The common data header contains an incorrect data record width.";
	case kReservedBitsNotZero:
		return "Reserved bits have not been set to zero.";
	case kParticleSignBitsNotValid:
		return "The particle sign bits are not a valid value.";
	case kHitNotMarkedAsNil:
		return "A hit was marked as not found, but the corresponding hit"
			" structure was not set to nil.";
	case kFoundDuplicateIDs:
		return "Found duplicate data record identifiers, but they should all be unique.";
	case kPtValueNotValid:
		return "The pT value is not positive, nor -1 indicating an invalid value.";
	case kFoundDuplicateTriggers:
		return "Found duplicate trigger decisions.";
	case kPairTrackIdsAreIdentical:
		return "The track identifiers of the track pair are identical.";
	case kMassValueNotValid:
		return "The invariant mass value is not positive, nor -1 indicating an invalid value.";
	case kLowPtCountInvalid:
		return "The low pT trigger count is greater than 2, which is invalid.";
	case kHighPtCountInvalid:
		return "The high pT trigger count is greater than 2, which is invalid.";
	default:
		return "UNKNOWN REASON CODE";
	}
}


bool AliHLTMUONUtils::HeaderOk(
		const AliHLTMUONTriggerRecordsBlockStruct& block,
		WhyNotValid* reason
	)
{
	/// Method used to check if the header information corresponds to the
	/// supposed type of the raw dHLT data block.
	/// [in]  \param block  The data block to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the header is not valid, if and
	///      only if a problem is found with the data.
	/// \returns  true if there is no problem with the header and false otherwise.
	 
	// The block must have the correct type.
	if (block.fHeader.fType != kTriggerRecordsDataBlock)
	{
		if (reason != NULL) *reason = kHeaderContainsWrongType;
		return false;
	}
	
	// The block's record width must be the correct size.
	if (block.fHeader.fRecordWidth != sizeof(AliHLTMUONTriggerRecordStruct))
	{
		if (reason != NULL) *reason = kHeaderContainsWrongRecordWidth;
		return false;
	}
	
	return true;
}


bool AliHLTMUONUtils::HeaderOk(
		const AliHLTMUONTrigRecsDebugBlockStruct& block,
		WhyNotValid* reason
	)
{
	/// Method used to check if the header information corresponds to the
	/// supposed type of the raw dHLT data block.
	/// [in]  \param block  The data block to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the header is not valid, if and
	///      only if a problem is found with the data.
	/// \returns  true if there is no problem with the header and false otherwise.
	
	// The block must have the correct type.
	if (block.fHeader.fType != kTrigRecsDebugDataBlock)
	{
		if (reason != NULL) *reason = kHeaderContainsWrongType;
		return false;
	}
	
	// The block's record width must be the correct size.
	if (block.fHeader.fRecordWidth != sizeof(AliHLTMUONTrigRecInfoStruct))
	{
		if (reason != NULL) *reason = kHeaderContainsWrongRecordWidth;
		return false;
	}
	
	return true;
}


bool AliHLTMUONUtils::HeaderOk(
		const AliHLTMUONTriggerChannelsBlockStruct& block,
		WhyNotValid* reason
	)
{
	/// Method used to check if the header information corresponds to the
	/// supposed type of the raw dHLT data block.
	/// [in]  \param block  The data block to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the header is not valid, if and
	///      only if a problem is found with the data.
	/// \returns  true if there is no problem with the header and false otherwise.
	
	// The block must have the correct type.
	if (block.fHeader.fType != kTriggerChannelsDataBlock)
	{
		if (reason != NULL) *reason = kHeaderContainsWrongType;
		return false;
	}
	
	// The block's record width must be the correct size.
	if (block.fHeader.fRecordWidth != sizeof(AliHLTMUONTriggerChannelStruct))
	{
		if (reason != NULL) *reason = kHeaderContainsWrongRecordWidth;
		return false;
	}
	
	return true;
}


bool AliHLTMUONUtils::HeaderOk(
		const AliHLTMUONRecHitsBlockStruct& block,
		WhyNotValid* reason
	)
{
	/// Method used to check if the header information corresponds to the
	/// supposed type of the raw dHLT data block.
	/// [in]  \param block  The data block to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the header is not valid, if and
	///      only if a problem is found with the data.
	/// \returns  true if there is no problem with the header and false otherwise.
	
	// The block must have the correct type.
	if (block.fHeader.fType != kRecHitsDataBlock)
	{
		if (reason != NULL) *reason = kHeaderContainsWrongType;
		return false;
	}
	
	// The block's record width must be the correct size.
	if (block.fHeader.fRecordWidth != sizeof(AliHLTMUONRecHitStruct))
	{
		if (reason != NULL) *reason = kHeaderContainsWrongRecordWidth;
		return false;
	}
	
	return true;
}


bool AliHLTMUONUtils::HeaderOk(
		const AliHLTMUONClustersBlockStruct& block,
		WhyNotValid* reason
	)
{
	/// Method used to check if the header information corresponds to the
	/// supposed type of the raw dHLT data block.
	/// [in]  \param block  The data block to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the header is not valid, if and
	///      only if a problem is found with the data.
	/// \returns  true if there is no problem with the header and false otherwise.
	
	// The block must have the correct type.
	if (block.fHeader.fType != kClustersDataBlock)
	{
		if (reason != NULL) *reason = kHeaderContainsWrongType;
		return false;
	}
	
	// The block's record width must be the correct size.
	if (block.fHeader.fRecordWidth != sizeof(AliHLTMUONClusterStruct))
	{
		if (reason != NULL) *reason = kHeaderContainsWrongRecordWidth;
		return false;
	}
	
	return true;
}


bool AliHLTMUONUtils::HeaderOk(
		const AliHLTMUONChannelsBlockStruct& block,
		WhyNotValid* reason
	)
{
	/// Method used to check if the header information corresponds to the
	/// supposed type of the raw dHLT data block.
	/// [in]  \param block  The data block to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the header is not valid, if and
	///      only if a problem is found with the data.
	/// \returns  true if there is no problem with the header and false otherwise.
	
	// The block must have the correct type.
	if (block.fHeader.fType != kChannelsDataBlock)
	{
		if (reason != NULL) *reason = kHeaderContainsWrongType;
		return false;
	}
	
	// The block's record width must be the correct size.
	if (block.fHeader.fRecordWidth != sizeof(AliHLTMUONChannelStruct))
	{
		if (reason != NULL) *reason = kHeaderContainsWrongRecordWidth;
		return false;
	}
	
	return true;
}


bool AliHLTMUONUtils::HeaderOk(
		const AliHLTMUONMansoTracksBlockStruct& block,
		WhyNotValid* reason
	)
{
	/// Method used to check if the header information corresponds to the
	/// supposed type of the raw dHLT data block.
	/// [in]  \param block  The data block to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the header is not valid, if and
	///      only if a problem is found with the data.
	/// \returns  true if there is no problem with the header and false otherwise.
	
	// The block must have the correct type.
	if (block.fHeader.fType != kMansoTracksDataBlock)
	{
		if (reason != NULL) *reason = kHeaderContainsWrongType;
		return false;
	}
	
	// The block's record width must be the correct size.
	if (block.fHeader.fRecordWidth != sizeof(AliHLTMUONMansoTrackStruct))
	{
		if (reason != NULL) *reason = kHeaderContainsWrongRecordWidth;
		return false;
	}
	
	return true;
}


bool AliHLTMUONUtils::HeaderOk(
		const AliHLTMUONMansoCandidatesBlockStruct& block,
		WhyNotValid* reason
	)
{
	/// Method used to check if the header information corresponds to the
	/// supposed type of the raw dHLT data block.
	/// [in]  \param block  The data block to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the header is not valid, if and
	///      only if a problem is found with the data.
	/// \returns  true if there is no problem with the header and false otherwise.
	
	// The block must have the correct type.
	if (block.fHeader.fType != kMansoCandidatesDataBlock)
	{
		if (reason != NULL) *reason = kHeaderContainsWrongType;
		return false;
	}
	
	// The block's record width must be the correct size.
	if (block.fHeader.fRecordWidth != sizeof(AliHLTMUONMansoCandidateStruct))
	{
		if (reason != NULL) *reason = kHeaderContainsWrongRecordWidth;
		return false;
	}
	
	return true;
}


bool AliHLTMUONUtils::HeaderOk(
		const AliHLTMUONSinglesDecisionBlockStruct& block,
		WhyNotValid* reason
	)
{
	/// Method used to check if the header information corresponds to the
	/// supposed type of the raw dHLT data block.
	/// [in]  \param block  The data block to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the header is not valid, if and
	///      only if a problem is found with the data.
	/// \returns  true if there is no problem with the header and false otherwise.
	
	// The block must have the correct type.
	if (block.fHeader.fType != kSinglesDecisionDataBlock)
	{
		if (reason != NULL) *reason = kHeaderContainsWrongType;
		return false;
	}
	
	// The block's record width must be the correct size.
	if (block.fHeader.fRecordWidth != sizeof(AliHLTMUONTrackDecisionStruct))
	{
		if (reason != NULL) *reason = kHeaderContainsWrongRecordWidth;
		return false;
	}
	
	return true;
}


bool AliHLTMUONUtils::HeaderOk(
		const AliHLTMUONPairsDecisionBlockStruct& block,
		WhyNotValid* reason
	)
{
	/// Method used to check if the header information corresponds to the
	/// supposed type of the raw dHLT data block.
	/// [in]  \param block  The data block to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the header is not valid, if and
	///      only if a problem is found with the data.
	/// \returns  true if there is no problem with the header and false otherwise.
	
	// The block must have the correct type.
	if (block.fHeader.fType != kPairsDecisionDataBlock)
	{
		if (reason != NULL) *reason = kHeaderContainsWrongType;
		return false;
	}
	
	// The block's record width must be the correct size.
	if (block.fHeader.fRecordWidth != sizeof(AliHLTMUONPairDecisionStruct))
	{
		if (reason != NULL) *reason = kHeaderContainsWrongRecordWidth;
		return false;
	}
	
	return true;
}


bool AliHLTMUONUtils::IntegrityOk(
		const AliHLTMUONTriggerRecordStruct& tr,
		WhyNotValid* reason
	)
{
	/// This method is used to check more extensively if the integrity of the
	/// trigger record structure is OK and returns true in that case.
	/// [in] \param tr  The trigger record structure to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the structure is not valid, if and
	///      only if a problem is found with the data.
	/// \returns  true if there is no problem with the structure and false otherwise.
	
	// Make sure that the reserved bits in the fFlags field are set
	// to zero.
	if ((tr.fFlags & 0x3FFFFFF0) != 0)
	{
		if (reason != NULL) *reason = kReservedBitsNotZero;
		return false;
	}

	// Make sure the sign is not invalid.
	if ((tr.fFlags & 0xC0000000) == 0xC0000000)
	{
		if (reason != NULL) *reason = kParticleSignBitsNotValid;
		return false;
	}

	// Check that fHit[i] is nil if the corresponding bit in the
	// flags word is zero.
	const AliHLTMUONRecHitStruct& nilhit
		= AliHLTMUONConstants::NilRecHitStruct();
	if ( ((tr.fFlags & 0x1) == 0 and tr.fHit[0] != nilhit) or
	     ((tr.fFlags & 0x2) == 0 and tr.fHit[1] != nilhit) or
	     ((tr.fFlags & 0x4) == 0 and tr.fHit[2] != nilhit) or
	     ((tr.fFlags & 0x8) == 0 and tr.fHit[3] != nilhit)
	   )
	{
		if (reason != NULL) *reason = kHitNotMarkedAsNil;
		return false;
	}

	return true;
}


bool AliHLTMUONUtils::IntegrityOk(
		const AliHLTMUONTriggerRecordsBlockStruct& block,
		WhyNotValid* reason,
		AliHLTUInt32_t* recordNum
	)
{
	/// This method is used to check more extensively if the integrity of the
	/// dHLT raw internal data block is OK and returns true in that case.
	/// [in] \param block  The trigger record data block to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the data block is not valid, if and
	///      only if a problem is found with the data.
	/// [out] \param recordNum  If this is not NULL, then it will be filled with
	///      the number of the trigger record that had a problem. This value will
	///      only contain a valid value if 'reason' contains one of:
	///        - kReservedBitsNotZero
	///        - kParticleSignBitsNotValid
	///        - kHitNotMarkedAsNil
	/// \returns  true if there is no problem with the data and false otherwise.
	
	if (not HeaderOk(block, reason)) return false;
	
	const AliHLTMUONTriggerRecordStruct* triggerRecord =
		reinterpret_cast<const AliHLTMUONTriggerRecordStruct*>(&block + 1);

	// Check if any ID is duplicated.
	for (AliHLTUInt32_t i = 0; i < block.fHeader.fNrecords; i++)
	{
		AliHLTInt32_t id = triggerRecord[i].fId;
		for (AliHLTUInt32_t j = i+1; i < block.fHeader.fNrecords; j++)
		{
			if (id == triggerRecord[j].fId)
			{
				if (reason != NULL) *reason = kFoundDuplicateIDs;
				return false;
			}
		}
	}

	// Check integrity of individual trigger records.
	for (AliHLTUInt32_t i = 0; i < block.fHeader.fNrecords; i++)
	{
		if (not IntegrityOk(triggerRecord[i], reason))
		{
			if (recordNum != NULL) *recordNum = i;
			return false;
		}
	}

	return true;
}


bool AliHLTMUONUtils::IntegrityOk(
		const AliHLTMUONTrigRecsDebugBlockStruct& block,
		WhyNotValid* reason
	)
{
	/// This method is used to check more extensively if the integrity of the
	/// dHLT raw internal data block is OK and returns true in that case.
	/// [in] \param block  The trigger record debugging information data block to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the data block is not valid, if and
	///      only if a problem is found with the data.
	/// \returns  true if there is no problem with the data and false otherwise.
	
	if (not HeaderOk(block, reason)) return false;
	return true;
}


bool AliHLTMUONUtils::IntegrityOk(
		const AliHLTMUONTriggerChannelsBlockStruct& block,
		WhyNotValid* reason
	)
{
	/// This method is used to check more extensively if the integrity of the
	/// dHLT raw internal data block is OK and returns true in that case.
	/// [in] \param block  The trigger channels data block to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the data block is not valid, if and
	///      only if a problem is found with the data.
	/// \returns  true if there is no problem with the data and false otherwise.
	
	if (not HeaderOk(block, reason)) return false;
	return true;
}


bool AliHLTMUONUtils::IntegrityOk(
		const AliHLTMUONRecHitsBlockStruct& block,
		WhyNotValid* reason
	)
{
	/// This method is used to check more extensively if the integrity of the
	/// dHLT raw internal data block is OK and returns true in that case.
	/// [in] \param block  The reconstructed hits data block to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the data block is not valid, if and
	///      only if a problem is found with the data.
	/// \returns  true if there is no problem with the data and false otherwise.
	
	if (not HeaderOk(block, reason)) return false;
	return true;
}


bool AliHLTMUONUtils::IntegrityOk(
		const AliHLTMUONClustersBlockStruct& block,
		WhyNotValid* reason
	)
{
	/// This method is used to check more extensively if the integrity of the
	/// dHLT raw internal data block is OK and returns true in that case.
	/// [in] \param block  The clusters data block to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the data block is not valid, if and
	///      only if a problem is found with the data.
	/// \returns  true if there is no problem with the data and false otherwise.
	
	if (not HeaderOk(block, reason)) return false;

	const AliHLTMUONClusterStruct* cluster =
		reinterpret_cast<const AliHLTMUONClusterStruct*>(&block + 1);
	
	// Check if any ID is duplicated.
	for (AliHLTUInt32_t i = 0; i < block.fHeader.fNrecords; i++)
	{
		AliHLTInt32_t id = cluster[i].fId;
		for (AliHLTUInt32_t j = i+1; i < block.fHeader.fNrecords; j++)
		{
			if (id == cluster[j].fId)
			{
				if (reason != NULL) *reason = kFoundDuplicateIDs;
				return false;
			}
		}
	}
	
	return true;
}


bool AliHLTMUONUtils::IntegrityOk(
		const AliHLTMUONChannelsBlockStruct& block,
		WhyNotValid* reason
	)
{
	/// This method is used to check more extensively if the integrity of the
	/// dHLT raw internal data block is OK and returns true in that case.
	/// [in] \param block  The ADC channels data block to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the data block is not valid, if and
	///      only if a problem is found with the data.
	/// \returns  true if there is no problem with the data and false otherwise.
	
	if (not HeaderOk(block, reason)) return false;
	return true;
}


bool AliHLTMUONUtils::IntegrityOk(
		const AliHLTMUONMansoTrackStruct& track,
		WhyNotValid* reason
	)
{
	/// This method is used to check more extensively if the integrity of the
	/// Manso track structure is OK and returns true in that case.
	/// [in] \param track  The track structure to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the structure is not valid, if and
	///      only if a problem is found with the data.
	/// \returns  true if there is no problem with the structure and false otherwise.
	
	// Make sure that the reserved bits in the fFlags field are set
	// to zero.
	if ((track.fFlags & 0x3FFFFFF0) != 0)
	{
		if (reason != NULL) *reason = kReservedBitsNotZero;
		return false;
	}

	// Make sure the sign is not invalid.
	if ((track.fFlags & 0xC0000000) == 0xC0000000)
	{
		if (reason != NULL) *reason = kParticleSignBitsNotValid;
		return false;
	}

	// Check that fHit[i] is nil if the corresponding bit in the
	// flags word is zero.
	const AliHLTMUONRecHitStruct& nilhit
		= AliHLTMUONConstants::NilRecHitStruct();
	if ( ((track.fFlags & 0x1) == 0 and track.fHit[0] != nilhit) or
	     ((track.fFlags & 0x2) == 0 and track.fHit[1] != nilhit) or
	     ((track.fFlags & 0x4) == 0 and track.fHit[2] != nilhit) or
	     ((track.fFlags & 0x8) == 0 and track.fHit[3] != nilhit)
	   )
	{
		if (reason != NULL) *reason = kHitNotMarkedAsNil;
		return false;
	}
	
	return true;
}


bool AliHLTMUONUtils::IntegrityOk(
		const AliHLTMUONMansoTracksBlockStruct& block,
		WhyNotValid* reason,
		AliHLTUInt32_t* recordNum
	)
{
	/// This method is used to check more extensively if the integrity of the
	/// dHLT raw internal data block is OK and returns true in that case.
	/// [in] \param block  The Manso track data block to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the data block is not valid, if and
	///      only if a problem is found with the data.
	/// [out] \param recordNum  If this is not NULL, then it will be filled with
	///      the number of the track that had a problem. This value will only
	///      contain a valid value if 'reason' contains one of:
	///        - kReservedBitsNotZero
	///        - kParticleSignBitsNotValid
	///        - kHitNotMarkedAsNil
	/// \returns  true if there is no problem with the data and false otherwise.
	
	if (not HeaderOk(block, reason)) return false;

	const AliHLTMUONMansoTrackStruct* track =
		reinterpret_cast<const AliHLTMUONMansoTrackStruct*>(&block + 1);
	
	// Check if any track ID is duplicated.
	for (AliHLTUInt32_t i = 0; i < block.fHeader.fNrecords; i++)
	{
		AliHLTInt32_t id = track[i].fId;
		for (AliHLTUInt32_t j = i+1; i < block.fHeader.fNrecords; j++)
		{
			if (id == track[j].fId)
			{
				if (reason != NULL) *reason = kFoundDuplicateIDs;
				return false;
			}
		}
	}

	// Check that the tracks have integrity.
	for (AliHLTUInt32_t i = 0; i < block.fHeader.fNrecords; i++)
	{
		if (not IntegrityOk(track[i], reason))
		{
			if (recordNum != NULL) *recordNum = i;
			return false;
		}
	}

	return true;
}


bool AliHLTMUONUtils::IntegrityOk(
		const AliHLTMUONMansoCandidatesBlockStruct& block,
		WhyNotValid* reason,
		AliHLTUInt32_t* recordNum
	)
{
	/// This method is used to check more extensively if the integrity of the
	/// dHLT raw internal data block is OK and returns true in that case.
	/// [in] \param block  The Manso track candidate data block to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the data block is not valid, if and
	///      only if a problem is found with the data.
	/// [out] \param recordNum  If this is not NULL, then it will be filled with
	///      the number of the track candidate that had a problem. This value will
	///      only contain a valid value if 'reason' contains one of:
	///        - kReservedBitsNotZero
	///        - kParticleSignBitsNotValid
	///        - kHitNotMarkedAsNil
	/// \returns  true if there is no problem with the data and false otherwise.
	
	if (not HeaderOk(block, reason)) return false;

	const AliHLTMUONMansoCandidateStruct* candidate =
		reinterpret_cast<const AliHLTMUONMansoCandidateStruct*>(&block + 1);
	
	// Check if any candidate track ID is duplicated.
	for (AliHLTUInt32_t i = 0; i < block.fHeader.fNrecords; i++)
	{
		AliHLTInt32_t id = candidate[i].fTrack.fId;
		for (AliHLTUInt32_t j = i+1; i < block.fHeader.fNrecords; j++)
		{
			if (id == candidate[j].fTrack.fId)
			{
				if (reason != NULL) *reason = kFoundDuplicateIDs;
				return false;
			}
		}
	}
	
	// Check that the tracks have integrity.
	for (AliHLTUInt32_t i = 0; i < block.fHeader.fNrecords; i++)
	{
		if (not IntegrityOk(candidate[i].fTrack, reason))
		{
			if (recordNum != NULL) *recordNum = i;
			return false;
		}
	}
	
	return true;
}


bool AliHLTMUONUtils::IntegrityOk(
		const AliHLTMUONTrackDecisionStruct& decision,
		WhyNotValid* reason
	)
{
	/// This method is used to check more extensively if the integrity of the
	/// single track trigger decision structure is OK and returns true in that case.
	/// [in] \param decision  The trigger decision structure to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the structure is not valid, if and
	///      only if a problem is found with the data.
	/// \returns  true if there is no problem with the structure and false otherwise.
	
	// Make sure that the reserved bits in the fTriggerBits field are set
	// to zero.
	if ((decision.fTriggerBits & 0xFFFFFFFC) != 0)
	{
		if (reason != NULL) *reason = kReservedBitsNotZero;
		return false;
	}
	
	// The pT should be -1 or a positive number.
	if (decision.fPt != -1. and decision.fPt < 0.)
	{
		if (reason != NULL) *reason = kPtValueNotValid;
		return false;
	}
	
	return true;
}


bool AliHLTMUONUtils::IntegrityOk(
		const AliHLTMUONSinglesDecisionBlockStruct& block,
		WhyNotValid* reason,
		AliHLTUInt32_t* recordNum
	)
{
	/// This method is used to check more extensively if the integrity of the
	/// dHLT raw internal data block is OK and returns true in that case.
	/// [in] \param block  The single track trigger decision data block to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the data block is not valid, if and
	///      only if a problem is found with the data.
	/// [out] \param recordNum  If this is not NULL, then it will be filled with
	///      the number of the trigger decisions that had a problem. This value will
	///      only contain a valid value if 'reason' contains one of:
	///        - kReservedBitsNotZero
	///        - kPtValueNotValid
	/// \returns  true if there is no problem with the data and false otherwise.
	
	if (not HeaderOk(block, reason)) return false;
	
	const AliHLTMUONTrackDecisionStruct* decision =
		reinterpret_cast<const AliHLTMUONTrackDecisionStruct*>(&block + 1);

	// Check that there are no duplicate trigger entries.
	for (AliHLTUInt32_t i = 0; i < block.fHeader.fNrecords; i++)
	{
		AliHLTInt32_t id = decision[i].fTrackId;
		for (AliHLTUInt32_t j = i+1; i < block.fHeader.fNrecords; j++)
		{
			if (id == decision[j].fTrackId)
			{
				if (reason != NULL) *reason = kFoundDuplicateTriggers;
				return false;
			}
		}
	}
	
	// Check that the trigger bits for each track have integrity.
	for (AliHLTUInt32_t i = 0; i < block.fHeader.fNrecords; i++)
	{
		if (not IntegrityOk(decision[i], reason))
		{
			if (recordNum != NULL) *recordNum = i;
			return false;
		}
	}
	
	return true;
}


bool AliHLTMUONUtils::IntegrityOk(
		const AliHLTMUONPairDecisionStruct& decision,
		WhyNotValid* reason
	)
{
	/// This method is used to check more extensively if the integrity of the
	/// track pair trigger decision structure is OK and returns true in that case.
	/// [in] \param decision  The trigger decision structure to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the structure is not valid, if and
	///      only if a problem is found with the data.
	/// \returns  true if there is no problem with the structure and false otherwise.
	
	// Make sure that the reserved bits in the fTriggerBits field are set
	// to zero.
	if ((decision.fTriggerBits & 0xFFFFFF80) != 0)
	{
		if (reason != NULL) *reason = kReservedBitsNotZero;
		return false;
	}
	
	// Check that the track IDs are not the same.
	if (decision.fTrackAId == decision.fTrackBId)
	{
		if (reason != NULL) *reason = kPairTrackIdsAreIdentical;
		return false;
	}
	
	// The invariant mass should be -1 or a positive number.
	if (decision.fInvMass != -1. and decision.fInvMass < 0.)
	{
		if (reason != NULL) *reason = kMassValueNotValid;
		return false;
	}
	
	// Neither the high pt (hipt) or low pt (lopt) count bits can be > 2.
	AliHLTUInt8_t lowPtCount = (decision.fTriggerBits & 0x00000003);
	AliHLTUInt8_t highPtCount = (decision.fTriggerBits & 0x0000000C) >> 2;
	if (lowPtCount > 2)
	{
		if (reason != NULL) *reason = kLowPtCountInvalid;
		return false;
	}
	if (highPtCount > 2)
	{
		if (reason != NULL) *reason = kHighPtCountInvalid;
		return false;
	}
	
	return true;
}


bool AliHLTMUONUtils::IntegrityOk(
		const AliHLTMUONPairsDecisionBlockStruct& block,
		WhyNotValid* reason,
		AliHLTUInt32_t* recordNum
	)
{
	/// This method is used to check more extensively if the integrity of the
	/// dHLT raw internal data block is OK and returns true in that case.
	/// [in] \param block  The track pair trigger decision data block to check.
	/// [out] \param reason  If this is not NULL, then it will be filled with
	///      the reason code describing why the data block is not valid, if and
	///      only if a problem is found with the data.
	/// [out] \param recordNum  If this is not NULL, then it will be filled with
	///      the number of the trigger decisions that had a problem. This value will
	///      only contain a valid value if 'reason' contains one of:
	///        - kReservedBitsNotZero
	///        - kPairTrackIdsAreIdentical
	///        - kMassValueNotValid
	///        - kLowPtCountInvalid
	///        - kHighPtCountInvalid
	/// \returns  true if there is no problem with the data and false otherwise.
	
	if (not HeaderOk(block, reason)) return false;

	const AliHLTMUONPairDecisionStruct* decision =
		reinterpret_cast<const AliHLTMUONPairDecisionStruct*>(&block + 1);
	
	// Check that there are no duplicate trigger entries.
	for (AliHLTUInt32_t i = 0; i < block.fHeader.fNrecords; i++)
	{
		AliHLTInt32_t ta = decision[i].fTrackAId;
		AliHLTInt32_t tb = decision[i].fTrackBId;
		for (AliHLTUInt32_t j = i+1; i < block.fHeader.fNrecords; j++)
		{
			if (ta == decision[j].fTrackAId and tb == decision[j].fTrackBId)
			{
				if (reason != NULL) *reason = kFoundDuplicateTriggers;
				return false;
			}
		}
	}
	
	// Check that the trigger bits for each track pair have integrity.
	for (AliHLTUInt32_t i = 0; i < block.fHeader.fNrecords; i++)
	{
		if (not IntegrityOk(decision[i], reason))
		{
			if (recordNum != NULL) *recordNum = i;
			return false;
		}
	}
	
	return true;
}