org.lcsim Conditions Database

Overview

The conditions database is designed to allow a running analysis or reconstruction module to access information about the run "conditions". In our current environment the "conditions" includes the entire detector description, since this is not hardwired into the framework at all.

The recommended format for storing conditions file collections is in a zip file. The conditions database includes facilities for downloading .zip files from the web and caching them on the user's machine, so no web connection is required when running analysis or reconstruction, as long as the required conditions have been previously accessed.

The org.lcsim conditions framework is designed to be very flexible, both in use and in implementation. Our current implementation looks up conditions based on the detector name.

Conditions Formats

The conditions themselves are stored as an arbitrary collection of files, either stored in a filesystem or in a zip file. The most common files used are property files (name, value pairs) or XML files (e.g. for geometry), however there are no constraints placed on the files.

Properties Files

Properties files are simply sets of key, value pairs with the 'equals' as a '=', ':' or ' '. Their file extension should be '.properties'.

For instance, any of the following will assign the value 'strange' to the key 'charm'.

charm = strange 
charm: strange
charm  :strange

Multiple strings can also be associated with a single key, as follows.

charm    beauty, truth, strange

The value of the key 'charm' will be 'beauty, truth, strange'. These can be read as individual values using the method String.split() .

Accessing Conditions

For the following sections, we will use as an example the SDJan03 detector with corresponding tag of sdjan03.

Detector Alias Files

An alias file is a property file named alias.properties that lists the locations of conditions information for a specific detector tag.

It has the following format.

[detector_name]: [conditions]

The value of conditions can be any of the following.

1. URL Zip File
2. Local Directory
3. Local Zip File

Suppose you want to look up conditions called SmearingParameters for sdjan03.

These could be specified in any of these three ways.

1. As a zip file on a website.

   sdjan03: http://www.example.com/path/to/sdjan03.zip
   

1. As a local directory.

   sdjan03: file:/path/to/my/sdjan03/
   

1. As a local zip file.

   sdjan03: file:/path/to/my/sdjan03.zip
   

Multiple detector tags can be used used in the same alias.properties file, but each detector tag should be listed only once.

Alias Locations

The alias file is stored in one or more of the following locations.

1. The LCSim work directory in the user home directory.

   ~/.lcsim/

2. Within the lcsim.jar file at the following path.

   org/lcsim/detector/

3. At a URL on the LCSim website.

   http://www.lcsim.org/detectors/

Your custom aliases belong at

~/.lcsim/alias.properties

as this is likely the only place to which you'll have write access, and your own aliases should be kept separate from the shared ones.

Alias Translation

Once this translation is complete, the resulting value is checked as follows.

1. If the name is a URL with a file: protocol, the file or directory specified is assumed to contain the conditions.
   Here is an example zipfile location.

   sdjan03: file:/path/to/sdjan03.zip
   

   Here is an example directory.

   sdjan03: file:/path/to/sdjan03
   

2. If the name is a remote URL then an attempt is made to download a zip file from that location (if the zip file is already in the local cache and up-to-date it is used from there).
   This is an example URL.

   http://www.example.com/path/to/sdjan03.zip
   

3. If the name is not a URL, we search for a directory or zip file with that name in the following locations:
   1. ~/.lcsim/detectors
   2. Within the lcsim.jar file at

      /org/lcsim/detector/

   3. At

      http://www.lcsim.org/detectors/

If none of these succeed in finding the conditions for the specied detector the program will terminate.

Java Example

Here is an example of accessing conditions of the sdjan03 detector from Java code.

First, retrieve the default instance of the ConditionsManager.

ConditionsManager mgr = ConditionsManager.defaultInstance();

Then look up the conditions. The base location is http://www.lcsim.org/detectors/sdjan03.zip.

mgr.setDetector("sdjan03", 0);

Conditions are stored in sets, usually organized by single files or directories.

For example, sampling fractions can be found in the SamplingFractions.properties file, which is referred to as SamplingFractions when using the ConditionsManager.

ConditionsSet cs = mgr.getConditions("SamplingFractions");

Now, the sampling fractions are available by their keys.

This code simply iterates over the keys and prints their keys and values.

for ( Object o : cs.keySet() )
{
    System.out.println(o.toString() + "=" + cs.getString(o.toString()) );
}

Most likely, the typed values from the ConditionsSet need to be retrieved in order to do anything useful.

Here is an example showing how to convert conditions in a ConditionSet to their typed values, one-by-one.

for ( Object o : cs.keySet() )
{
    String k = (String) o;

    Class typ = cs.getType(k);

    if ( typ == double.class )
    {
        double dblVal = cs.getDouble(k);
    }
    else if ( typ == int.class )
    {
        int intVal = cs.getInt(k);
    }
    else if ( typ == java.lang.String.class )
    {
        String strVal = cs.getString(k);
    } 
}

Presumably, an algorithm will do something with the value once it is retrieved.