BLNTuple.hh

Go to the documentation of this file.

//      BLNTuple.hh
/*
This source file is part of G4beamline, http://g4beamline.muonsinc.com
Copyright (C) 2003,2004,2005,2006 by Tom Roberts, all rights reserved.

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.

http://www.gnu.org/copyleft/gpl.html
*/

#ifndef BLNTUPLE_HH
#define BLNTUPLE_HH

#include <map>
#include <vector>
#include <set>
#include "globals.hh"
#include "G4ThreeVector.hh"

class BLNTupleHandler; // forward declarations
class BLNTupleCallback;

/**     class BLNTuple is an interface class to an NTuple, independent of
 *      implementation (HistoScope, BLTrackFile, Root, ...).
 *
 *      Each type of NTuple will derive a class from this one, and implement
 *      the virtual functions.
 **/
class BLNTuple {
protected:
        G4String name;
        G4String fields;
        int nData;
        std::vector<BLNTupleCallback*> callback;
        /// Constructor.
        BLNTuple(G4String _name, G4String _fields) :
                name(_name), fields(_fields), callback() { nData = 0; }
        static bool enableOutput;
        static std::map<G4String,BLNTupleHandler*> *handler;
        static std::vector<BLNTuple *> list;
        static std::set<G4String> nameSet;
        static G4String defaultType;
        static BLNTupleHandler *forceHandler;
        friend class BLNTupleHandler;
public:
        /// Destructor.
        virtual ~BLNTuple() { callback.clear(); }

        /// create() will create a new NTuple for writing.
        /// type must be a known type of NTuple implementation ("" => default).
        /// "category/name" is the name of the NTuple (the "/" may be omitted 
        /// if category is null, depending on type).
        /// fields is a : separated list of the field names.
        /// filename is a hint, and is not used by all types.
        static BLNTuple *create(G4String type, G4String category, G4String name,
                                        G4String fields, G4String filename);

        /// read() will open an NTuple for reading.
        /// type must be a known type of NTuple implementation ("" is default).
        /// "category/name" is the name of the NTuple (the "/" may be omitted 
        /// if category is null, depending on type).
        /// fields is a : separated list of the field names (not used by all
        /// types, in which case it is up to the user to make sure the file
        /// fields match the required ones).
        /// filename is a hint, and is not used by all types.
        /// The NTuple should be explicitly closed by calling its close().
        static BLNTuple *read(G4String type, G4String category, G4String name,
                                        G4String fields, G4String filename);

        /// appendRow() adds a row to an NTuple created for writing.
        /// NOTE: data[] must contain n doubles, and n must be the same
        /// as the number of fields in the NTuple.
        virtual void appendRow(double data[], int n) = 0;

        /// readRow() reads a row from an NTuple open for reading.
        /// returns true if valid row, false if EOF or error.
        /// ndata must be equal to the value of getNData(), and data[]
        /// must be at least that long.
        virtual bool readRow(double data[], int ndata) = 0;

        /// getName() returns the name of the NTuple (not including category)
        G4String getName() const { return name; }

        /// getFields() returns a colon-separated list of the fields.
        G4String getFields() const { return fields; }

        /// getNData() returns the # data items required.
        int getNData() const { return nData; }

        /// doCallbacks() will call all registered callbacks
        void doCallbacks(double data[], int ndata);

        /// annotate() will add an annotation line to any ASCII format.
        /// Normally line should begin with a "#", and have no "\r" or "\n".
        /// line == "" will output an empty line to ASCII files.
        /// Ignored for NTuples that don't support annotations.
        virtual void annotate(G4String line) { }

        /// needsReference() returns true if this NTuple needs the Reference
        /// particle.
        virtual bool needsReference() { return false; }

        /// flush() will flush the NTuple to disk, if supported.
        virtual void flush() = 0;

        /// close() will close the NTuple.
        virtual void close() = 0;

        /// do Summary() will print a 1-line summary to stdout, if supported.
        virtual void doSummary() = 0;

        /// registerCallback() registers a callback with this BLNTuple.
        void registerCallback(BLNTupleCallback *cb) { callback.push_back(cb); }

        /// getList() returns the list of all BLNTuples.
        static std::vector<BLNTuple*> getList() { return list; }

        /// isUniqueName() returns true if the name is unique. Also enters
        /// the name into the nameSet.
        static bool isUniqueName(G4String name);

        /// disableOutputFiles() prevents any output files from being written.
        static void disableOutputFiles() { enableOutput = false; }

        /// getEnableOutput() returns enableOutput;
        static bool getEnableOutput() { return enableOutput; }

        /// registerHandler() registers a BLNTupleHandler. This defines
        /// a new type of NTuple that can be created. Can be called in
        /// static initializers without worrying about ordering.
        static void registerHandler(G4String typeName, BLNTupleHandler *h);

        /// getHandler() returns the BLNTupleHandler for a given type.
        /// returns 0 for unknown type.
        static BLNTupleHandler *getHandler(G4String type);

        /// flushAll() writes all NTuples to file(s). This is a "checkpoint
        /// dump".
        /// Loops over all NTuples in the order they were created.
        /// Ignores NTuples open for reading.
        static void flushAll();

        /// closeAll() writes all NTuples to file(s) and closes them.
        /// Loops over all NTuples in the order they were created.
        /// Ignores NTuples open for reading.
        static void closeAll();

        /// summary() will summarize the NTuples to stdout
        /// Loops over all NTuples in the order they were created.
        /// Ignores NTuples open for reading.
        static void summary();

        /// update() will update real-time histogram interface(s)
        static void update();

        /// setDefaultType() sets the default type for NTuples
        static void setDefaultType(G4String name) { defaultType = name; }

        /// getFormatList() returns a list of known formats.
        static G4String getFormatList();
        
        /// getForceHandler() will return the forced handler (NULL if none).
        static BLNTupleHandler *getForceHandler() { return forceHandler; }
        
        /// setForceHandler() will force the specified handler to be used,
        /// regardless of type. Used to force an MPI handler when in MPI mode.
        static void setForceHandler(BLNTupleHandler *f) { forceHandler = f; }
};

/** class BLNTupleHandler defines a handler for a single type of NTuple.
 *  To be useful it must be registered with BLNTuple::registerHandler()
 *  -- this is normally done in the class default constructor, and a
 *  static object is defined.
 **/
class BLNTupleHandler {
protected:
        std::map<G4String,BLNTupleHandler*> *handler()
                { return BLNTuple::handler; }
public:
        virtual BLNTuple *create(G4String type, G4String category, 
                        G4String name, G4String fields, G4String filename) = 0;
        virtual BLNTuple *read(G4String type, G4String category, G4String name,
                                G4String fields, G4String filename) = 0;
};

/** class BLNTupleCallback defines a callback for BLNTuple::appendRow().
 **/
class BLNTupleCallback {
public:
        /// callback() is called by BLNTuple::appendRow() for every registered
        /// callback. The first argument is always this, identifying the
        /// BLNTuple that is doing the calling.
        virtual void ntupleCallback(BLNTuple *ntuple, double data[], int ndata)
                                                                        = 0;
};

#endif // BLNTUPLE_HH