//	BLCollectiveComputation.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 BLCOLLECTIVECOMPUTATION_H
#define BLCOLLECTIVECOMPUTATION_H

#include "G4Event.hh"
#include "G4Track.hh"

/**	struct BLTrackData -- data related to a track (for collective tracking)
 **/
struct BLTrackData {
	G4Event *event;
	G4Track *track;
public:
	/// Constructor.
	BLTrackData(G4Event *e, G4Track *t) { event = e;  track=t; }

	/// destructor. DOES NOT DELETE ANY OTHER OBJECTS.
	~BLTrackData() { }
};

/**	class BLCollectiveComputation -- base class for a collective computation
 *
 *	Normally a command class that implements a collective computation 
 *	will be derived from this class as well as BLCommand.
 *	Its command() function should register itself with
 *	    BLRunManager::getObject()->registerCollectiveComputation(this);
 *	and then call
 *	    BLRunManager::getObject()->setCollectiveMode(true);
 *
 *	If steps in time are also desired, it should call
 *	    BLRunManager::getObject()->setDeltaT(0.1*ns);
 *	(with desired delta-T). Note that steps in time are not exact, so
 *	the computation should probably check that the variation in time
 *	among the tracks is small enough (in practive, 1 ps accuracy is
 *	normal).
 *
 *	Note that setDeltaT() can be called at any time, and will affect the
 *	next step. It is probably desirable to adjust deltaT depending on the
 *	importance of the collective computation (when the bunch is diffuse,
 *	bigger deltaT won't affect the accuracy but will reduce the CPU time).
 *	Caveat: if steps in time are to be used, setDeltaT() must be called
 *	before tracking begins, and should never be <= 0.0 (values <= 0.0
 *	means each track takes individual steps in space, which is probably
 *	not useful).
 *
 *	Note that runmanager->rejectCollectiveStep() can be called during
 *	tracking or in collectiveStep() to reject the current step and 
 *	re-process it. This only makes sense if setDeltaT() has been
 *	called with a smaller value of deltaT. Attempts to reject the very
 *	first step are silently ignored (that step is used to process all
 *	tracks to the same time).
 *
 *	The basic sequence of collective tracking, including callbacks from
 *	BLRunManger to each registered collective computation is:
 *
 *	(generate beam tracks from beam commands, filling trackVector)
 *	stepTime = (largest time from beam tracks)
 *	beginCollectiveTracking()
 *	first=true
 *	loop over steps {
 *		rejected=false
 *		nActive=0
 *		loop over tracks in trackVector {
 *			if(rejected && !first) break;
 *			beginTrack()
 *			(discard remaining secondaries, if any)
 *			process track to stepTime or killed
 *			if(track is active) ++nActive
 *			if(keepSecondaries)
 *				append secondaries to trackVector
 *			else
 *				discard secondaries
 *		}
 *		if(!rejected || first) collectiveStep()
 *		if(rejected && !first) {
 *			restore saved tracks and stepTime
 *		} else {
 *			save tracks and stepTime
 *			stepTime += deltaT
 *		}
 *		first=false
 *	} while(nActive > 0)
 *	endCollectiveTracking()
 *
 *	Note: if multiple BLCollectiveComputation instances are registered
 *	with BLRUnManager, the callbacks to them will occur in the order
 *	in which they were registered (normally the order in which their
 *	commands appear in the input file).
 *
 **/
class BLCollectiveComputation {
public:
	BLCollectiveComputation() { };
	virtual ~BLCollectiveComputation() { }

	/// beginCollectiveTracking() is called after the track vector is 
	/// constructed but before trackng begins.
	/// Can be used to allocate internal arrays or create NTuple-s.
	/// Note that additional tracks can be added to v as tracking proceeds;
	/// no tracks are ever removed (but they will change status).
	/// The vector v will not change during the run.
	virtual void beginCollectiveTracking(std::vector<BLTrackData>& v) { }

	/// beginTrack() is called just before the track v[index] is
	/// tracked for the next step. Note that the user class can be
	/// derived from G4UserTrackingAction and registered to be called
	/// at the start and end of tracking for each track. The difference
	/// is this routine relates the track to the entry in v[], and
	/// also: BLRunManager::processOneTrack() can be called here, but
	/// not in PreUserTrackingAction().
	virtual void beginTrack(std::vector<BLTrackData>& v, int index) { }

	/// collectiveStep() is called after each collective step
	/// to perform the computation.
	/// It can store data for later use, and can modify the tracks.
	/// Note that collectiveStep() is not called until after the
	/// first step is taken, so you might want to call your
	/// collectiveStep() function at the end of beginCollectiveTracking()
	/// to store the state of tracks at the earliest time.
	/// Note: collectiveStep() can call runmanager->rejectCollectiveStep(),
	/// in which case the tracking since the previous return from
	/// collectiveStep() will be discarded and re-done; for this to make
	/// sense, runmanager->setDeltaT() should also be called with a
	/// smaller value -- this is one way to adapt deltaT dynamically.
	virtual void collectiveStep(std::vector<BLTrackData>& v) = 0;

	/// endCollectiveTracking() is called after tracking is complete.
	/// Can be used to delete internal arrays and print a summary.
	virtual void endCollectiveTracking(std::vector<BLTrackData>& v) { }
};

#endif // BLCOLLECTIVECOMPUTATION_H