STAR  Computing  Simulation  
Technical Requirements Document for the STAR Detector Description Services
  Maintained by Maxim Potekhin

Version 1.0

1. Introduction

1.1 The purpose of this document

The purpose of this document is to specify the technical requirements for the STAR Detector Description Services (DDS). These requirements will define the design of the DDS, as well as help guide the changes in other elements of the STAR software that will have to be done in the course of the overall system integration.

This document does not contain the schema for the Detector Description Language and other related schemas, which will be covered in separate design documents.

1.2 Motivation

Traditionally, the experiments in High Energy and Nuclear Physics had their geometries decribed separately for the needs of simulation and processing of the experimental data (reconstruction). This was in part due to the fact that the geometry for simulation purposes was typically represented as code written in a traditional programming language (e.g. Fortran) specifically for the GEANT application (or something similar).

The reconstruction software, on the other hand, was often not based on GEANT and instead made use of some form of other geometry model, with geometrical data fed from a database. Other applications, such as event display, would often have their own geomtery model, defined from another set of parameters. One could say that typically detector models in various parts of the experiment's software were not integrated with each other.

Due to the increasing complexity of experiments, this situation is virtually impossible to sustain, as maintenance of the geometry in a few disparate pieces of code becomes extremely labor intensive, and so does verification of the geometry model (or models) existing in various software systems of the same experiment.

The STAR experiment faces challenges of that nature as well:

  • it is increasingly difficult to keep updating the geometrical (and other) detector data embedded or implicit in a variety of source files. Versioning is partly done within compiled code by sometimes complex system of switches defined at run time.
  • handshake between the geometry descriptions in the simulation and reconstruction parts of the software is difficult or non-existent, and the creators of software for the various detector subsystems are pretty much left to fend for themselves to create a Detector Model when it's needed in reconstruction.
  • it is impossible to provide a uniform geometry database for the experiment, hence very difficult to guarantee the integrity of the detector description
  • last, but not least, the current geometry description in STAR ended up being fairly non-transparent to end users, significantly diminishing our ability to use the team members' expertise in ensuring the correctness of the geometrical model. Ability of the users to make ad-hoc changes when they study the detector is also negatively impacted.
Therefore it is necessary to provide a framework, to which we will refer to as Detector Description Services, which should resolve these issues.

1.3 Recent Developments in the Area of Detector Description

Recent years have seen the growing interest in the HEP community in creating software detector models from the "single source", or "unified" geometry description. This breaks away from the tradition of writing application-specific code, in an application-specific language, for such platforms as GEANT 3.21 or GEANT 4 in the respective programming languages, such as Fortran or C++, as well as the tendency to embed the actual numerical data in such code.

Efforts in the area of detector geometry and material modeling, with varying degree of success, have been undertaken in the following experiments: ATLAS, CMS, ALICE, LHCb (as well as in a few others). Despite variety in the ways the work done in these groups, it was to a large extent based on using the XML, the Extensible Markup Language, either as a means to describe geometrical data or as an exchnage format.

The choice of XML as a platform for geometry description is based on a large number of factors. Besides those commonly found in literature, in our experience there are also the following:

  • Desire to maintain platform neutrality: the XML code serves only as vehicle for the detector decription and is not tied to a particular programming language used in the multiple clients. This allows to build a detector model that is more generic than any singgle client application and thus facilitates the existence of multiple clients.
  • There is an active development effort under way (in CMS, for example), as well as existing solutions for interfacing XML objects with databases.
  • There is a considerable degree of flexibility in how and where the data are actually stored, e.g. the possibility of using URL.
  • XML being a well established technology with a considerable amount of expertise available, along with a variety of tools readily available for processing XML code.
  • Possibility to interface with third party software products such as certain CAD packages which are XML capable.
We will assume that XML is the most likely choice for the STAR geometry description as well.

