The conditions database is designed to allow a running analysis or reconstruction module to access information about the run "conditions". In our current environment, conditions include the entire detector description.
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.
The recommended format for storing conditions information is in a zip file. The conditions database includes facilities for downloading zip files from the web and caching them, so no web connection is required when running analysis or reconstruction jobs, as long as the required conditions have been previously accessed.
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 as to which file formats can be used for conditions information.
Properties files contain line-delimited key, value pairs with the 'equals' as a '=', ':' or ' ' (space). The 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 strings can be read as individual values using the method String.split() .
For the following sections, we will use as an example the SDJan03 detector with corresponding tag of sdjan03 for conditions lookup.
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 one of the following.
sdjan03: http://www.example.com/path/to/sdjan03.zip |
sdjan03: file:/path/to/my/sdjan03/ |
sdjan03: file:/path/to/my/sdjan03.zip |
sdjan03_local: sdjan03 |
Multiple detector tags can be used used in the same alias.properties file, but each detector tag should eventually resolve to a single location.
If the name is not a URL, then it is assumed to be an alias, which is recursively translated.
Suppose the following is listed in the alias.properties.
a: b b: c c: http://www.example.com/d.zip |
The final value of a will be
http://www.example.com/d.zip |
The value after translation need not be a URL or file. It can be a detector tag.
In the following case, the value of a will be resolved to d.
a: b b: c c: d |
The d name will need to be resolved using the conditions lookup algorithm.
The alias file is stored at one or more of the following paths.
~/.lcsim/alias.properties |
org/lcsim/detector/alias.properties |
http://www.lcsim.org/detectors/alias.properties |
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 common ones.
Once the recursive names are resolved, conditions information for a detector tag is retrieved as follows.
In the case of an alias, once the final detector name is determined, the algorithm searches for a directory or zip file with the same name as the tag in the following "canonical" locations:
~/.lcsim/detectors |
/org/lcsim/detector/ |
http://www.lcsim.org/detectors/ |
The following canonical locations would be scanned for sdjan03 conditions.
Within the home directory.
~/.lcsim/detectors/sdjan03.zip ~/.lcsim/detectors/sdjan03/ |
In the jar file.
/org/lcsim/detector/sdjan03.zip /org/lcsim/detector/sdjan03/ |
On the LCSim website.
http://www.lcsim.org/detectors/sdjan03.zip |
If the lookup process does not result in a valid set of conditions, the program will terminate with an error. (In Java, this is a ConditionsNotFoundException).
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.