/** @mainpage g4beamline g4beamline is a program to run geant4 simulations of beamlines. It is designed to be easy to use, extremely flexible, and easily extensible.

Extending the g4beamline program

Additional elements and commands can easily be added to the g4beamline program by simply deriving additional classes from BLElement or BLCommand. The source has lots of examples of each. The basic idea is that for each command or element the .cc file defines a global default instance, and the default constructor registers the command with BLCommand so it can be used in the input file. Virtual functions from BLCommand define the parameters of the command (see BLCommand for details). New elements can be placed (via the "place" command) as usual. Because of the rich set of callbacks (see below), a new command can do just about anything that is possible in the program. Commands generally create a new instance of the class, and register it for the appropriate callbacks to implement the functionality required. This can include Geant4 callbacks and functions such as registering new particles and physics processes. Most new features in G4beamline are implemented as new commands. Occasionally a new feature will require modifications to the infrastructure classes, or even new infrastructure classes, but that is rather rare. Multiple new commands can be developed and tested in parallel by different people in their private source trees; once one is ready, its file is placed into the official source tree and it is automatically included in the next official build. This can be done aggressively, because if the new command is not used in the input file, its code will not be executed (except for registering its command). So even if the new command has buggy code, it won't affect users that don't use it.

Implementation Notes

The commands for an input file are all implemented as individual classes in individual .cc files, derived from BLCommand. The class BLCommand handles reading the input file, parsing commands, parsing command arguments (both positional and named), and implementing first-character commands (/, *, #, and !). Derived commands simply declare their arguments (via calls to argString(), argInt(), and argDouble()), and handleNamedArgs() manages putting the values from the command line into the class variables. Conventionally, the class name, filename, and command name are interrelated: 
	command name:	example
	class name:	BLCMDexample
	file name:	BLCMDexample.cc
Commands do not require a .hh file, as the class is used only in the command's single .cc file. Classes used in more than one command should be implemented as infrastructure classes. All .cc files in the source/src directory are included in the build, so their global static constructors will be executed before main() is entered. As those constructors register the default instance of each command with BLCommand, no list of commands is required -- simply placing the source file into that directory is sufficient. Beamline elements are also implemented as individual classes in individual .cc files, derived from BLElement (which is derived from BLCommand, so every element includes a command to create an instance of the element). The place command places instances of a given element into the current group. The class BLManager interfaces to BLRunManager, and implements all of the user customization classes (G4UserSteppingAction, G4UserDetectorConstruction, etc.). Element classes can register with BLManager to have a UserSteppingAction() function called for every reference-particle or beam step referring to a specific G4VPhysicalVolume. For a simple example of this see BLCMDvirtualdetector.cc.

Callback Summary

The BLManager provides callback services to command and element classes; the latter register with the former, specifying when to be called back. Some of these are extensions of Geant4 callbacks, some are new in G4beamline. Note the Geant4 callbacks occur in every state, so the code should check the BLManager state. For a simulation run (i.e. viewer=none), the order of callbacks is:
CallbackDescription
Reading Input FileCommands execute, elements construct their objects. For any command class, reading its command generates a call to command(), while for elements the place command generates a call to construct(). Most element commands create a new class instance in command() which holds the values of its arguments; the heavy work is performed in construct(), such as creating solids, logical and physical volumes, and placing them into the Geant4 world.
callback(0)Callback pre-Tune particle.
-Tune particle is tracked, including BeginOfRunAction, BeginOfEventAction, PreUserTrackingAction (multiple times), UserSteppingAction (multiple times), ZSteppingAction (multiple times), StackingAction (multiple times), PostUserTrackingAction, EndOfEventAction, EndOfRunAction.
-Reference particle is tracked, including BeginOfRunAction, BeginOfEventAction, PreUserTrackingAction, UserSteppingAction (multiple times), ZSteppingAction (multiple times), StackingAction, PostUserTrackingAction, EndOfEventAction, EndOfRunAction.
callback(1)Callback post-Reference particle.
BeginOfRunActionStart of a run tracking beam.
BeginOfEventActionJust before each event is processed.
PreUserTrackingActionJust before each track is tracked.
UserSteppingActionDuring tracking, each 'physics' step. This is the most common callback, and can be conditioned on the step being in a specific physical volume, and on the state (Tune, Reference, Beam).
ZSteppingActionDuring tracking, each 'physics' step at a specific Z value (centerline coordinates).
StackingActionDuring tracking, when placing secondary track onto stack.
PostUserTrackingActionJust after each track is tracked.
EndOfEventActionJust after each event is processed.
EndOfRunActionEnd of a run tracking beam.
callback(2)Callback post-beam tracking.
Note that the Tune particle consists of a run with one event containing one or more tracks (depends on how often the Tune particle must be re-tracked during tuning). The Reference particle consists of a run with one event containing one track. So the corresponding Geant4 callbacks happen for these two runs as well as for the run containing all of the beam tracks. For visualization, callback(4) is called after callback(1) and after the selected viewer is set up. For each image, a run is simulated with visualization of its tracks enabled. For special situations, such as collective tracking, callback(3) is called just after callback(1), and the program exits after all registered callback(3)-s return. There are additional callbacks that are not related to runs, events, or tracking:
BLCommandRegisters command names and maps them to implementation classes.
BLCollectiveComputationRegistered with BLRunManager to perform collective computations.
BLManagerIn addition to the above callbacks, it also registers the BLPhysics object, BLBeam objects, and BLUserCode objects.
BLNTupleRegisters NTuple Handlers to implement the different types of NTuples, and also registers callbacks to be called by the appendRow() function of specific NTuples.
BLGlobalFieldRegisters individual instances of BLElementField that implement the electromagnetic field of an individual element. Handles field overlaps, and uses bounding boxes for efficiency.
**/