The LHC Computing Grid (LCG) project has sponsored a Requirements Technical Assessment Group on Detector Geometry and Material Description, known as RTAG#7. It included experts from CMS and other experiments and was able to absorb most of the accumulated expertise in its published recommendations. The potential of a widely accepted set of standards emerging form this activity is unclear at this point.

However, it's clear that the approach featuring a flexible Detector Description based on a single source (and often using a XML-based description language) has been established and applied in the software products created and used in a few experiments. It was decided that we in STAR should evaluate it as well, as it has the potential of bringing significant benefits to the STAR physics analyses.

A pilot project was done in February-March of 2003, which was aimed at gaining experience in expressing the STAR geometry in a XML-based description language, and studying the issues inherent in parsing such code. In parallel, we researched the current status and results of much larger and ambitious projects undertaken in other groups. We have arrived at the conclusion that a parser generating the GEANT 3.21 or GEANT 4 code, by itself, may not justify the very significant effort involved in the geometry migration, and that a broader definition of the Detector Description Services is needed.

1.4 The Structure of This Document

Section 1 contains a short Introduction to the area of detector description, motivations for the STAR experiment to get involved in this, and a summary of recent developments in that area.

In Section 2, we present a brief Glossary of Terms which help identify the problem domain. Section 3 provides some further illustrattions in the form of Usage scenarios.

Finally, in Section 4 we arrive at the Technical Requirements for the STAR Detector Description Services. It contains the General Requirements as well as a discussion of their application in a XML-based system.

In Section 5, we present some conclusions and notes on the current status of the project.

2. Glossary of Terms

We will follow, in part, the glossary provided in the RTAG#7 document, as it is close to being standard. It is given here in an abridged format for readibility, and contains some additions and other small differences:
  • Detector Description Model (DDM): transient mapping of the features related to geometry, physical attributes and behavior of the detector. It defines the structure and API for all client applications, for access to all detector related information. It can also be characterized as an in-memory representation of the complete structure of the detector.
  • Ideal Detector: the "blueprint" model of the detector which makes use of the symmetry in the detector design and ignores misalignment and other variations in the detector parts.
  • Realistic Detector: the model that describes realities of the detector construction such as misalignments and other variations, often in terms of corrections with the respect to the Ideal Detector.
  • Primary Constants: basic quantities on which other detector description parameter are based, e.g. basic detector length.
  • Derived Quantities: these are derived from the Primary Constants and typically used in the client application
  • Shape: a geometrical object. Can be Primitive (meaning it cannot be decomposed into other shapes within a given model) or Composite which is defined in terms of other shapes via some kind of operation (e.g. Boolean composition)
  • Material: description of the physical properties of a medium
  • Volume: an un-positioned shape that has been assigned a material
  • Placement: association of two volumes in a parent-child relationship, which is a geometrical transformation between their local reference frames
  • Geometrical Hierarchy: acyclic graph containing volumes nodes and placementsedges
  • Detector Element: a physical component of the detector, which can be mapped to a node of the Geometrical Hierarchy. It can comprise other elements.
  • Schema: domain concepts expressed as data types and their relationships.
  • Detector Description Language (DDL): a format or a language that provides the facility to define and maintain the description of detectors.
  • Client: in this context, a software object or an application that relies on the Detector Description Model (DDM) to provide the enirety of information about the detector necessary for accomplishing its task
  • Detector Description Services (DDS): a combined framework providing all of the detector data to the various software components in a given experiment. It will include the Detector Description Model (DDM) and other elements as detailed in the Requirements Section (section 4).

3. Usage Scenarios

