STAR  Computing  Simulation  
Comparative analysis of GDML and AGDD


The purpose of this document is to evaluate potential benefits and drawbacks of two XML-based geometry description languages, GDML and AGDD. Let us define first the citeria for such comparison.

The XML-based format for geometry description can be used in two distinct contexts, (a) interchange format (b) primary source for geometry. We shall concern ourselves with the latter application. Further, there are two components in the geometry source,

  1. Logical structure of the composite object being described, such as defining the geometrical primitives used, and which often includes some sort of hierarchical arrangement of volumes
  2. Data content, which includes but is not limited to dimensions of the primitive volumes and positioning information.

We will address various implementations for the data component later, and for now concentrate on the first, structural component.

Let's briefly list the requirements for a successful schema:

  • A sufficient assortment of primitives (solids), allowing the user to describe complex geometries. In addition, a straightforward mapping to the solides that exist in the popular simulations engines such as Geant 3 (further referred to as G3), Geant 4 (G4) and the emerging Monte Carlo tools based on the Root geometry (TGeo), is preferred. It is sometimes called solids compatibility
  • Logical grouping of volumes: there must be away to create assemblies of volumes that can be positioned as a whole. This is pretty well aligned with the placement logic in G4 and TGeo, but is largely absent from G3 (apart from the obious hierarchical placement of child volumes inside mother, which is strictly speaking is not the same)
  • Self-contained, single source detector description, i.e. the XML geometry specification should be self contained and not involve significant pieces of structural information coded separately and in a different language.
  • Support for the inherent symmetry in the structure being described, i.e. being able to describe identical entities being positioned multiple times, while only describing the underlying volume once and positioning the copies implicitely, according to a rule. An example of this would be the positioning of the sectors of a barrel calorimeter. In an algorithmic language, this can be naturally done in a loop, however as XML is not an algorithmic language, more thought should be given to that matter when developing a schema.
  • Volume parametrization compatible with G3,4 and TGeo
  • Facilities that support arithmetic expressions
  • Adequate means to define materials
In the following, we will attempt to see how these items are covered in GDML and AGDD and whether either platform has an advantage in terms of serving as the basis of the new detector description for STAR. We will rely on code samples as opposed to schemas to clarify the points being made.

History and Applications of GDML and AGDD


AGDD project originated in the Atlas Collaboration with the specific purpose of describing the complex geometry of the Atlas detector. It was started in the late 90s and was effectively shut down, albeit without a formal announcement, in the year 2002. Still, it has a small but steady user base among the team forking on the Atlas muon system, as it provides an excellent visualization tool via Persint.

ADGG had undergone a significant evolution. At first, the difficult problem of emplying algorithmic placement of volumes was tackled by having the so-called "compact" description, whereby the XML source by itself was associated, via a system of tags, with bits of C++ that implemented the needed algorithms. Needless to say, that immediately reduced the portability and maintenance appeal of the XML approach. In one of the later versions, v6, this was superceded by introducing prepackaged XML tags that did the algorithmic positioning.


GDML is a spinoff of the Geant 4 project. It would appear that initially it was meant as a detector description tool, however it was later fctored out of the G4 framework into a separate project, and of late ir oriented towards an exchange format rather than a primary source. We are not aware of actual users of that language.

3. Clients and Applications

For GDML, there is a G4 client whereby a G4 geometry can be created from a GDML source. In addition, G4 should be able to produce a GDML dump, and so should the Root geometry system. These two developments are work in progress.

AGDD has been used to create the G4 geometry for major components of the Atlas detector. We suspect though that the G4 experimentation was done with the "compact" version of AGDD which is not suitable for us. At the time of this writing it has two graphics clients, graXML and Persint.

Solids, Assembly and Booleans

Let's consider the solids compatibility among the GDML, AGDD, G3 and G4. For sake of brevity, the following description covers only volume types that are immediatly useful in the contruction of a realistic detector, and we skip exotic things like hyperbolic shapes etc.

Box + + + +
Sphere + + +
Tube + + + +
Cone + + + +
Para + + + +
Trd + + + +
Trap + + + +
Polycone + + +
Polyhedra (Polygon) + + +
Torus + + +
Boolean+ +/−+
Assembly+ +/−+

