GeoModelXML Overview
Introduction¶
GeoModelXML
is a toolkit built on top of GeoModel
, which allows quick development of detector geometries using structured XML files containing the detector description, built up from a set of standard shapes and operations known about by the toolkit.
While this has limitations with respect to the programmatic approach used by GeoModel
itself, it allows a clear separation between data decribing the geometry, and code used to construct it from that data. While the programmatic approach to describing geometries - backed by the full capabilities of the C++ language - is unquestionably more powerful, the contraints imposed by GeoModelXML
can be beneficial for certain development models in terms of ensuring maintainability, and the data/code separation allows for clear versioning strategies.
Quick Start¶
To define a geometry using GeoModelXML
, a top-level file should be provided which gives an entry point to the geometry description, and contains several things which allow it to be interpreted by GeoModelXML
:
- The
DOCTYPE
should be set togeomodel
, providing the path to a valid.dtd
file (for example the latest version ofgeomodel.dtd
found inGeoModelXML\GeoModelXml\data
) defining the expected and allowed properties of the various elements. - While it is perfectly valid to write the full geometry within a single file (and in fact production geometries will be automatically combined into a single file before use) it can often be more readable to break up the geometry into multiple files. This can be done by defining a named
ENTITY
with a path to another.gmx
file to be included - A
geomodel
element should then be defined, which contains the actual geometry definition; this includes defining materials and shapes which can then be used to create logical volumes (logvols
) which can then be built up into largerlogvols
orassemblies
. - The entities defined can be included in the geometry by adding them with
&
in front of their name. NB that entities should be included in an appropriate order to avoid issues (e.g. entities defining parameters should be included before the parameters are used). - An
addbranch
element should then be defined which includes the geometry elements to build. These should be of typelogvol
orassembly
(or a reference thereto). Anything prior to theaddbranch
can be considered as defining possible contents of the geometry, since only things pulled in by the elements included inaddbranch
will finally be built as part of the geometry.
You can see an example below:
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE geomodel SYSTEM "PATH/TO/FILE/geomodel.dtd" [
<!ENTITY materialFile SYSTEM "PATH/TO/FILE/materials.gmx">
]>
<geomodel name="Hello World" version="1.0"
xmlns="http://www.nikhef.nl/%7Er29/gmx">
&materialFile
<shapes>
<tube name="ShapeOneMeterCylinder" rmin="200" rmax="500" zhalflength="500"/>
</shapes>
<addbranch>
<logvol name="DiamondCylinder" shape="ShapeOneMeterCylinder" material="Diamond"/>
</addbranch>
</geomodel>
<!-This is the content of materials.gmx->
<materials>
<element name="Carbon" shortname="C" Z="6" A="12.011" />
<material name="Diamond" density="3.515">
<elementref fraction="1.0" ref="Carbon"/>
</material>
</materials>
The way in which these elements can be defined, have shapes, materials, and transformations (to position them) defined, as well as how they can be combined and replicated will be covered in Building a geometry.
Once you have a valid geometry defined, you can use it as an input to the various GeoModel
applications such as gmcat
, gmclash
, gmex
, etc, via using the GMXPlugin
to process the input. The input file to use in the GMXPlugin
can be set one of two ways:
-
By default, the plugin will looks for a file called
gmx.xml
so you can e.g. simply create a symbolic link to your desired input file with this name. This works well if you have just a single file, or you are working in the directory where all your geometry files reside. However, this can cause problems with relative paths to entities you wish to include. Therefore, a further more robust option is to simply concatenate your multiple files into a single file, e.g:xmllint --noent --valid PATH/TO/FILE/MyTopFile.gmx > gmx.xml
-
Alternatively, you can define an environment variable
GMX_FILES
which provides the path to the file (or multiple files, if you have several top-level files defined e.g. for dirrferent detector components) to be read in, e.g:(also note potential issues with relative paths to entities)export GMX_FILES='PATH/TO/FILES/file1.gmx PATH/TO/FILES/file2.gmx'
Once you have your inputs defined, you can launch the applications with a command like:
install/bin/gmcat install/lib64/libGMXPlugin.so -o mySQLiteFile.db
Note that the GMXPlugin
is effectively a simple code wrapper around a call to gmx2geo
, within the general plugin framework defined by GeoVGeometryPlugin
, and so new plugins which implment slighty different access patterns and behaviour are easily added.
Good practise guidelines¶
As with any software framework, following sensible rules when developing in GeoModelXML
can help greatly in ensuring readability and maintainability for future, so that other developers can pick up your files and easily understand how they work, and how they could be modified as necessary. Some important rules to think about are:
- Avoid magic numbers: use of named variables (if sensibly named) will be far clearer - for example defining
<var name="bulkhead_z_pos" value="300" />
rather than simply placing a structure atz=300
- Use descriptive names: E.g.
bulkhead_z_pos
is better thanBHZ
- Use relative rather than absolute positions: This allows elements to be moved together rather by updating a single parameter, and thus avoiding either potential misplacements (and clashes) or needing to update multiple parameter coherently. E.g if we have:
Then it is preferable to place
<var name="bulkhead_z_pos" value="300" /> <var name="bulkhead_halflength_z" value="5" /> <var name="myStruct_halflength_z" value="5" />
myStruct
viathan simply by doing<var name="myStruct_z_pos" value="bulkhead_z_pos + bulkhead_halflength_z + myStruct_halflength_z" />
since in the former case changing either the dimensions of<var name="myStruct_z_pos" value="310" />
myStruct
or the position ofbulkhead
allow a consistent location ofmyStruct
relative tobulkhead
. - Components should ideally be built up in a modular way, such that individual components can be visualized and debugged individually: e.g. thought should be given so that it is straightforward to build a geometry containing a single instance of each fundamental structure on its own.
Previous documentation¶
The original GeoModelXML
manual, which has lots of useful information and details - but is in places rather specific to its initial version as part of the ATLAS experiment software - can be found here