org.lcsim Conditions Database
| Table of Contents |
|---|
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, 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.
Conditions Formats
| Tip | ||
|---|---|---|
| ||
The conditions framework should be used for information that is associated with one or more detectors. It should not be used for detector-independent settings on analysis algorithms, as this would force end users to create or locate a properties file for that algorithm. Instead, algorithm settings should use "getter" and "setter" methods on a Driver, e.g. getX() and setX(). This will allow these settings to |
Conditions Formats
The conditions framework API makes no assumptions about the format of the conditions data. However, the default implementation of the condition database assumes that the data is stored in zip files or file system directories. The package 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 internet 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.
If storing conditions in zip files is not suitable for your project, there are two options. You can either implement the conditions framework interfaces from scratch, or use the standard implementation with custom conditions reader. If the detector.properties file in the conditions zip file or directory contains a line in the "ConditionsReader: ClassName" format, the framework will instantiate ClassName class and use it in place of the standard reader. The latter option makes it possible to keep some conditions in zip files while fetching others from a database, for example.
Properties Files
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'.
| No Format |
|---|
charm = strange
charm: strange
charm :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() .
Accessing Conditions
For the following sections, we will use as an example the SDJan03 detector with corresponding tag of sdjan03 for conditions lookup.
Detector Alias Files
An alias file is a property file Alias files are properties files, named alias.properties, that lists list the locations location of conditions information for a specific detector tagtags.
It has Alias files have the the following format.
| No Format |
|---|
[detector_name]: [conditions] |
...
Multiple detector tags can be used used in the same alias.properties file, but each detector tag should eventually resolve to a single location.
Minimally, this directory or zip file should contain a file called compact.xml with the compact geometry description for the detector.
It may also contain sampling fractions, track smearing parameters, and other conditions for specific org.lcsim drivers.
Recursive Name Translation
If the name value is not a URL, then it is assumed to be an alias, which . This is recursively translatedresolved recursively until the "base" value is obtained for that key.
Suppose the following is listed in the alias.properties.
...
| No Format |
|---|
a: b b: c c: d |
The d name will need to be resolved using the conditions lookup algorithm.
Alias File Locations
The alias file is Alias files are stored at one or more of the following pathslocations.
- The LCSim work directory in the user home directory.
No Format ~/.lcsim/alias.properties
- Within the lcsim.jar file at the following path.
No Format org/lcsim/detector/alias.properties
- At a URL on the LCSim website.
No Format http://www.lcsim.org/detectors/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.
On Windows, the default location of the .lcsim directory is usually
| No Format |
|---|
C:/Documents and Settings/username/.lcsim/ |
.
Conditions Lookup
Once the recursive names are resolved, conditions Conditions information for a detector tag is retrieved as follows.
- If the tag value is a URL with a protocol of file:, the local file (zip format) or directory path specified is assumed to contain the conditions.
- If the tag value is the URL of a zip file at a remote URL, an attempt is made to download the file from that location, unless the zip file is already in the local cache (~/.lcsim/cache). In this case, the local copy is used instead.
In the case of an alias, once the final detector name is determined, the algorithm searches that the tag value resolves to a detector tag, the following "canonical" locations are searched for a directory or zip file with the same name as the tag in the following "canonical" locations:
- In the user home directory.
No Format ~/.lcsim/detectors
- Within the lcsim.jar file.
No Format /org/lcsim/detector/
- On the LCSim website.
No Format http://www.lcsim.org/detectors/
The So the following canonical locations would be scanned for sdjan03 conditions.
- Within the home directory.
No Format ~/.lcsim/detectors/sdjan03.zip ~/.lcsim/detectors/sdjan03/ - In the jar file.
No Format /org/lcsim/detector/sdjan03.zip /org/lcsim/detector/sdjan03/ - On the LCSim website.
No Format 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).
Java Example
Here is an example of accessing conditions of the sdjan03 detector from Java code.
...
| No Format |
|---|
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.
Retrieving the Magnetic Field Information
The org.lcsim.geometry.FieldMap interface provides information about the magnetic field of the detector.
The B-field is retrievable from within a Driver's process method.
| No Format |
|---|
void process(EventHeader header)
{
// Give a position for the B-field measurement to be retrieved.
double[] pos = {0,0,0};
// Provide your own b array to be filled.
double [] b = {0,0,0};
// Get the FieldMap from the detector.
FieldMap field = event.getDetector().getFieldMap();
// Fill your array with the B field data.
field.getField(pos, b);
// Print B field data to screen.
System.out.println("bfield (" + b[0] + "," + b[1] + "," + b[2] + ")");
}
|
Setting the Cache Directory
Sometimes the default location of the user home directory is not a good place to download and store conditions information. For instance, grid jobs do not generally run under a user's credentials but a user name associated with the VO, so the default location will not work.
There are two ways to change the base cache directory, depending on the method being used to run lcsim.
If the lcsim jar is being run using the java command, set the system property org.lcsim.cacheDir to point to the directory where conditions information will be cached.
| No Format |
|---|
java -Dorg.lcsim.cacheDir=/my/cache/dir [...rest of options...]
|
The recon XML format provided by lcsim also has a setting for this.
| No Format |
|---|
<control>
<cacheDirectory>/my/cache/directory</cacheDirectory>
</control>
|
The user's alias.properties file should also go in this directory instead of the home area.
Implementation Caveats
At the moment, there is a couple of implementation peculiarities you should be aware of.
The framework API lets you register listeners on ConditionsManager or on any Conditions, but the Conditions implementation simply forwards registration to the ConditionsManager. The result is that if, for example, you register your listener on two ConditionsSets, you will receive notifications of any conditions changes, not just those involving the two sets you are interested in, and you will receive them twice. For now, register all your listeners on the ConditionsManager to avoid this problem.
Once the conditions have changed, asking for data from an existing CachedConditions object will get you updated information. However, asking for data from an existing ConditionsSet will return old data - you have to get a new instance of the ConditionsSet from the ConditionsManager.