Solids in GDML can be of the type BooleanSolidType: union, subtraction, intersection. This maps pretty well onto G4. AGDD currently supports this function in only one type of parser written for it (Persint), although it has been commented by one former developer that it can be added to others as needed.

Assembly type describes a logical grouping of objects that can be manipulated and position as a single object. Below is a snippet of code demonstrating how this is done in AGDD (assembly is termed "composition" in this case):

<composition name="cube">
    <mposZ volume="xyplane" ncopy="3" dZ="200" /> </composition>

<composition name="TEST">
    <posXYZ volume="cylinder1" X_Y_Z="0; 0; 1500" />
    <posXYZ volume="cylinder"  X_Y_Z="0; 0;  500" />
    <posXYZ volume="cube"      X_Y_Z="0; 0; -500" />

Note the way these "compositions" are formed - either through multiple positioning of a volume, or through a trivial aggomeration of different volumes.

In addition, AGDD has a composition type "Stack", which allows for a more detailed description of objects stacked on top of each other.

Assembly volume type is also present in GDML, but the existing documentation is incomplete and there was not suitable code sample to present here.

Volume Positioning

AGDD features a variety of positioning operators. For example, consider this line:

<posXYZ volume="trd" X_Y_Z="200; 200; 0" rot="0; 0; 0" S="0" unit_length="mm" unit_angle="deg" /> 
Obviously, the translation and rotation can be specified simultaneously. GDML has a comparable positioning system, which can be found in a code sample. A translation can be defined as follows:
<position name="shiftbyx" x="20" />
It is not clear at this point if the translation and rotations can only be referenced in GDML and not inlined as illustrated in the AGDD example.

Perhaps the most important feature where the two languages diverge is the area of algorithmic positioning operators.

In the AGDD example above, the mposZ tag represents a multiple positioning operator that places three copies of the underlying volume, at particular locations separated by a step. Likewise, there are predefined operators to position copies of objects in angular coordinates. In addition, the user can still resort to placing explicit iterators in the XML code, and using arrays of parameter to feed the data to the construction process. The full power of these features is nicely illustrated in the test suite developed specifically for the AGDD parser.

GDML does not have these feature ans there are no definite plans to implement it in foreseeable future. A such, that is a single most important obstacle for the adoption of that format.

Divisions, Volume Parametrization and Math Facilities

At the time of this writing, we don't have information on whether either of the languages has implemented divisions implemented, but studying the publicly available documentation indicates that's not the case.

A related issue is one of parametrized volumes, and it is known that there are plans to implement those in GDML in near future. Here's a prototype of GDML code that will be able to do it:

 <volume name="Tracker" >
   <materialref ref="Air" />
   <solidref ref="tracker" />
   <paramvol ncopies="5" >
    <volumeref ref="Chamber" />
     <parameters number="1" >
      <position name="copy1pos" x="0" y="0" z="-700" />
      <box_dimensions x="672" y="672" z="100" />
     <parameters number="2" >
      <position name="copy2pos" x="0" y="0" z="100" />
      <box_dimensions x="1104" y="1104" z="100" />
     <parameters number="3" >
      <position name="copy3pos" x="0" y="0" z="900" />
      <box_dimensions x="1536" y="1536" z="100" />
     <parameters number="4" >
      <position name="copy4pos" x="0" y="0" z="1700" />
      <box_dimensions x="1968" y="1968" z="100" />
     <parameters number="5" >
      <position name="copy5pos" x="0" y="0" z="2500" />
      <box_dimensions x="2400" y="2400" z="100" />

That doesn't look like a really efficient piece of code. Instead of grouping parameters in an array and having some sort of iterator run over them, the developer is forced to manually plug in the same volume reference the required number of times. The absence of parameter grouping significantly reduces the code's readability.