Typical usage scenarios will include but are not limited to the following:
  • Detector Design and Maintenance: the design documents and other means of description of the current state of the detector must be translated into a certain detector description format (DDL).
  • Processing the Detector Description Data: this is a process in which a Detector Description Model is created based on persistent data which may exist in variety of formats. Note that this involves a variety of services (such as a database interface) and calculations (such as assigning vlaues to the Derived Quantities based on Primary Constants.
  • Version Management: creation of the correct Detector Description Model based on a persistent store containing the information about time dependence of the detector configuration and other relevant data. In the current STAR context that involves at the very least managing the various geometry tags (geometry-year etc)and the source file versioning.

4. Technical Requirements for the STAR Detector Description Services (DDS)

4.1 General Technical Requirements

Based on te above Glossary and Usage Scenarios we formulate the following Technical Requirements:
  1. The DDS shall include a Detector Description Model (DDM) as defined in the Glossary. This is necessary in order to provide all manner of detector-related data from a single source.

    The DDM shall provide facilities to describe the Ideal Detector as well as the Reaistic Detector.

    In itself it will not be based on the hierarchical geometry systems of either GEANT 3.21 or GEANT 4 as its functionality is necessarily wider. It is mandatory that the architecture of DDM would allow the generation of the GEANT 4 geometrical model of the detector. The creation of the GEANT 3.21 geometry is desirable however it is considered optional.

    A few other possibilities will be considered such as having the so-called Virtual Monte Carlo layer as it has been defined in the Alice experiment, with the possibility to interface both versions of GEANT. Alternatively, there are promising developments in the most recent Root geometry models. A decision about what external representation layer should be generated or exposed will be made at a later date.

    The DDM architecture and data content should also be sufficient for generation of geometrical models in the reconstruction software of the STAR detector subsystems. These individual models may or may not be based on the same underlying software.

  2. All of the detector subsystems shall be described in a common Detector Description Language (DDL). Given the trends in the industry, recent developments in the field of detector modeling and recommendations of experts, this language will use XML as the underlying platform.
  3. The DDS shall have a Persistent Storage System containing the data necessary to instantiate a DDM. This will not always mean creating new databases, but rather building interfaces to existing ones. This system shall contain time-dependent data on the detector's elements geometry, detector confiuration and material composition. It will necessarily feature a mapping mechanism for relational database and XML schemas.

    The system will not be restricted to the database form and will include elements such as XML files residing on a server and accessible via the network.

  4. The DDS shall have an Application Interface, or a group of interfaces, for the external the software clients to access the DDM.

    These may include

    • Conventional API whereby the DDS is provided as a library
    • Client-Server architecture, in which case it will be possible to query the DDS over the network, e.g. sending requests about about geometrical and material data in a format such as SOAP.

    The clients will include the simulation applications, reconstruction and visualisation tools. As an abstraction, the interaction of the clients with the DDS can be illustrated as follows:

  5. There will be Versioning and Configuration Management, which will include a transparent and user-friendly schema or a protocol allowing the construction of the DDM according to the time dependence of the detector configuration

The above requirements effectively define the composition of the system which can be itemized in a condensed form:
  • Detector Description Model (DDM)
  • Detector Description Language (DDL)
  • Persistent Storage System
  • Application Interface(s)
  • Versioning and Configuration Management

4.2 The XML-based components of the Detector Description Services

Based on the General Technical Requirements (previous subsection) we can now formulate how those will be met by the XML-based components of the DDS.

In the following we assume that the reader has basic knowledge of XML and XML schemas. Most the terminology largely follows that of the RTAG#7 and CMS groups. We will present guidelines for the schemas at this point, leaving these to be finalized at a later date.

4.2.1 DDL

Within the XML approach, the DDL denotes a XML schema adpoted for describing the detector geometry, i.e. tag names, attribute lists, structure of tags etc. A document conforming to this scheme is called an instance document of the schema.

XML tags to be included in DDL

While this is still very preliminary, we make a note of the following tags (or similar) that are likely to be used in DDL:
  • Materials:
    • ‹ElementaryMaterial›
    • ‹CompositeMaterial›
  • Shapes:
    • ‹Box›
    • ‹Trapezoid›
    • ‹Cone›
    • ...etc...
  • Components:
    • ‹Volume›: assigns material to a shape
    • ‹Placement›
    • ‹Translation›
    • ‹Rotation›
    • ‹AlgorithmicPositioning›
    • ...etc...
    The Placement defines the parent-child relationships in the hierarchy, whereas the Translation and Rotation are positioning components. These two tags would typicially be nested inside the Placement tag. The Algorithmic Positioning is briefly explained in the subsection on ADL.
  • Data:
    • ‹Parameter›
    • ‹...›

Partitioning and Cross Referencing

Based on the experience gained in STAR, as well as in other groups, we assume that the DDL document will be partitioned into sections containing the data belonging to the same category (e.g. material section, shape section etc). A hypothetical example of the material section could resemble the following:

    ‹CompositeMaterial name="G10" .../›
    ‹CompositeMaterial name="NOMEX" .../›
    ‹ElementaryMaterial name="Hydrogen" .../›
    ‹ .... /›
    ‹ .... /›
    ‹ .... /›

It will also be necessary to implement document cross referencing, whereby items defined in a particular section are referring to items in different sections located in same or different documents. This in turn mandates the use of namespaces in order to be able to uniquely identify items. As a simple example, if we have a file named material.xml, we could refer to a particular material in that file by using a tag:

‹CompositeMaterial name="materials:Air" .../›

4.2.2 CDL

In the simplest form, the complete detector description could be contained in a single DDL source file. This, of course, is not practical for our purposes as the STAR detector is quite complex. While this is not a necessary a part of the requirements, it is reasonable to assume that the DDL code will be stored in a potentially large number of files, possibly in different locations and in a different form (such as flat files and database objects, etc). As DDL descriptions of the detector components evolve, so do their respective schemas, therefore there must be a way to correctly retrieve the schema as well, so that validation can take place.

Combined with the requirement of Versioning and Configuration Management, this leads us to adopt a protocol for selecting a set of DDL documents according to the user's instruction (e.g. a specific timestamp). Implemented as a XML schema, such protocol is termed Configuration Description Language, or CDL.

The CDL document helps fulfill three important functions of the DDS:

  • DDL instance versioning (by specifying the location and version of DDL source code)
  • DDL retrieval (by specifying the method of acess to the DDL source code)
  • DDL validation (via retrival of the schema)

A hypothetical example of a CDL document could look like this:

        ‹File url=""›
         ‹File url=""/›
         ‹File url=""/›
    ‹ .... /›
    ‹ .... /›
    ‹ .... /›

4.2.3 ADL

Due to the symmetries often present in the detector design, it is sometimes desirable and/or necessary to use algorithms to build the geometrical hierarchy. within the DDL. Since DDM has been identified as a representaion layer accessible to a variety of clients, we can no longer rely on simple in-line code or a formula translation for a particular target language.

Instead, the interface to such algorithms is formalized in a schema under the name of Algorithm Description Language, or ADL.

The ADL schema will contain tags for Algorithm Definitions, as well as means for parameter binding between ADL and DDL tags within which the algorithms are used.

5. Conclusions

There are compelling reasons to migrate the detector description in the STAR experiment from a set of isolated tools and applications, to the Detector Description Services. It will logically include the "single source" geometry model which will be made available to client applications. The present document contains Technical Requirements for such system.

We are now conducting a feasibility study trying to determine which existing development projects and frameworks can be adopted by the STAR organization in order to leverage the significant technology investment made elsewhere.

Since the existing systems and/or design documents feature a large degree of commonality, which was also reflected in a paper sponsored by the LHC Grid Computing Computing Project, we identified common components such as Detector Description Language, Configuration Description Language and others. The general adoption of XML schemas as basis for these languages was noted and it is now assumed that STAR will use this technology as well.

The documents following this one will contain a discussion and specifications of XML schemas and other design detail.

Last updated by Maxim Potekhin on 04/24/2003