field/BlineTracer/README.md

0001 \page ExampleBlineTracer Example BlineTracer
0002
0003 \author Laurent Desorgher (desorgher@phim.unibe.ch) - 04/10/2003
0004
0005 The BlineTracer module allows to trace and visualise magnetic field
0006 lines in a Geant4 application where particle are tracked through the
0007 magnetic field (in future, these functionalities may be integrated in
0008 the Geant4 kernel).
0009
0010 To use the tracer, the user should copy the classes provided here in
0011 his/her own application/example and create somewhere in his/her code
0012 an instance of a G4BlineTracer object.
0013 It can be anywhere (for example in the main code or in the user class
0014 defining the magnetic field):
0015
0016 ```cpp
0017 #include "G4BlineTracer.hh"
0018 G4BlineTracer* theBlineTool = new G4BlineTracer();
0019 ```
0020
0021 ## Design principles
0022
0023 The core of the tool is the method G4BlineTracer::ComputeBlines() of G4BlineTracer class.
0024 In this method a bline is computed by tracking a ChargedGeantino in the user
0025 defined magnetic field and by using a Bline equation of motion (class
0026 G4BlineEquation, motion along the field) instead of a Lorentz equation.
0027
0028 During the execution of this method :
0029
0030  - The user defined  equations of motion associated to the different
0031   global  and local fields are replaced by instances of G4BlineEquation
0032   associated to the same fields.
0033   The G4BlineEquation class defines the differential equation of a
0034   magnetic field line.
0035
0036  - User defined ChordFinders are replaced by new ChordFinders
0037   associated to the G4BlineEquation object.
0038
0039  - The user primary generator action, run action, event action and
0040   stepping action are replaced by instances of the classes
0041   G4BlinePrimaryGeneratorAction, G4BlineTracer, G4BlineEventAction
0042   and G4BlineSteppingAction respectively. Other actions are set to
0043   a NULL pointer.
0044
0045 After the execution of the method, the original user defined actions, equation
0046 of motions and chord-finders are restored.
0047
0048 In other words, the deafult run-action is temporarly replaced by a
0049 G4BlineTracer run-action using the same Geometry, physics and magnetic fields
0050 but with a different equation of motion and user actions.
0051
0052 The  G4BlinePrimaryGeneratorAction::GeneratePrimaries() method of the G4BlinePrimaryGeneratorAction class
0053 call the GeneratePrimaries() method of the user defined PrimaryGeneratorAction
0054 for defining the start position and start time of tracking.
0055 Start position for user application and for Bline tracking are therefore
0056 controlled by the same UI commands.
0057 The type of particles to be tracked when tracing Blines is always set
0058 to Charged-Geantino. This allows to switch off the effect of electromagnetic
0059 and hadronics physics when tracing field lines.
0060
0061
0062 The G4BlineEventAction class is responsible to store computed magnetic field
0063 lines as a vector of Polylines and Polymarkers for later visualisation.
0064 These vectors can be drawn and reset at any time.
0065
0066 The stepping action does nothing in this implementation but it can be used
0067 in future versions to limit field line tracing to physical volumes defined
0068 by the user. For this purpose a G4BlineStackingAction could also be
0069 implemented.
0070
0071 ## User Manual
0072
0073 ### General description
0074
0075 The BlineTracer is controlled by the UI commands contained in the directory
0076 /vis/blineTracer. By calling the command 'computeBline', several magnetic field
0077 lines passing through user defined start positions are computed.
0078 Start positions are generated by the user primary generator action.
0079 By doing so, the definition of start positions is the same for usual particles
0080 tracking and magnetic field line tracking.
0081
0082 A magnetic field line is computed as a track of a charged geantino that moves
0083 along the field line. The user can define the maximum length of a tracking step
0084 (only valid for Bline tracing purposes) by the use of the 'setMaxStepLength'
0085 command.
0086
0087 By using small enough maximum step length, smooth magnetic field lines are
0088 obtained. By using the command 'stockLines' and 'stockPoints' the user
0089 can decide to store the series of tracking step positions defining
0090 a magnetic field line as a Polyline object and/or a PolyMarker object
0091 (circles) respectively.
0092
0093 These objects are stored in vectors of PolyLines and PolyMarkers.
0094 By using the command 'draw', these vectors are added to the scene
0095 of the visualisation manager, provided that a scene handler and
0096 visualisation driver have been properly created.
0097
0098 The scene is visualised by invoking the vis command '/vis/show'.
0099 Polyline objects are visualised as line segments joining the different
0100 step positions defining a line, while for a Polymarker object markers
0101 (here circles), are  drawn at each step positions.
0102
0103 By using the 'setColour' the user defines the visualisation colour
0104 that will be associated to the next computed magnetic field lines.
0105 By calling 'setPointSize' the user defines the size of visualisation markers
0106 that will be  associated to the next computed magnetic field lines.
0107 The user can remove the vector of Polymarker and Polyline from the memory
0108 by invoking 'resetMaterialToBeDrawn'.
0109
0110 When using small max step size and polymarkers for visualisation purposes, the
0111 thickness of a smooth magnetic field line is obtained. It is controlled by the
0112 Marker size parameter ('setPointSize')
0113
0114 ### Command description
0115
0116 ```
0117 /vis/blineTracer/computeBline  nb_of_lines
0118 ```
0119     - Parameters: integer nb_of_lines
0120     - Description: Compute nb_of_lines different magnetic field lines
0121
0122 ```
0123 /vis/blineTracer/setMaxStepLength max_step_length
0124 ```
0125     - Parameters: double max_step_length
0126     - Description: Set the maximum tracking step length for computing
0127                    magnetic field lines
0128
0129 ```
0130 /vis/blineTracer/setColour  red green blue
0131 ```
0132     - Parameters: double red, green, blue
0133     - Description: Define  the colour for visualisation of the
0134                    next computed magnetic field lines. The color is
0135                    defined by a  RGB code (red,green,blue)  with all
0136                    parameters smaller than 1.
0137
0138 ```
0139  /vis/blineTracer/stockLines aBool
0140 ```
0141     - Parameters: boolean aBool
0142     - Description: If true the next computed field lines are stored
0143                    as Polylines for further visualisation
0144
0145 ```
0146 /vis/blineTracer/stockLines aBool
0147 ```
0148     - Parameters: boolean aBool
0149     - Description: If true the next computed field lines are stored
0150                    as Polymarkers for further visualisation
0151
0152 ```
0153 /vis/blineTracer/setPointSize point_size
0154 ```
0155     - Parameters: double point_size
0156     - Description: set the size of the visualisation  markers
0157                    that will be associated with the next computed
0158                    magnetic field lines
0159
0160 ```
0161 /vis/blineTracer/resetMaterialToBeDrawn
0162 ```
0163     - Parameters: none
0164     - Description: The vector of Polyline and Polymarker representing
0165                    magnetic field lines to be visualised are removed
0166                    from memory
0167
0168 ```
0169 /tracking/storeTrajectory 1
0170 ```
0171     - If the storeTrajectory parameter is not set no field lines are
0172       stored.
0173
0174   An example for Bline visualisation is provided in the bline_vis.mac macro.
0175
0176 ## Current limitations & known problems
0177
0178  The tool is working properly only for detectors parts where magnetic
0179  field are defined. It is planned in the future to stop the tracking of
0180  field lines in regions where no fields are existing.