geo_db Directory Reference

Description

Geometry Database API

The Geometry Database is a main component of the Geometry Information System designed to store, process and manage information on geometry models of detectors. The repository contains an interface to work with the Geometry Database of an experiment.

Contents

File / directory	Description
GeoSetup	Loading of the geometry setups from the Local (SQLite) or Central Geometry Database for simulation (FairRunSim) and reconstruction (gGeoManager), magnetic field and parameter files of the setup
geo_db_settings.h	Settings of the Geometry Database
SetEnv.sh	Environment for the standalone use of the interface
local.db, storage	Local Geometry Database (SQLite replica of the Central one) and its geometry and magnetic field files; they are downloaded at the CMake configuration step (see DBL_FILE_PATH below) and are not stored in git
macros	Macros to install the Local Geometry Database, list and load the setups
examples	XML format of the local customization of a setup
doc	Doxygen configuration and reference manual of the interface

The interface is built into the GeoDb library; it is a git submodule developed in the nica_db/geo_api repository at git.jinr.ru.

1. Required external software

The interface of the Geometry Database requires the following external software to be installed: SQLite database engine, FairSoft package including CERN ROOT 6 environment and FairRoot package of the FAIR collaboration.

Install SQLite

Please make sure the SQLite database engine has been installed on your system before compiling FairSoft.

• Install the required SQLite database engine for RedHat-based OS (eg, CentOS, Scientific Linux, AlmaLinux):

  sudo yum install -y sqlite-devel

• Install the required SQLite database engine for Debian-based OS (eg, Ubuntu, Debian):

  sudo apt-get install -y libsqlite3-dev

Install FairSoft package with CERN ROOT 6 framework

Detailed instructions on how to install the FairSoft package including CERN ROOT 6 can be found on the corresponding website https://github.com/FairRootGroup/FairSoft.

Install FairRoot

Detailed instructions on how to install the FairRoot software can be found on the website of the framework: https://github.com/FairRootGroup/FairRoot.

NOTE: A detailed example of installing the FairSoft and FairRoot packages can be found at the website of our experiment here: https://bmn.jinr.ru/software-installation/ ("Installing the external packages" Section).

2. Set database environment (every time you start working with the Geometry Database)

Before deploying and using the Local Geometry Database based on SQLite, DBL_FILE_PATH variable should be set, which contains a desired full path to 'local.db' file to be downloaded, e.g. >export DBL_FILE_PATH=**[your_target_path]**/local.db

NOTE: Run “export DBL_FILE_PATH=**[your_target_path]**/local.db” every time you run terminal to work with the geometry database (or append this line to the .bashrc file).

NOTE: If a requested geometry setup is absent in the Local Geometry Database, it is downloaded from the Central One to the directory of the DBL_FILE_PATH file. This directory can be read-only, e.g. on CVMFS, so the database is installed to a writable directory instead, and the running process uses it from now on: the database is installed to a unique folder, so parallel jobs do not overwrite the files of each other. The folder is removed when the process exits normally. This folder is created in the following directory:

• the DBL_CACHE_PATH variable, if it is set like >export DBL_CACHE_PATH=**[your_scratch_path]**/geo_db
• the TMPDIR variable, if it is set and writable;
• the */tmp/[user]/* directory.

3. Clone the Geometry API and download Local Geometry Database

The Application Programming Interface of the Geometry Database is cloned from GitLab. Change directory to a desired path, where the Geometry API will be downloaded and run:

git clone https://git.jinr.ru/nica_db/geo_db.git
cd geo_db

The Local Geometry Database can be downloaded in one of two ways:

1st way = Use prepared ROOT macro for the installation of the Geometry Database

. SetEnv.sh
cd macros
root -b -q installLocalDB.C

NOTE: By default, in the SetEnv.sh file SIMPATH points to */opt/fairsoft/install*, and FAIRROOTPATH - */opt/fairroot/install* directories. If you installed FairSoft or FairRoot to another directory, please, change SIMPATH and FAIRROOTPATH variables in the file ("export SIMPATH=[your FairSoft install path]" and "export FAIRROOTPATH=[your FairRoot install path]").

2nd way = Manual downloading from the Geometry Web Service

The button for downloading full geometry database of an experiment is avaliable on the Geometry Web Service of the experiment in the upper part of the website. It ensures to download the replica of the full geometry database in the SQLite database format, which is presented as TAR archive file, namely “localdb.tar”. The TAR file includes “storage” folder and “local.db” file.

4. Using the Application Programming Interface (ROOT macros):

NOTE: Before using the ROOT macros to work with the Geometry Database, the variable DBL_FILE_PATH should be set, which contains path to the SQLite file storing the replica of the Central Geometry Database.

To show a list of the geometry setups in the local database:

root -b -q getSetupList.C

To load a geometry setup in your application, use GeoSetup class instance. It has the following main methods:

• Loading selected geometry setup for Reconstruction and Analysis from the Local Geometry Database and create gGeoManager instance.

  bool loadSetupToGeoManager(const char* setupTag, const char* revision = nullptr);

• Loading selected geometry setup for Simulation from the Local or Central (defined by url) Geometry Database and add it to the FairRunSim instance.

  bool loadSetupToFairRunSim(const char* setupTag, const char* revision = nullptr, const char* localSettings = nullptr, const char* url = nullptr);

• Getting magnetic field of the current setup geometry.

  FairField* getMagneticField(double scale = -1);

• Getting path to parameter file for the given detector name of the current setup.

  const char* getParameterFile(const char* detector_name);

  Detailed description can be found in the Doxygen documentation (doc/html folder).

Directory dependency graph for geo_db:

Directories
	doc
	Geometry Database API documentation
	examples
	Local geometry customization
	macros
	Geometry Database macros

Files
	geo_db_settings.h
	GeoSetup.cxx
	GeoSetup.h