Creating a Local Mokka Geometry Database

The Mokka detector simulation framework uses a MySQL database to access essential information about detector geometries, materials, shared parameters, and others. By default, Mokka connects to a central MySQL database which is maintained by the Mokka developers and which runs on a server named pollin1.in2p3.fr somewhere in France. That central database is, of course, read-only. For this reason, if you want to develop your own Mokka geometry drivers or create new geometry models, you will need a database to which you have write access. The typical solution for this is to have a local MySQL database on your own computer.

This page is supposed to give you a step-by-step description how to create such a MySQL geometry database on your local computer. It won’t tell you how to install or use Mokka – see the Mokka home page in case you need further information concerning Mokka itself. Besides, this page assumes that you have a working installation of the MySQL software – see the MySQL home page for any help you may need to get and install the MySQL software package. If you have MySQL already installed (as in the DESY environment), you don’t need to be superuser to carry out the following steps – the system root user and the MySQL root user are different things.

No knowledge of the MySQL command language is required, but in case you would like to familiarise yourself with MySQL, go to the MySQL web pages and have a look at the MySQL manual. It provides not only a detailed description of all MySQL commands, but also a short tutorial which introduces the most important aspects of MySQL and which should be more than sufficient for all your needs regarding Mokka.

First, make sure that the MySQL-related commands are accessible through your PATH. If MySQL is not installed at a standard location such as /usr/bin, you have to adjust the environment variable PATH, either interactively or in a shell initialisation file:

export PATH=your_mysql_installation/bin:${PATH}

Replace your_mysql_installation by the path to your local MySQL installation. In case you get an “error while loading shared libraries”, you may need to include your_mysql_installation/lib/mysql in the environment variable LD_LIBRARY_PATH.

At DESY, the latest version for Scientific Linux 4 (as of April 2008) can be found at /opt/products/mysql/5.0.45. The server-side software (mysql_install_db and mysqld_safe) can be found only in /opt/products, but the client-side software (mysql, libmysqlclient, …) is also available locally under /usr/bin. Note that a version mismatch between server and client will generally not be a problem.

Create a data directory:

mkdir your_data_directory

Replace your_data_directory by a path of your choice, for example /data/${USER}/mysql. You will need a few megabytes of disk space. Avoid directories in the AFS, because your AFS token will expire after a day, at the latest. Do not choose a directory inside /tmp, either, because such data may automatically be erased by the system after some time.

Initialise the local database. This will create some directories and files in your data directory that are used internally by MySQL:

Note that this script has to be called from the installation directory in some versions of MySQL. Don’t be alarmed by the bunch of appearing messages – we’ll take care of the MySQL root password in a second.

Start the MySQL daemon in the background, using your data directory. It may take a moment until it is up and running. If you get an error message about insufficient permissions, you can try the option --no-defaults as the first argument.

bin/mysqld_safe --datadir=your_data_directory &cd -

Note that the daemon was called safe_mysqld in earlier versions of MySQL. It has to be running whenever you want to access your local database. If you use a program like top, you will see that the daemon spawns a couple of processes named mysqld which you don’t need to worry about. It also creates a socket file in the /tmp directory, which you should not delete. (You can specify another location or name with the --socket option.)

Enter the MySQL monitor and change some access rights for your local database: Choose a root password, delete the anonymous user, and create a user consult with password consult to be used by Mokka.

mysql -urootUPDATE mysql.user SET Password=PASSWORD('mysql_root_password') WHERE User='root';UPDATE mysql.user SET Host='your_long_hostname' WHERE Host='your_short_hostname';DELETE FROM mysql.user WHERE User='';FLUSH PRIVILEGES;GRANT SELECT ON *.* TO consult@localhost IDENTIFIED BY 'consult';GRANT SELECT ON *.* TO consult IDENTIFIED BY 'consult';QUIT;

Replace mysql_root_password by a password of your choice. your_short_hostname is the output of the command “hostname --short”, your_long_hostname is the output of “hostname --long”. Remember to terminate MySQL commands with a semicolon. Capitalisation of MySQL keywords is not mandatory, but it will not hurt, either.

Download a dump of the central Mokka geometry database from the LDC Optimisation pages at DESY. Import the the dump file into your local database:

mysql -uroot -p < your_dump_file

You will be prompted for the MySQL root password. Note that the dump file is just an automatically generated sequence of MySQL commands and some comments, so it can simply be fed into MySQL using input redirection. After that, you may remove your dump file if you like. Use the same command to extend your local database with data from other dump files, if desired.

Mokka version 05-00 introduces so-called “super drivers” which need some temporary databases for their calculations. Your dump should already have provided these databases, but you still need to grant certain access privileges to the user consult. One table in the database models03 is used to manage the access to these temporary databases – you need to enable consult to lock and modify this table, too.

You should now be ready to run Mokka with your local geometry database. Adjust the corresponding setting in your Mokka steering file:

/Mokka/init/dbHost your_mysql_host

Replace your_mysql_host by the name (or IP address) of your host (to connect via TCP) or by the special name localhost (to connect locally via a Unix socket). You can also use the extended notation host:port or localhost:/path/to/socket for more control.

In case you want to stop the MySQL daemon at some later time, use mysqladmin:

mysqladmin -uroot -p shutdown

After entering the MySQL root password, the daemon will come to a halt. Use mysqld_safe to restart it. Note that you do not need to stop the daemon before you log out – it can continue running in the background without you being logged in, even though you will still be the owner of the process.

You can browse through your database using the MySQL monitor, doing a SELECT command on each table you’d like to inspect. However, it is much more convenient to use a client with a graphical user interface. On the MySQL download pages, you can find programs such as MySQL Query Browser and MySQL Administrator. Unfortunately, both of these will cause you trouble in the DESY environment, so you may want to use the older MySQL Control Center instead. Read how to set up MySQL Control Center, if you like.

Graphical browsers also let you make changes to the contents of your database. However, in terms of reproducibility and also the ability to share your data with others, it can be much more convenient to write a short MySQL dump file by hand and process it with the MySQL monitor, as explained above. Generally speaking, you should choose this method as soon as you change or insert more than one or two values. Keep in mind that you may need to get a fresh dump of the central database whenever a new version of Mokka is released, thus overwriting your custom changes. If you perform all your modifications with the help of small dump files, you will be able to redo them much more easily.

A final remark: Did you encounter any problems while following the descriptions on this page? Do you think some things were hard to understand? Have you found a mistake? Don’t hesitate to drop me a line!