In case of AGDD, there is no parametrized volumes per se. However, the presence of parameter arrays and iterators affords one effectively the same functionality, and arguably in a better manner:

 <array name="zs" values="
     -1107;   -1085.4; -1056.6; -1027.8; -999;    -970.2;  -941.4;  -912.6;
      -883.8;  -855;    -826.2;  -797.4; -768.6;  -739.8;  -711;    -682.2;
      -661.5;  -648;    -634.5;  -621;   -607.5;  -594;    -580.5;  -567;
      -552.6;  -538.2;  -523.8;  -509.4; -495;    -480.6;  -465.3;  -450;
      -434.7;  -419.4;  -404.1;  -388.8; -373.5;  -357.3;  -341.1;  -324.9;
      -308.7;  -292.5;  -276.3;  -259.2; -242.1;  -225.9;  -208.8;  -190.8;
      -173.7;  -156.6;  -138.6;  -120.6; -102.6;  -84.6;   -66.6;   -48.6;
       -30.6;   -11.7;     7.2;    26.1;   45;     63.9;    82.8;   101.7;
       120.6;   139.5;   158.4;   177.3;  197.1;  216;     234.9;   254.7;
       273.6;   292.5;   312.3;   332.1;  351;    369.9;   389.7;   409.5;
       429.3;   448.2;   467.1;   486.9;  506.7;  526.5;   546.3;   566.1;
       586.8;   607.5;   628.2;   648.9;  669.6;  691.2;   712.8;   734.4;
       756;     777.6;   800.1;   822.6;  845.1;  868.5;   891.9;   914.4;
       937.8;   962.1;   985.5;  1008.9; 1033.2; 1058.4;  1082.7;  1103.4"/>
   <var name="yb" value="0.3"/>
   <var name="yt" value="0.3"/>
   <trd name="MU_TM1_T1_L1_Wiregang"  material="Tungsten" Xmp_Ymp_Z="xb; xt; yb; yt; h" /> 

<composition name="MU_TM1_T1_L1_Wireplane">
     <foreach index="iz" loops="112" when="iz < 10 || iz > 100">
       <posXYZ X_Y_Z="0; 0; zs[iz]">
         <var name="xb" value="xb_m * (iz+1) + xb_b"/>
         <var name="xt" value="xt_m * (iz+1) + xt_b"/>
         <var name="h"  value="hs[iz]"/>
         <volume name="MU_TM1_T1_L1_Wiregang"/>

We argue that the combination of the multiple positioning operators and iterators can serve as a viable tool to describe parametrized volumes.

Both languages support basic expressions and usage of variables. Reportedly, the iterators and formula expansion in AGDD have been implemented in XSLT, which makes it a rather rigorous XML implementation, and less dependent on the target platform.


According to the available documentation, AGDD allows the developer to define materials based on their A, Z and density much like it was done in G3. On the other hand, AGDD goes one step further and enables one to combine complex materials as opposed to elements. This is a welcome feature.

Other aspects of GDML and AGDD

Let's condider now the "utilities" offered by the two languages, outside of the purely geometrical area of functionality:

Functionality GDML AGDD v1-5 AGDD v6
Constants + + +
Simple arithmetic expressions + + +
Expressions involving functions + +
Iterators implemented + +
Arrays of parameters + +
Export of pure XML for visualization + +
XML tags to describe compact objects + +
Crucial content location in the code XML C++ XML
Cominations of complex materials +
Database import

The third column in the table above describes the latest version of AGDD, as described above in the "history" section. In this version, the XML indeed served as a single source for the geometry description. Prior to that, the so-called "compact" description of objects required a separate piece of C++ code to handle the algorithnmic part. As mentioned above, this has been done away with.

As the last row of the table indicates, none of platforms takes care of a proper relational database interface. That topic will be discussed separately.

Developers' Reports and Impressions

There is anecdotal evidence (probably biased as it comes from the former AGDD team) that AGDD was proven as a viable tool when describing a realistic and complex systems. As GDML was never used in this context, there is no counterargument.

Personal experience of the author (reading the geometry code in both langiages) indicates that the claim might be true, as AGDD features much better readability. This should be evident from the pieces of code included in this write-up.

There is a claim from the same people that writing a parser for GDML is simpler (which might have to do with the less rich feature set of that language, in our opinion).


It would appear that AGDD as a platform is superior (in practical and not theoretical terms) to GDML in three regards:
  • Its implementation of multiple positioning operators
  • Arrays and iterators
  • Better readability

AGDD has the disadvantage of not being developed anymore. However, last but not least, GDML positions itself as an exchange format, meaning that the features needed to make it the primary source are unlikely to be implemented at all, or will receive poor support, which makes its adoption problematic.

  Page created by Maxim Potekhin. Last edit on 11/18/2004