Infrequently asked questions with their even less frequently given answers! Excerpts from some e-mail traffic of the last three years, covering everything from Mokka to Mokka. This is just a compilation of things that have come up in the course of time – don’t expect a nice, well-structured, easily readable, faultless writeup, please.
Please note: This document is not supposed to be a user manual and it will not tell you how to use Mokka in general. Only a couple of more or less arcane side issues are covered, but maybe you’ll find just what you were looking for …
The official Mokka web pages (not complete in all parts yet)
The previous version of the Mokka web pages before the migration to Plone (partially outdated)
Mokka release notes: The Mokka release notes (can be found in the directory “Mokka/ReleaseNotes”) contain information about changes from version to version, but you will not always be able to get a coherent picture of the whole thing without reading a lot of information (some of which is outdated again, and so on). “grep” may help you …
The Detector Model Database Browser, a benign web-based interface to the Mokka geometry management system, and the Mokka Geometry Database Cross-Reference
The “ILC Soft” software portal provides links to all relevant software packages
The LDC/ILD Optimisation web pages
Responsible persons:
In case of more general questions, you can also post messages on the Linear Collider Forum, which has a section dedicated to Mokka
The Geant4 User’s Guide for Application Developers provides detailed information about the underlying Geant4 framework and its usage in applications like Mokka
The Geant4 HyperNews are a forum with several sections that cover various Geant4-related questions
Run Mokka with the (uppercase) command line option “-H” to get a description of possible command line arguments (the lowercase option “-h” had already been used for another purpose). The parsing of command line arguments follows the usual “getopt(3)” conventions. Long options “--like-this” are not supported.
As in any Geant4-based application, some help can be displayed in the terminal with the “help” command. Entering a number will select the corresponding item (command or subdirectory), negative numbers will take you back. Entering zero will exit the help system and go back to the “Idle>” prompt. The entire help can also be accessed in a convenient way with the command “/control/createHTML”. This will export all help pages as HTML files, which can then be viewed with a browser. The root command directory can be found in “_.html”, since every slash in the command directory structure will be translated to an underscore in the respective filename.
Apart from the help, you can navigate through the command directory structure using “cd”, “pwd”, and “ls”, which will display a short help for all entries in the current command directory. Comments (which have to be on a line of their own) are indicated by a leading number sign “#”. The long help for single commands can be displayed by a preceding “help” in front of the command name. The current history of commands can be displayed by “hist”.
A leading question mark will display the current parameter settings for a given command in many cases (though not always). Often parameters are marked as “omittable”, in which case the value is either set to a default constant or “taken from the current value”. If default values shall be used only for one (or several) of the leading or middle parameters, they can be replaced by exclamation marks. If default values shall be used for the rearmost (or all) parameters, they can simply be left out.
cd /gun
pwd
ls
cd
# comment
help /gun/position
/gun/position 1 2 3 m
?/gun/position
/gun/position ! ! 20 cm
histThe Mokka-specific commands appear in the “/Mokka/” command directory and they are explained in the help system as well. (The actual usefulness of these explanations may vary.) In any case, you can easily see which commands exist in the first place, and you can then search the release notes for further information.
Please be aware that further command directories and commands may be created anywhere inside the command directory structure at runtime. Certain commands may initialise new kinds of Geant4 objects, which will in turn create new commands in the user interface. You will often get an appropriate message on the standard output that tells you what happened and how you can proceed. An example is the command “/vis/scene/add/trajectories”, which will eventually lead to the creation of a new command directory “/vis/modeling/trajectories/”. Some of the commands in that directory will in turn trigger the creation of further custom directories. Take your time to explore!
The visualisation of detector geometries is done through visualisation drivers that are provided by Geant4. (Mokka is not immediately involved here.) There are many different visualisation drivers – some provide images that are directly visible on the screen, others produce output files that need to be post-processed by other applications, or textual information:
“OGLIX” and “OGLSX”: The ususal display on the screen via OpenGL and X11. If you like, you can take screenshots with the graphics tool of your choice – simple but robust. You can also try and export your current view as EPS, but results may vary. The “OGLIX” variant will use “immediate”, unbuffered drawing – the viewer will use little memory, but images will be lost as soon as the viewer window is covered by another window. (If your window manager offers a setting like “always on top”, that may be useful – but beware of the screen saver or multiple desktops!) The “OGLSX” variant will use “stored”, buffered drawing – the viewer will use more memory and may become noticeably slow when many objetcs are displayed (e. g. events with many tracks), but redrawing will be done automatically.
“OGLIXm” and “OLGSXm”: Similar to the above, but with an interactive graphical user interface based on the Motif toolkit. The interactive features are started via “/vis/viewer/flush”, then you can use the mouse to adjust settings with the help of menu items and dialog boxes. The interactive mode can be exited with the menu item “Miscellany” → “Exit to G4Vis>”. You can switch back and forth between command line and graphical user interface as you like. Most of the menu items and dialog settings correspond to commands that can be entered by hand on the command line. The “OGLIXm” variant may be prone to flickering.
“HepRepFile” and “HepRepXML”: Produces “HepRep” files that can be opened and displayed with WIRED or HepRApp. The latest versions of WIRED are only available as plugins to JAS, but HepRApp is a rather new stand-alone Java application. WIRED looks fancy but may sometimes run a bit slowly (or get completely stuck), whereas the handling of the HepRApp user interface can be slightly cumbersome and counter-intuitive.
“VRML1”, “VRML1FILE”, “VRML2”, and “VRML2FILE”: Produces VRML files that can be displayed with specialised VRML viewers. VRML is a powerful and standardised system that is not only physics-related.
“RayTracer” and “RayTracerX”: Produces bitmap images by means of ray tracing. The viewer uses Geant4 built-in processes for the transportation of photons through the detector geometry, which may produce very nice pictures, but may also take some time. The “RayTracerX” variant also displays the image on the screen while it is being rendered.
“ATree” and “GAGTree”: Displays a textual representation of the hierarchy of geometry volumes. Can be very helpful in the debugging of geometries, but there’s not much to see. The “ATree” prints its output on the terminal upon “/vis/viewer/flush” or “/vis/drawTree”, the verbosity can be set via “/vis/ASCIITree/verbose”. The “GAGTree” displays its output in a GAG window.
“DAWNFILE” and “DAWN”: Produce files that can be rendered with DAWN, often called the “Fukui Renderer”. DAWN renders the data and produces high-quality PostScript images. You can also use DAWNCUT to apply cuts in the geometry. The output file will be produced (and DAWN will be started if it is reachable through your “PATH”) after “/vis/viewer/flush”. The “DAWNFILE” variant will create output files, the “DAWN” variant will try to communicate with a DAWN server over the network.
More information about the various visualisation drivers can be found in the Geant4 “User’s Guide for Application Developers”, section 8.3. Take your time and browse around in the built-in help system to learn more about all the available features of Geant4. Over the time, the whole system – especially everything related to visualisation – has become rather powerful.
Using the built-in “ASCIITree” viewer can reproduce the full detector geometry tree as Geant4 sees it:
/vis/scene/create
/vis/scene/add/volume world
/vis/open ATree
/vis/ASCIITree/verbose verbosity # see the built-in help
/vis/viewer/flushUsing the “/Mokka/Visu/Detector/” commands will display Mokka’s opinion about what might be going on:
/Mokka/Visu/Detector/ListGeometryTreePlease have a look at the release notes for mokka-06-00 in oder to find out how to use these commands and how to show, hide, or colour certain subdetectors. Good candidates for subdetector names are “tube”, “vxd”, “tpc”, “ecal”, “hcal”, “coil”, “yoke”, and so on – but “ListGeometryTree” will tell you the details.
If the “ASCIITree” or “ListGeometryTree” produce too much output, you may want to catch it with a tool like “less” – for example:
./bin/Linux-g++/Mokka ./mokka.steer << EOT | less
/Mokka/Visu/Detector/ListGeometryTree
exit
EOTMake sure you don’t forget the “exit” command in that case.
Picking in the viewer (only implemented for OpenGL and OpenInventor viewers up to now):
/vis/scene/create
/vis/open OGLIX
/vis/viewer/set/picking true
# adjust the view to your liking (zoom, rotate, pan, …)
/vis/viewer/flush
# left-click in the window and hope for the best …
# middle-click in the window to get back to the promptThis feature is rather new and it’s possible that you get some strange effects every now and then. But anything is better than nothing! (Finally, Geant4 starts to acquire the functionality that GEANT3 had ages ago …)
Displaying all volumes in the geometry, irrespective of their visibility setting (may take some time):
/vis/viewer/set/culling global falseViewing only a section plane (i. e. a thin slice), going through point “X Y Z” with normal vector “NX NY NZ”:
/vis/viewer/set/sectionPlane on X Y Z UNIT NX NY NZ
/vis/viewer/set/sectionPlane offApplying one or more cutaway planes (i. e. removal of a half space), either in “union” or in “intersection” mode:
/vis/viewer/addCutawayPlane X Y Z UNIT NX NY NZ
/vis/viewer/set/cutawayMode union | intersection
/vis/viewer/changeCutawayPlane INDEX X Y Z UNIT NX NY NZ
/vis/viewer/clearCutawayPlanesViewers for HepRep files and similar geometry formats may even have much more advanced capabilities – consult the documentation of the respective application to get the most out of it.
A straightforward, yet effective way to find geometry overlaps is by eye. Use an online visualisation driver (e. g. one of the OpenGL drivers), apply a section cut through the geometry (“/vis/viewer/set/sectionPlane”), zoom in (“/vis/viewer/zoomTo” or the corresponding slider in the dialog box) and pan around (“/vis/viewer/panTo” or the corresponding buttons in the dialog box) to find overlapping volumes. It may help to select wireframe mode (“/vis/geometry/set/forceWireframe”) or to display all volumes including invisible ones (“/vis/geometry/set/visibility” or “/vis/viewer/set/culling”). Picking (“/vis/viewer/set/picking”) or the “ATree” driver can help you to identify single volumes and to understand the volume hierarchy.
This approach is of course not absolutely safe: You cannot directly see the volume hierarchy, which means you’ll typically only recognise partial overlaps. Furthermore, you need to have some suspicion where geometry errors might be in order to place your section plane sensibly. Lastly, some constellations may lead to artifacts in the viewer that can look like a geometry error, but they aren’t. Nevertheless, looking at the geometry closely will catch the most common errors.
Produce an output file with the “DAWNFILE” driver and run it through DAVID to check the geometry for overlaps. DAVID will output errors on the terminal and it will also produce a second DAWN file where overlapping volumes are marked in red colour. DAVID works wonderfully for relatively simple shapes, but it is known to have some problems for volumes with more complicated shapes or placements. In any case, DAVID should provide very valuable help – even though its output may not be fool-proof, it can at least tell you where to look more closely.
The commands in the command directory “/geometry/test/” are specifically designed for geometry tests – read the Geant4 built-in help to learn what they do. Remember to use the “recursionFlag” to check more than one single level of the volume hierarchy. The built-in grid test and the cylinder test may not always be the optimal choice because they will either need a very long time (for small cells) or they may miss critical details of the geometry (for large cells). Sometimes it could be just the right choice to do some line tests in places where you suspect possible problems. You can also use a small shell script to output a series of line test commands that does a semi-automatic scan through parts of the geometry. Note that the command “/geometry/test/direction” does not strictly take a direction, but a momentum vector: The predefined value is 1 MeV, but may also want to try different orders of magnitude here.
Unfortunately, the results of the built-in geometry checks are not completely reliable, either: You may get false positives as well as false negatives, which means that you can neither be sure that your geometry is correct nor that there is an error. Try different tolerances and momenta. In case of doubt, use a viewer for visualisation or read the source code that constructs the geometry.
There is a plugin for Mokka that makes the built-in geometry checking of Geant4 available on the command line. See the corresponding readme file under “Mokka/source/Plugin/OverlapPlugin” for details, and keep in mind that the checking heuristics is not infallible.
External viewers for data formats like HepRep or VRML may have much more advanced possibilities of geometry checking. Consult the documentation of your favourite tool.
Ages ago there have been rumours about a ROOT-based geometry checker for GEANT (probably still version 3). However, nobody has ever seen it since, and there is no suitable interface between Geant4 and ROOT, anyway.
There are several ways to display events (i. e. trajectories and hits) in the Geant4 viewer. Results may vary.
Use the commands “/vis/scene/add/trajectories” and “/vis/scene/add/hits” to have trajectories and hits immediately displayed by Geant4. This will offer you rather detailed possibilities to control the visualisation of trajectories with the commands in “/vis/modeling/trajectories/”.
Try the command “/step/draw” to have each simulated step drawn by Geant4 on the fly.
Try the command “/Mokka/Draw true” and check out the various commands in “/Mokka/Visu/”.
Try the “VisPlugin”, if you like. Have a look at the file “Mokka/source/Plugin/VisPlugin/Readme” for further information.
Use the commands “/vis/scene/endOfEventAction accumulate [maxNumber]” and “/vis/scene/endOfRunAction accumulate” to overlay the visualisation of multiple events or runs respectively. The optional parameter maxNumber specifies how many events should be buffered in memory – you may want to select a smaller number than the default value of 100.
Setting up the environment for Geant4:
export G4WORKDIR=/path/to/local/mokka/installation
export G4INSTALL=/afs/desy.de/group/it/ilcsoft/geant4/9.0.p01
source $G4INSTALL/env.sh # this sets a lot of further variablesAdditional settings for Geant4 that you may find convenient (may already be contained in “env.sh”, depending on the Geant4 installation):
export G4UI_USE_TCSH=1 # smarter command line
unset G4UI_USE_XM # no Motif user interface
unset G4UI_USE_XAW # no Athena user interface
#export G4DEBUG=1 # if you want to enable debugging support
#export G4UI_NONE=1 # if you want to disable any kind of user interface
#export G4VIS_NONE=1 # if you want to disable any kind of visualisation
# (but keep in mind the comment on possible linking problems below)If you want to enable/disable certain Geant4 visualisation drivers, user interfaces, or library extensions, keep in mind that the environment variables “G4VIS_BUILD_*_DRIVER”, “G4UI_BUILD_*_SESSION”, and “G4LIB_BUILD_*” are only taken into account while building the Geant4 toolkit itself, whereas “G4VIS_USE_*”, “G4UI_USE_*”, and “G4LIB_USE_*” will be evaluated while building a Geant4-dependent application like Mokka. If you try to “use” a feature in your application that has not been “built” into your specific Geant4 installation, you’ll get linker errors.
External ILC software packages (strictly speaking not required, but strongly recommended):
export LCIO=/afs/desy.de/group/it/ilcsoft/lcio/v01-10
export GEAR=/afs/desy.de/group/it/ilcsoft/gear/v00-08MySQL client software: “mysql_config” must be reachable through your “PATH” (but it may already be available locally under “/usr/bin”)
#export PATH=/afs/desy.de/group/it/ilcsoft/mysql/5.0.26/bin:$PATH
#export MANPATH=/afs/desy.de/group/it/ilcsoft/mysql/5.0.26/man:$MANPATHAIDA support: “aida-config” must be reachable through your “PATH” (optional)
#export RAIDA_HOME=/afs/desy.de/group/it/ilcsoft/v01-03/RAIDA/v01-03
#source $RAIDA_HOME/bin/aida-setup.sh
#export G4ANALYSIS_USE=1 # if you want to enable AIDA supportYou can of course choose different versions or local installations of Geant4, LCIO, Gear, MySQL, or any AIDA implementation.
Only a couple of environment variables that point to the location of Geant4 data files (currently “G4LEVELGAMMADATA”, “G4LEDATA”, “G4NEUTRONHPDATA”, “G4RADIOACTIVEDATA”, and “G4ABLADATA”, depending on your version of Geant4) need to be set at runtime. The easiest and safest way is to source “$G4INSTALL/env.sh” also before running Mokka, even though this will set many other variables that are not required at runtime.
Apart from that, you may have to set an appropriate “LD_LIBRARY_PATH” to specify the search path for shared libraries that cannot be found by the loader. The “ldd” tool will help you to see which shared objects can be found (and where).
In order to avoid setting an “LD_LIBRARY_PATH” at runtime, you can also provide the same information once in the “LD_RUN_PATH” at linktime – these search paths will then be hard-coded into the linked executable. The built-in paths can be checked by running “objdump -p” and searching for a line titled “RPATH” or “RUNPATH”.
Using appropriate commands from “/Mokka/init/” in the steering file (preferred):
/Mokka/init/initialMacroFile macro.g4
# executes the commands in the file “macro.g4” after startup
/Mokka/init/BatchMode true
# immediately quits Mokka afterwards without issuing an “Idle>” promptSpecifying an “initialMacroFile” in the steering file and exiting from the prompt with the help of a “here string” (works with “bash” and “zsh”):
./bin/Linux-g++/Mokka ./mokka.steer <<< exitSpecifying an “initialMacroFile” in the steering file and exiting from the prompt with the help of a pipeline:
echo exit | ./bin/Linux-g++/Mokka ./mokka.steerProviding all (or some) commands (including a trailing “exit”) with the help of a “here document”:
./bin/Linux-g++/Mokka ./mokka.steer << EOT
/generator/generator ttbar.stdhep
/run/beamOn 15862674
exit
EOTProviding all (or some) commands (including a trailing “exit”) via standard input redirection (with the respective commands in the file “std.in”):
./bin/Linux-g++/Mokka ./mokka.steer < std.inIncluding a trailing “exit” command in the macro file itself will not solve the problem because this will only exit the macro, but not Mokka as a whole.
Plugins provide a way to extend the functionality of Mokka through a well-defined interface. All plugin classes should be derived from the “Plugin” base class, defined in “source/Plugin/PluginManager/include/Plugin.hh”. Plugins can define methods for most of the Optional User Actions in Geant4 (“G4UserRunAction”, “G4UserEventAction”, “G4UserTrackingAction”, “G4UserSteppingAction” – see the Geant4 “User’s Guide for Application Developers”, section 6.2) plus an “Init” and an “Exit” method, which will be called before the Geant4 user interface session is started and after it has ended.
The plugins are controlled by the “PluginManager”, which keeps a list of all available plugins that have been compiled into the Mokka executable. Plugins get registered in that list automatically by the constructor of their base class, which must be called with a string argument – this string is used as an identifier for the plugin. All plugins should define one global instance of their class. This object will automatically be constructed at startup, which means that the plugin makes itself known to the plugin manager. As a shortcut for this, there is a preprocessor macro named “INITPLUGIN”, which takes the class name and the identifier string as arguments, and which gets expanded into a global variable definition. Using this mechanism, new plugins can be added without modifying any other part of the Mokka source code. However, please read the “Comment on Possible Linking Problems” below to make sure that your new plugin actually gets linked into the Mokka executable.
The plugin manager keeps another list of plugins that have actually been activated at runtime – only those plugins will be called during the execution of Mokka. Plugins are activated by the steering file command “/Mokka/init/registerPlugin”, followed by the identifier string of the plugin. (The name of the command may sound confusing in this context, but it was kept after the plugin mechanism had changed.) Each plugin can only be activated once, which means you cannot have two instances of the same plugin (with different settings, for example).
The constructor and destructor will be called for all plugin classes, but all other methods will only be invoked for activated plugins. This means that you should keep the constructor of your derived plugin class short (or even completely empty) and move most initialisation tasks to the “Init” method, so that they only get executed when your plugin is really activated. Accordingly, the clean-up tasks should go into your “Exit” method. Another advantage of this approach comes from the fact that constructors of global objects are called at an early stage of program execution (and destructors are called very late), whereas the “Init” and “Exit” methods are called when the Geant4 and Mokka environment is already fully initialised and ready to run. This implies you can access user variables that have been defined in your Mokka steering file (via “/Mokka/init/userInitType name value”), which would not yet be possible in the context of the constructor.
You can use plugins to add new commands to the Geant4 user interface. Create the “G4UIdirectory” and “G4UIcommand” objects in the “Init” method of your script, and the corresponding method of your “G4UImessenger” will be called whenever the user executes your user-defined command. See the Geant4 “User’s Guide for Application Developers”, section 7.2 for details.
Of the plugins that currently come with Mokka, “Checkplots” is somewhat special because it makes use of AIDA. As long as the preprocessor flag “G4ANALYSIS_USE” is not defined, most of the source code is disabled, and the plugin does almost nothing. If you first compiled Mokka without AIDA support and now want to enable it: make sure that AIDA is set up properly and that “G4ANALYSIS_USE” is defined as a non-empty environment variable. Then recompile the plugin (you may need a “make clean” first) and relink the Mokka executable. During the installation of Geant4 itself you will be asked whether you want to set “G4ANALYSIS_USE” permanently (via the “setup.sh” script that belongs to Geant4), but even if you chose “no” at that point, it should be no problem to switch this variable on manually later.
If you want to write your own plugin, you need to adjust:
the class name in the whole source code, and in the “INITPLUGIN” macro in particular
the identifier string in the “INITPLUGIN” macro (or the constructor call, if you do it by hand) and in your Mokka steering file to activate the plugin at runtime
the intended library name in the “GNUmakefile” of the plugin, and an according entry in the “EXTRALIBS” section of the central Kernel makefile “Mokka/source/Kernel/GNUmakefile”
As long as your plugin is located in a subdirectory of “Mokka/source/Plugin”, there is no need to modify the top-level makefile “Mokka/source/GNUmakefile”, since all subdirectories of “Mokka/source/Plugin” will automatically be included by make.
If you are using granular Geant4 libraries (i. e. many small libraries instead of one large file that contains everything), you may want to note the following:
Each geometry driver and plugin is instantiated once as a global static object by the preprocessor macros “INSTANTIATE” and “INITPLUGIN”, respectively, and then registers itself in a list of available code modules that is kept by a manager (the “CGAGeometryManager” and the “PluginManager”). This technique has the advantage that it’s possible to add such modules without having to modify any part of the Mokka kernel, but it also has the disadvantage of breaking the explicit chain of dependencies between all the source files. The internal makefiles of Geant4 rely on these dependencies and collect all libraries that are needed for the process of linking the final Mokka executable (using the “liblist” tool). As a result, Geant4 does not know about the libraries that are only referred to by geometry drivers or plugins, so these libraries will have to be included as EXTRALIBS in the main makefile “Mokka/source/Kernel/GNUmakefile” by hand.
Currently this has to be done only for “libG4geomdivision” and “libG4geomBoolean” because all other needed libraries are also used by pieces of code that are directly connected (via chains of “#include” directives) to the top-level file “Mokka/source/Kernel/Mokka.cc”. However, this may change if future geometry drivers or plugins use other “exotic” classes, and it will also change when you try to compile with special settings such as the “G4VIS_NONE” flag, for example. (The kernel won’t need some graphics-related classes anymore, but the geometry drivers will still refer to them.) To be able to link the Mokka executable in these cases, you’ll have to find out which classes cause the problem, which of the Geant4 libraries contain them, and add these libraries to your main makefile by hand. Keep in mind that their order matters to the linker because they may again have depedencies among each other. In the example of “G4VIS_NONE”, appending “-lG4specsolids”, “-lG4csg”, and “-lG4graphics_reps” (in that order) to the variable “EXTRALIBS” should currently be sufficient to build Mokka successfully.
Another consequence of the self-registering objects is that all Mokka libraries that contain geometry drivers and plugins need to be enclosed by the linker options “-whole-archive” and “-no-whole-archive”. Otherwise the linker would completely ignore them because it cannot find any explicit dependency – these libraries are never directly called from the main program! Please keep in mind that this is simply the price that has to be paid for the flexible approach of geometry driver and plugin management.
There are two ways to communicate with the MySQL server, either from tools like “mysql” or “mysqladmin” or from other client applications such as Mokka that actually make use of the databases:
The first possibility is to use a so-called socket file, which is a special way of inter-process communication under Unix-like operating systems – see the manpage of “socket(7)” for details. Sockets appear in the usual filesystem, but they are a special type of file. For example, the command “ls -l” will show them with the first letter “s” (instead of “-” for ordinary files, “d” for directories, “l” for symbolic links, and so on), and (depending on your personal settings) they might also show up in some special colour (often pink). The communication through a socket file will only work on the local host where the file resides, but not over network-based filesystems such as AFS or NFS. If you use the option “-h localhost” (or no “-h” option at all), “mysql” will try to communicate with the MySQL server via a socket file. You can use the command line option “--socket” to specify the name of the socket file if its filename differs from the default.
The other possibility is a usual TCP connection. It will be chosen whenever you use the “-h” option with any hostname or IP address other than the special name “localhost”. Over TCP, you can reach the MySQL server from any host on the whole internet (as long as there is no firewall that blocks the connection). You can of course also use the hostname or IP address of your local host (or 127.0.0.1 or sometimes “loopback”) – then the communication will happen over TCP and not the socket file.
If you do “netstat -a | grep mysql” on your machine, you’ll see whether the MySQL server is listening to a TCP port (3306 is the standard port for MySQL) and to a socket file named like “/tmp/mysql-4.0.26.sock”. However, if that file is gone for some reason (maybe it has been deleted?), you must use the TCP connection to still communicate with the server (i. e. shut it down and restart it, such that the socket file will be created again).
mysqladmin -h 127.0.0.1 -u root -p shutdownIf everything else fails, you can also use the “kill” command to get rid of the MySQL server processes. However, keep in mind that MySQL has some built-in “keep-alive” feature that will restart “mysqld” processes whenever they are lost (crashed, killed, or whatever). Use “pstree -p $USER” to find out which one is the parent process of all the others, and kill that one first.
Details on the handling of primary vertices and generator-level decays can be found in the Geant4 “User’s Guide for Application Developers”, section 3.6.1.2.
This is also the reason why HEPEvt files that can be understood by the Geant4 built-in “G4HEPEvtInterface” for plain-text event record files are lacking some information such as the “VHEP” vertex position – see section 3.6.2.2. The “HepLCIOInterface” of Mokka can also understand complete HEPEvt files that are a one-to-one representation of the binary StdHep format, but it will simply ignore the additional fields.
Note that “short” plain-text event records are indicated by the mixed-case filename extension “.HEPEvt”, whereas “long” plain-text event record files should end in an all-lowercase “.hepevt”. Files with binary StdHep event records need a filename extension of “.stdhep”.
There are now two possibilities to set the random seed in Mokka: One is via a plugin (with the command “/Mokka/randomSeed”), which needs to be linked into the Mokka executable at linktime and registered at runtime – this is explained in a readme file under “Mokka/source/Plugin/RandomPlugin/Readme”.
The other one is via the built-in Mokka command “/Mokka/init/randomSeed”, which was added to Mokka a bit later. The two possibilities are basically equivalent – both call “static void CLHEP::HepRandom::setTheSeed(long seed)”, and this affects the underlying CLHEP random generator that is used by Geant4.
If you like (e. g. because the plugin is not linked into your executable), just replace the command “/Mokka/randomSeed” by “/Mokka/init/randomSeed” and use the built-in functionality instead of the plugin. The only advantage of the plugin is that “/Mokka/randomSeed” doesn’t necessarily need an argument: If you use no argument (or the default value 0), then the plugin will automatically create an arbitrary random seed. Furthermore, it can display the current random seed with “?/Mokka/randomSeed” (just like you can display many other current parameter settings in Geant4).
If you query the value of the random seed immediately after the startup of Mokka, you’ll get the number 9876:
?/Mokka/randomSeed
Current value(s) of the parameter(s) : 9876The global Mokka variable “Control::RandomSeed” is only used when the Mokka command “/Mokka/init/randomSeed” is actually invoked, and the predefined value 1234567890 gets overwritten in that procedure – therefore, the hard-coded value has no influence at all.
The seed should be positive, and the source code of “JamesRandom.cc” states that it “should be within the range [0, 900000000]”. The number 9876 is the first entry of “HepRandom::seedTable” in the file “SeedTable.h”.
If you want to develop your own geometry drivers or if you are designing a geometry model, you’ll need a geometry database to which you have write access (and where your modifications don’t interfere with anybody else). You may have a look at some intructions how to Create a Local Mokka Geometry Database, which should help to get you going.
If you make modifications to an existing database (such as “models03”) or if you create your own database for your driver, I’d suggest you to write a short MySQL file for these tasks, instead of modifying the database directly with a graphical interface, by typing commands at the MySQL prompt directly, or by modifying the main dump file. You can write these files by hand (instead of having them generated by mysqldump) – after all, they are simply sequences of MySQL commands that you could type in the MySQL monitor as well. (This is also the reason why you can feed them into “mysql” by plain input redirection.) You can make use of as many MySQL input files as you like. Advantages of this approach (in my opinion) will be:
Your own MySQL files are much more concise, so you can immediately see what you’re doing.
You won’t have a major problem with existing databases and tables in large dumps.
You have a clear distinction between your work and things you got from elsewhere. This is particularly important when there is a new Mokka release and you are obliged to get a new dump from the central database. If you kept your own stuff separated, chances are that you can do the upgrade with very little or even without any effort. If you fiddled around with the main dump, you may have a hard time trying to remember what you actually changed there and porting this to the new version.
If you want to share your developments with others, you can easily send your file to the Mokka developers and ask them to include your modifications in the central database.
While you’re still testing your file, you will probably read it in many times, modifying it slightly in the meantime. To avoid problems with already existing databases/tables/entries (created by yourself in earlier iterations), you could do something like the following:
DROP DATABASE IF EXISTS `foo`; -- dispose of earlier attempts
CREATE DATABASE `foo`; -- start from scratch
… -- create tables and fill them with values
DELETE FROM `models03`.`sub_detector` WHERE `name` = "bar"; -- delete the old entry, if it exists
INSERT INTO `models03`.`sub_detector` VALUES (0, "bar", …); -- create a new entry
DELETE FROM `models03`.`ingredients` WHERE `model` = "baz"; -- delete all existing ingredients
INSERT INTO `models03`.`ingredients` VALUES (0, "baz", …); -- (re-)define all ingredients of your modelBy first destroying everything which you are going to create (and which you may already have created earlier), you can be sure that there will always be exactly one instance of your data.
The capitalisation of MySQL keywords is not required, but it won’t hurt and you may find your files easier to read. Enclosing the names of databases, tables, and fields with backward (!) quotes is generally not required either, but it could be considered good style: This practice will save you from harm if any of the names ever becomes a MySQL keyword in the future. (Don’t assume that this has not happened yet.)
The management of geometries is slightly convoluted in Mokka. The software has developed and grown over time, and often existing structures were extended and patched instead of redesigned and replaced. The general principle is as follows: There are four basic constituents that are involved in the geometry construction – models, drivers, databases, and subdetectors. A driver is a piece of C++ code, a database is one MySQL database on the central (or local) MySQL server, and a subdetector is a combination of both, i. e. a certain driver that is invoked and told to connect to a certain database. A model is a set of subdetectors that, together, form an overall detector geometry.
Every detector model (which can be selected with the steering file command “/Mokka/init/detectorModel” or with the (uppercase) command line option “-M”) has a name, some description, a status and an associated detector concept given in the table “models03.model”. The status can be either “frozen” (i. e. stable and not changing in the future) or “unstable” (i. e. possibly changing in the future, with announcements going to the Mokka discussion mailing list). You should use the status “unstable” for testing versions of geometry models, and you should do production runs only with “frozen” models, because only these simulation results will be reproducible.
A detector concept has a name, some description, a size of the Geant4 world volume (given as three half-lengths of a box), and sizes of the “tracker region” and “calorimeter region” – these values are stored in the table “models03.detector_concept”. Read the release notes for mokka-03-02 and mokka-05-00 to learn how these regions (not in the sense of “G4Region”) are treated in detail.
The “CGAGeometryManager” knows about all available drivers at runtime, because every driver registers itself in a list with an identification string while its constructor runs at the startup of Mokka. This is done by the common base class of all drivers, “VSubDetectorDriver”. When you specify a certain detector model, the geometry manager looks up (in the MySQL table “models03.ingredients”) of which subdetectors it consists. Then it looks up (in the MySQL table “models03.sub_detector”) which combination of driver and database corresponds to each subdetector. Finally it invokes the driver for each subdetector (i. e. its implemetation of the function “VSubDetectorDriver::ContextualConstruct”), thereby passing to it the name of the database to which it should connect (though the first argument of the type “CGAGeometryEnvironment” and its appropriate function “CGAGeometryEnvironment::GetDBName”). The order of the invocation is determined by the field “build_order” in the database “models03.ingredients”, provided that the different subdetectors of a given model have different values assigned.
If you want to modify a given detector model at runtime, you can use commands in the steering file to switch certain subdetectors off (“/Mokka/init/EditGeometry/rmSubDetector”) or on (“/Mokka/init/EditGeometry/addSubDetector”). However, you need to be careful not to introduce inconsistencies such as volume overlaps – see the release notes for mokka-06-01 for details (“Cooking the Model Geometry at Launch Time”). You can also use the steering file command “/Mokka/init/subDetector” or the (uppercase) command line option “-S” (which overrides the option “-M”) to construct only one single subdetector, but the specific geometry parameter settings that may be associated with the model won’t be applied in that case. If you need one subdetector just like it would appear in a given geometry model, you should instead construct the whole model and then remove all other subdetectors with “/Mokka/init/EditGeometry/rmSubDetector”.
Now things start to become slightly difficult: In earlier times, the geometries were static – all numbers and sizes were either contained in the database or (in a few cases) hard-coded in the drivers. One so-called subdetector (in the Mokka meaning) would always produce the same geometry. The driver code itself could be reused by passing it the name of a different database with the same structure, but with different content. Therefore, you could have multiple subdetectors (again, in the Mokka meaning) referring to the same driver code, but to different databases – thereby producing similar, but not identical geometries. As an example, you may have a look (in the table “models03.sub_detector”) at the subdetectors “tpc00”, “tpc01”, and “tpc02”, which all use the same driver code “tpc00”, but different MySQL databases to which the driver connects. Often you only had one single subdetector (and thus database) for a given driver, but sometimes there were two or three, maybe. As mentioned before, that’s how it was done in earlier times.
At some point in time, the desire arose to have “scalable” geometries – i. e. geometries that should depend on a few global parameters (such as TPC radius, TPC length, or HCAL thickness) and then grow or shrink automatically. Of course, this is in principle a good idea, but it’s very hard to get it right (and consistent between all the different ingredients). Nowadays, a couple of those global parameters have become common practice among Mokka developers, but one still has to be extremely careful in order not to break things.
When scalable geometries and global geometry parameters were first introduced, a rather nasty workaround was developed in order to make the old, existing drivers scalable (because they could not all be rewritten so quickly): the infamous “superdrivers”. These superdrivers were able to read the relevant global geometry parameters that would influence the geometry which was constructed by their respective “subdriver” (i. e. a usual, but non-scalable Mokka geometry driver). They would then create a “temporary” faked database (named “TMP_DBnn” and managed in the table “models03.tmp_databases”) at runtime that is similar to the usual static database, but adapted to the current values of the global geometry parameters (possibly by running one of the MySQL scripts in “models03.scripts”). The superdriver then invokes its subdriver and passes to it the name of the temporary database that it created just a second ago – the subdriver will run happily and never know what’s really going on.
This apparently works, but it’s rather ugly – an additional level of indirection is introduced, the code gets complicated and cluttered over several files and classes, and you need write access (!) on the MySQL server. Therefore, the technique of using superdrivers should be considered obsolete, since it was just a workaround to keep old code functional. All new geometry drivers should query their relevant global geometry parameters directly and not use the detour over a temporary database with fake data created by a superdriver. When developing new code, you should avoid superdriver-subdriver constructs completely.
What does that mean in concrete terms? Have a look at the base class “VSubDetectorDriver”, which must be the base class for every Mokka geometry driver. Generally speaking, only two member functions of that class are important for you: the constructor and “ContextualConstruct”. These are the ones that you’ll typically implement for your own derived class. The constructor shouldn’t do anything but invoke the constructor of the base class with a reasonable identification string (which will be matched against the entry in the MySQL table “models03.sub_detector”) and a prefix for the produced LCIO output collection(s). There is no general rule, but following the common practice you could use something like:
class FooCal03: public VSubDetectorDriver
{
public:
FooCal03(): VSubDetectorDriver("foocal03", "foocal") { /* noop */ }
/* ... */
}The function that actually does the work is “ContextualConstruct”. It is invoked by the geometry manager when the detector geometry is constructed (if a subdetector that uses your driver is a part of the seleted geometry model) and the two arguments which it receives are an object of the class “CGAGeometryEnvironment” and a pointer to the world volume (which you should use as a mother volume for the placement of your detector elements). The “CGAGeometryEnvironment” can tell you the name of the MySQL database to which your driver should connect (“GetDBName”) according to the MySQL table “models03.sub_detector”, and you can query the relevant global geometry parameters (“GetParameterAsString”, “GetParameterAsDouble”, “GetParameterAsInt”). You would typically connect to the database (by creating an object of the class “Database”) to query static, non-scaling values and you would somehow calculate the scaling values at runtime with the help of global geometry parameters. Don’t forget to delete the “Database” object to close the connection to the MySQL server at the end of “ContextualConstruct”! Finally, the destructor usually doesn’t need to do anything.
One thing that may not be completely clear at first sight is “INSTANTIATE(XYZ)”, which has to appear in the “.cc” file of every driver. This is a preprocessor macro that will be expanded to the definition of one global variable (outside of any scope) that refers to an object of your class. The compiler makes sure that this global object is initialised at a very early stage of program execution, so your driver registers itself in the list of the geometry manager. There should be only one instance of your class at runtime, namely the one created by the “INSTANTIATE” macro. Note that due to this technique, you don’t need to modify any other parts of the source code (e. g. the geometry manager itself) in order to include your driver in the framework.
The table “models03.parameters” defines a (rather large) set of global geometry parameters (together with some description) and it contains default values for all of them. This default setup approximately represents LDC version 2 – you can get it by selecting the geometry model “LDC01”. The default parameter values (which are independent from any individual geometry model) can be overridden by entries in the table “models03.model_parameters” (stating explicitly which model they should be applied to). If you look closely, you’ll see that there is not a single entry belonging to “LDC01”, which is the simple reason that “LDC01” is identical to the default (at least with respect to the subdetectors that are ingredients of it).
The table “models03.sharing” tells you which of the many geometry parameters are actually made known to each of the drivers. Only the parameters that are associated to a certain driver in that table are included in its “CGAGeometryEnvironment” and can then be fetched with “GetParameterAsString”, “GetParameterAsDouble”, or “GetParameterAsInt” – all other geometry parameters are not available to the driver (except through the public global variable “Control::globalModelParameters”, which is readable and writable from everywhere). The table “models03.sharing” offers yet another mechanism to override the default value for a given geometry parameter: If the field “driver_default_value” is non-empty, this value will be included in the “CGAGeometryEnvironment” that is passed to the respective driver. Note that you must be cautious not to introduce inconsistencies such as volume overlaps.
Apart from entries in the databases “models03.parameters”, “models03.model_parameters”, and “models03.sharing”, parameter values can also be set in the Mokka steering file at runtime (with “/Mokka/init/globalModelParameter”) – these values will take precedence over all static information in the database. Lastly, parameter values (as well as the size of the tracker region and the calorimeter region) can also be modified at runtime (e. g. from within the driver code), and completely new parameters can be created without declaring them in “models03.parameters” (but not without assigning them to one or more drivers in “models03.sharing” that should be able to access them). Again, try to avoid inconsistencies.
Another, rarely-used mechanism are the so-called detector setups: Setups are declared in the table “models03.setup” with a name and some description, and the table “models03.setup_parameters” defines the geometry parameters and their respective values that belong to each setup. Similar to model-dependent parameter values, setup parameters must be included in the table “models03.parameters” and they must be associated to one or more drivers in the table “models03.sharing”. Their values are available to the driver in the “CGAGeometryEnvironment”. Detector setups – something like minor variations of a detector model – can be selected with the steering file command “/Mokka/init/detectorSetup” or with the (lowercase) command line option “-s”.
If you want to support the Gear geometry management system, you need to implement the member function “GearSetup” for your driver. It is responsible for exporting valid Gear information at runtime, provided that some Gear parameters have been defined for your kind of subdetector (this time not meant in the Mokka meaning) – contact the Gear experts if you want to know details.
If you’d like to add a new subdetector (in the non-Mokka meaning) to Mokka, you would have to write code for a Mokka driver that constructs the subdetector geometry, plus a database that contains the relevant data. You could put it in “Mokka/source/Geometry/Tesla/{include,src}”. The prefix “S” was commonly used for superdrivers, and for some reason the subdirectory “Mokka/source/Geometry/LDC” contains only such superdrivers up to now – all other developments have still gone into “Mokka/source/Geometry/Tesla” so far, for no definite reason. The numbering has no special meaning, either – for example, people simply called the first driver for the TPC “TPC00.cc”, the next one “TPC01.cc”, and so on. You could use one of the more recent files in “Mokka/source/Geometry/Tesla” as a starting point, but not “Mokka/source/Geometry/LDC/{include,src}/S*.{hh,cc}”, because these are the superdrivers that we’d like to get rid of in the future. Instead, watch out for geometry drivers that have a “ContextualConstruct” and see how they make use of the “CGAGeometryEnvironment” that they receive as a parameter. There are a few examples of these self-scaling drivers in “Mokka/source/Geometry/Tesla”.
You should not create databases at runtime – as mentioned before, that was just invented for the superdrivers. Instead, create a completely new database for your subdetector, with tables and fields that your driver code queries and understands. Note that there has been some kind of misconception right from the start of Mokka development: Usually, one project (such as Mokka) should use one single database on a MySQL server with many different tables. This way, you could have one server on a host machine and still provide databases for many different projects. However, Mokka uses many different databases for its various subdetectors, and most databases contain only one or very few tables. This is not the way you’re supposed to use a MySQL server, but it’s the way that Mokka does it – you’ll have a flood of more than a hundred small databases on your server, which gets all cluttered up – in case you have a dedicated MySQL server machine in your group, your admins may not be delighted.
One more or less important point will be to identify the global geometry parameters that are relevant for you. Recently there has been the trend to define lots of new global geometry parameters for every single driver, like for the ECAL, the HCAL and also the LumiCal. On the one hand, this has the advantage (?) that these parameters can be modified at runtime without touching the database at all (because global geometry parameters can also be set in the steering file, overriding the contents of the database), but on the other hand, this also makes things complicated and enables users to mess things up. It’s your choice whether you’d like to introduce new global geometry parameters for your driver.
Have a look at the other drivers that read the same geometry parameters as your driver to find a reasonable build order. The build order affects all “sub_detector” entries, no matter whether the corresponding driver is static, a superdriver/subdriver pair, or a self-scaling driver. For static drivers, the build order (i. e. the order in which the different drivers are invoked) doesn’t matter of course, because they are completely independent from each other. Even for superdriver/subdriver pairs or for self-scaling drivers, the build order would not matter if the values of all geometry parameters were determined only by database entries and possibly by settings in the steering file. However, drivers are able to modify geometry parameters at runtime, and then their order will make a difference. So, for example, the ECAL could push the HCAL outside to prevent an overlap, even if a specific HCAL radius was given in the database. The general rule of thumb is “the farther outside, the larger the build order”, even though this is not true in all cases.
A good starting point to test your own developments would be (a private copy of) the latest baseline model that is currently available in the central database. Check the Mokka Detector Model Database Browser to see how the various entries in the database “models03” are interpreted in the end – you can also append “mokkamodels.php?host=hostname” to query the MySQL server on any given host (if your firewall doesn’t block the connection). If your own testing model is not displayed as it’s supposed to, chances are that some information is still missing or inconsistent. You can also use the Mokka Geometry Database Cross-Reference to see which building blocks are defined in the geometry database, and how they interact with each other.
To handle hits in your sensitive detector, you should define a sensitive detector class, which has to inherit from “VSensitiveDetector”. However, you should not define your own hit class because collections of “TRKHit” and “CalHit” objects will automatically be written to the output file by the Mokka kernel at the end of each event. The kernel knows about these classes and it can translate the content of respective objects to LCIO (preferred) or plain text output files (obsolete). If you have a look at the documentation of the corresponding LCIO classes, “SimTrackerHit” and “SimCalorimeterHit”, you’ll see quite some similarity with the Mokka classes.
To become active, the sensitive detector must be registered somewhere in the “ContextualConstruct” function of the driver using the “RegisterSensitiveDetector” function, because not only Mokka, but also the Geant4 framework needs to know about sensitive volumes. This management is somewhat complex, but if you’re interested in the details, you can read section 4.4 in the Geant4 “User’s Guide for Application Developers”.
To output hit information from your sensitive detector, I suggest that you simply glance at a few other drivers and sensitive detector implementations to see what the others do in detail, e. g. in the sensitive detector constructor or in the “Initialize” function. (You have certainly seen that Mokka sensitive detectors usually have an “SD” in the filename.) The standard output format is of course LCIO, and you won’t have to care about that as long as you use the common hit classes (see above) and make your hit collection(s) known to the Mokka kernel. You should not let your subdetector create its own, private output file or data format.
The command to write out momentum and path length information for tracker hits in the LCIO output file is “/Mokka/init/lcioDetailedTRKHitMode”. As an argument you have to give the name of a Mokka hit collection for which the full information should be written out. (The command can be called more than once.)
You can find some details in section XII of the release notes for the version mokka-06-02. However, possible values for the argument can be found only in the Mokka source code. (Watch out for the value that is assigned to “G4VSensitiveDetector::collectionName”, which should happen in the constructors of the various sensitive detector classes, which are in turn called from the geometry drivers.) Maybe the Geant4 built-in command “/hits/list” can assist you. (Try to append “Collection” to the names of the sensitive detectors.)
CGA is meant as a means to spawn Mokka from inside another program, but only with limited physics simulation capabilities – if you have a look at “CGAInit.cc”, you’ll see that this has some similarity with the main file “Mokka.cc”, but it lacks a couple of features. “CGAInit” is in fact never called from inside Mokka – it is only the entrypoint into Mokka and the Geant4 world form some arbitrary other program.
Most of the CGA-related code resides in “Mokka/source/Geometry/CGA”. CGA offers several utility functions that return mostly geometry-related information – you can find a list of them in “CGADefs.h”. One of those functions is “CGAGetB”, which is implemented in “CGAFieldCalculations.cc” (you can see that it only queries the global detector field from the “G4TransportationManager” in a single point). Other things are flying around as well …
Examples for the usage of CGA are given in “Mokka/examples/CGA/Ex01.c” (as a little stand-alone program) and “Mokka/MarlinPackages” (as two Marlin processors, one initialising CGA – and thus Mokka itself – and the other one actually retrieving some information). I have never used those Marlin processors, but I still remember that it was already a pain to compile them in the first place. (Once I posted a message “Linking the Marlin packages which come with Mokka” on the Linear Collider Forum, but all that won’t win the beauty contest …) There is also some documentation in “Mokka/doc/CGADoc”, but this is obviously outdated – maybe you can still get something out of it. You can also search the release notes for appearances of “CGA”. (You’ll see that the idea is quite old, but CGA has never really been used.) You’ll quickly notice that some parts of the code (both of CGA itself and the example processors) need getting used to – the style seems to be a mix of Fortran, C, and even some C++ with a bit of Standard Template Library interspersed.
In the course of time, the general approach has changed such that Gear files now contain enough information by themselves. It should have become unnecessary to spawn Mokka in the background during a Marlin run just to query geometrical properties via CGA – instead, everything relevant should be available in the Gear file directly. This way, CGA has always lived a shadow existence and will probably continue to do so in the future, provided it has any.
I’ll try to keep this document up to date, but I cannot promise to extend the information or to add further topics, even if they may be requested. However, in case you find a downright mistake or if you think that something is incomprehensible, please don’t hesitate to contact me.
This page is valid XHTML — Last change: 2010-06-08 by Adrian Vogel <adrian.vogel@desy.de>