-
Notifications
You must be signed in to change notification settings - Fork 4
/
HDDS-1_1.xsd
2674 lines (2255 loc) · 97.5 KB
/
HDDS-1_1.xsd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.gluex.org/hdds"
xmlns="http://www.gluex.org/hdds"
elementFormDefault="qualified">
<!-- HDDS: HALL D Geometric Detector Specification
=============================================
Version: 1.1
Date : September 6, 2013
This xml schema defines the structure and syntax for
Hall D Geometric Detector Specification xml files.
Documentation of the elements is given below.
The basic structure of this document was borrowed
from the AGGD project of the Atlas collaboration.
version 1.0 - original release
version 1.1 - added the geometry_layer[=0] attribute to the volume
positioning tags to support placement of volumes in
secondary layers of the geometry. Objects in the default
layer 0 of the geometry are on top, with subsequent layers
placed sequentially underneath, such that any object in a
lower layer supersedes an object in a higher-numbered layer
that overlaps with it. See section 1.5.2 for details.
1) General structure of a detector description
===========================================
o The HDDS element is the main container where all detector description
information is maintained and managed.
o Currently one may find within the HDDS element :
o materials : definition of a set of materials
o section : definition of a section (main division of the detector)
o region : definition of tracking properties (eg. magnetic fields)
o The schema provides a main version id. This corresponds to a constraint
(named version). All "materials", "sections", "regions" and the
overall "HDDS" element must individually specify in their attributes
a matching version value. (eg. version="v4")
o General rule for angle definition for all XML statements:
a) Right handed coordinate system is used.
Explicitly this means that:
Z-axis angle rotation should be positive when rotation is
made in the direction from X to Y in the short way
Y-axis angle rotation should be positive when rotation is
made in the direction from Z to X in the short way
X-axis angle rotation should be positive when rotation is
made in the direction from Y to Z in the short way
b) All angles corresponds to "active" rotation, i.e. the object is rotated
in the fixed coordinate system
(NOT "passive" rotation when the axis are rotated and the object
is fixed)
1.1) Materials
===============
The materials element collects together all of the materials information
in the document under a single container. Attributes of materials are :
version : version of the materials description
date : last modification date
author : last modification author
specification : version of the materials tag schema
o Materials can be elements or composites.
o Elements are identified using a long name. Attributes are
symbol : the conventional symbol name
z : mean number of protons
a : atomic weight
o Composites are identified using a long name and provide a density (g/ml).
They are made of a set of addmaterial elements, each with attributes
material : an IDREF to an already defined material or element
fractionmass : a percentage of this material in the composite
(use for both materials and elements).
natoms : the number of atoms of this element in the composite
(elements only). Use either natoms or fractionmass.
o Contents of elements and composites are a sequence of parameters with
names taken from the following list. Any element that is valid within
a parameter block (see section 1.3) is allowed.
density : density (g/cm^3)
radlen : radiation length (g/cm^2)
collen : nuclear collision length (g/cm^2)
abslen : nuclear interaction length (g/cm^2)
dedx : minimum-ionization dE/dx (MeV/g/cm^2)
o Elements and composites may have optical properties associated with
them which indicate how optical photons (ie. visible light) interacts
with the material. Optical properties are enclosed within the
optical_properties container element. They are specified as a list of
specify elements. If optical_properties is present, it must enclose at
least two specify elements. The arguments to specify are as follows.
E : photon energy (eV, required)
refindex : refractive index (required for dielectrics, default 0)
abslen : absorption length (cm, dielectrics only, default 0)
effic : detection efficiency (meaning is user defined, default 0)
reflect : reflection coefficient (metals only, default 0)
smooth : smoothness parameter (1=perfect, 0=rough, default 1)
1.2) Sections
==============
A section forms the basic sub-division of the entire detector. It
holds the implementation of the geometry for this particular piece
of detector. A section is primarily made of "volume" elements but
also may receive a set of named and typed parameter blocks (used to specify
constants).
Attributes of section are :
name : (short) unique name to identify the section
version : internal version of the section
date : last modification date
author : last modification author
top_volume : envelope volume corresponding to the section
specification : version of the section tag schema
1.3) Parameters
===============
Parameters are named and typed values. Possible types are :
int : an int value
real : a float value
string : a text string
reference : an IDREF to a parameter block.
int_array : an array of values
real_array : an array of values
string_vector : a vector of text strings
reference_vector : a vector of IDREFs to parameter blocks.
Parameters must be defined within named "parameter blocks" which in
turn can be referenced by any volume. Parameter blocks are defined
within sections.
All scalar parameter get their value in the attribute named "value";
array parameters get their array of values within the single
attribute named "values"; vector parameters get their values as a
set of member elements.
It is required to specify a semantics for the values using a "unit"
attribute (available for both scalar and arrays). Current possible
units are:
m cm mm for lengths
deg rad mrad for angles
percent for fractions
or simply
none
some examples are:
<real name="chamber_width" value="12.56" unit="mm" />
<string name="chamber_type" value="RPC" />
<real_array name="ratios" unit="percent" values="10 15 27 33" />
<string_vector name="authors">
<string_data value="Christian Arnault"/>
<string_data value="Stan Bentvelsen"/>
<string_data value="Jean-Francois Laporte"/>
<string_data value="Steven Goldfarb"/>
<string_data value="Marc Virchaux"/>
<string_data value="Christopher Lester"/>
</string_vector>
1.4) Volumes
============
The 'volume' is a generic name for a geometric object. Effective
volume are organized as a hierarchy of types.
1) solid volume (have a "material" and may be "sensitive"))
|-> box 3-rectangle
|-> tubs tube section
|-> eltu elliptical tube
|-> trd trapezoid
|-> pcon poly-cone (sequence of joined cons)
|-> pgon polyhedron (sequence of joined polygons)
|-> cons cone section
+-> sphere sphere (or a section thereof)
2) composition (build a logical composition)
3) boolean volume
|-> union
|-> intersection
+-> subtraction
4) stack (pile up other volumes)
|-> stackX
|-> stackY
+-> stackZ
All kinds of volumes have at least the following attribute:
name : their identifier
parameters : an IDREF to a parameter block.
Parameter blocks are meant to describe non-geometrical information
or geometrical details that cannot or should not be described using
the generic model.
For example, the inner-structure of the SCT crystals contain
information about the strip-pitch, etc. The use and content of these
parameters is left free.
A volume in itself is not positioned. Rather, compositions, boolean
volumes or stacks combine "position" elements whose role is to
position a volume (see paragraph on positions)
1.4.1) Solid volume:
====================
A basic geometry unit; Specialized types provide for specific shapes
(boxes, tube sections, trapezoids and cone sections). A solid
references a material, and may be declared as "sensitive" (which
opens the not-yet-implemented capability of producing hits).
1.4.1.1) Box (element tag "box") :
A Box is a cuboid of given total lengths X,Y and Z. The Box is
centered on the origin with sides parallel to the x/y/z axes.
NB: Note the factor two difference in the dimensions wrt the 'Geant4 - Box'
Its dimensions are given by :
X_Y_Z="X Y Z"
1.4.1.2) Trapezoid (element tag "trd") :
A Trd is a trapezoid with the x and y dimensions varying along z. Its
dimensions are given by
Xmp_Ymp_Z="Xm Xp Ym Yp Z"
inclination="alph_xz alph_yz"
with:
Xm Length along x at the surface positioned at -Z/2
Xp Length along x at the surface positioned at +Z/2
Ym Length along y at the surface positioned at -Z/2
Yp Length along y at the surface positioned at +Z/2
Z Length along z axis
alph_xz Inclination angle in the x-z plane
alph_yz Inclination angle in the y-z plane
NB: Note the factor two difference in the dimensions wrt the 'Geant4 - trd'
1.4.1.3) Tube segment (element tag "tubs")
A tube or tube segment with curved sides parallel to the z-axis.
The tube has a specified total-length along the z axis, about which
it is centered, and a given minimum and maximum radius. A minimum
radius of 0 signifies a filled tube / cylinder. The tube segment is
specified by starting and delta angles for phi, with 0 being the +x
axis, PI/2 the +y axis. A delta angle of 2PI signifies a complete,
unsegmented tube/cylinder. The origin is centered in the middle of
the tube.
Its dimensions are given by
Rio_Z="Ri Ro Z"
profile="PhiS dPhi" (defaulted to "0 360")
with
Ri Inner radius
Ro Outer radius
Z Total length in Z
PhiS Starting angle phi
dPhi Delta angle phi
NB: Note the factor two difference in the length wrt the 'Geant4 - tubs'
1.4.1.4) Elliptical cross-section tube (element tag "eltu")
It has three parameters:
Rxy_Z="Ri Ro Z"
with
Rx Semi-axis of the ellipse along x
Ry Semi-axis of the ellipse along y
Z Half-length in z
1.4.1.5) Cone segment (element tag "cons")
A cons is, in the general case, a Phi segment of a cone, with length
Z, inner and outer radii specified at -Z/2 and +Z/2. The Phi segment
is described by a starting Phi angle, and the +dPhi delta angle for
the shape.
Its dimensions are given by
Rio1_Rio2_Z="Ri1 Ro1 Ri2 Ro2 Z"
profile="PhiS dPhi" (defaulted to "0 360")
with :
Ri1 inside radius at -Z/2
Ri2 inside radius at +Z/2
Ro1 outside radius at -Z/2
Ro2 outside radius at +Z/2
Z half length in z
PhiS Starting angle phi
dPhi Delta angle phi
1.4.1.6) Polycone segment (element tag "pcon" )
A pcon is, in the general case, a Phi segment of a polycone. The
polycone is build from a series of consecutive cones.
The phi-segment is given by the attribute
profile="PhiS dPhi" (defaulted to "0 360")
with :
PhiS Starting angle phi
dPhi Delta angle phi
The edges of the polycone are given by a series of XML element 'polyplane',
which are children of 'pcon'. The 'polyplane' dimensions are given
by the attribute:
Rio_Z="Ri Ro Z"
with :
Ri inside radius at point Z
Ro outside radius at point Z
Z position z
1.4.1.7) Polyhedron solid (element tag "pgon" )
A pgon is similar to the polycone (element tag "pcon") except that
its boundaries are planar segments instead of conical ones.
The phi-segmentation is given by the attribute
profile="PhiS dPhi" (defaulted to "0 360")
with :
PhiS Starting angle phi
dPhi Delta angle phi
and by the number of phi-segments specified using the attribute
segments="NNN" (no default)
with :
NNN number of (equal) phi segments
The edges of the polyhedron are given by a series of XML element 'polyplane',
which are children of 'pgon'. The 'polyplane' dimensions are given
by the attribute:
Rio_Z="Ri Ro Z"
with :
Ri inside radius at point Z
Ro outside radius at point Z
Z position z
where "radius" of a planar boundary is defined to be the perpendicular
distance from the boundary to the z-axis.
1.4.1.8) Sphere segment (element tag "sphere" )
A sphere segment is a section of a sphere that is delimited by boundaries
of fixed radius, polar angle and azimuthal angle.
The bounds of the sphere segment are given in three compound attributes:
Rio="Ri Ro"
polar_bounds="Theta0 Theta1" (defaulted to "0 180")
profile="PhiS dPhi" (defaulted to "0 360")
with :
Ri radius of inner surface
Ro radius of outer surface
Theta0 lower bound in theta
Theta1 upper bound in theta
PhiS Starting angle phi
dPhi Delta angle phi
1.4.2) Composition
==================
Construct a new volume which consists of positioning several volumes
(defined elsewhere in HDDS) placed at various places w.r.t. the
reference frame of this new entity.
The positioning of volumes proceeds via position elements:
posXYZ
posRPhiZ
mposR
mposPhi
mposX
mposY
mposZ
Volume are positioned according to the coordinates specified in the
above positioning elements w.r.t. the implicit coordinate system of
the composition (which defines the reference)..
In general, there is a priori no defined volume corresponding to
this entity i.e. it is a juxtaposition of volumes. Its envelope has
to be computed from the juxtaposed volumes. However one can force
this envelope to be one specific (elsewhere defined) volume. Then
all positioned volume will be placed into this "envelope" volume.
1.4.3) Stacks
=============
Constructs a new volume which consists of several other volumes
piled up along one given axis.
Stacks may be defined along
the X axis (element tag "stackX")
the Y axis (element tag "stackY")
the Z axis (element tag "stackZ")
The positioning of volumes proceeds via elements:
axisPos : a single volume is added to the pile. A
rotation (one angle) along the same axis as well as
a transverse displacement may also be specified.
axisMPos : a multiple position of a given volume. A
rotation (one angle) along the same axis as well as
a transverse displacement (both applicable to all copies)
may also be specified.
Offsets along the stack axis can be specified either using
a shift : distance between the coordinate origin of the stack and the
coordinate origin of the first stacked volume, or between
the coordinate origin of the previously stacked volume and
the coordinate origin of the first stacked volume.
a gap : distance between the coordinate origin of the stack and the
lowest dimension of the first stacked volume, or between the
highest dimension of the previously stacked volume and the
lowest dimension of the first stacked volume.
Coordinate system: The coordinate system of the stack can be
defined in two ways, that are selected by
the attribute 'origin'.
origin="atStart" (default)
The coordinate-system of the stack is defined before
any volumes are positioned in the stack, and
it is fixed (i.e. independent of the contents
of the stack).
For example, in the absence of the gap0 or
shift0 attributes, the origin of the
coordinate system coincides with the edge of
the stack.
origin="atCenter" After the stack is built an additional shift
along the direction axis is applied to the
coordinate system of the stack, such that it
lies in the center of the stack (including
gaps). The 'center' is defined as the
geometric middle between two planes
perpendicular to the direction axis, with the
planes just touching the extreme edges of the
stack (which include gaps). Note that the
coordinate system always lies on the direction
axis, and does not change in the perpendicular
direction.
To avoid ambiguities when gap0 is smaller than zero:
Define point A at the "stack start" (from which gap0 is
measured), and define the last physical part of the
stack as B. The center of the stack is then defined at
position (A+B)/2. In the simple case of zero gap0
and shift0, the coordinate system is shifted to
the center of the stack of volumes.
1.4.4) Boolean volumes (union, intersection and subtraction)
============================================================
NOTE: Boolean volumes are not currently supported by HDFast or HDGeant.
union : Union of several volumes
intersection : Intersection of several volumes
subtraction : Subtraction of several volumes. All the volumes
(but the first) are subtracted from the first
The positioning of volumes within boolean operation can only be
done via single positioners, say:
posXYZ
posRPhiZ
Note that it is required that the materials of the boolean volumes
are identical. This is however not checked (or forced) within the
XML syntax, and is left to the responsibility of the user (and the
application).
1.5) Positioning of volumes
===========================
Each volume (Solid volumes, compositions, unions, etc) are
positioned relatively to other volumes using the "position"
elements. A given volume may referenced (through its name) in
several position operations.
Position operators are organized as a hierarchy of types as follows
Single positions
| posXYZ
| posRPhiZ
Multiple positions
| mposR
| mposPhi
| mposX
| mposY
| mposZ
Axis positions
| axisPos
| axisMPos
o Single positions can be used in compositions or boolean volumes
o Multiple positions can only be used in compositions
o Axis positions can only be used in stacks
1.5.1) Common properties
All positioning operators share some properties :
attributes :
volume : the volume they are positioning.
unit_length : the units used to specify the coordinates.
unit_angle : the units used to specify rotation angles.
geometry_layer : the geometry layer (see section 1.5.2 below)
in which to place the volume.
member elements :
identifiers : a set of identifier specifications (see paragraph on
identifiers for details)
Single positions and Multiple positions may provide a local rotation
(specified as three angles around X, Y and Z)
The rotation around X,Y,Z axis is defined by rot="a b c"
the X rotation of a angle is done first
the Y rotation of b angle is done second
the Z rotation of c angle is done last.
1.5.1.1) posXYZ
posXYZ: single positioning of a 'generic' volume, in cartesian
coordinates. The coordinate system is implicitly defined by
the posXYZ (take a coordinate system, and place the volume in
it with a given set of coordinates and rotations)
specific attributes:
X_Y_Z : X, Y and Z coordinates of the volume inside the
coordinate system
The volume is rotated before it is placed.
1.5.1.2) posRPhiZ
posRPhiZ: single positioning of a 'generic' volume, in cylindrical
coordinates.
specific attributes:
R_Phi_Z : Radius, Phi (wrt the X-axis) and Z of the volume
(default is 0 0 0).
S : Move along the "ortho-radial" coordinate S
before placing the object (default is 0).
impliedRot : (true | false) rotation of volumes to point to center
coordinate system (true) or not (false).
The volume is rotated before it is placed.
1.5.1.3) mposPhi
mposPhi: multiple positioning of a 'generic' volume, around the
Z-axis at a given radius R, with incremental values of phi.
specific attributes:
ncopy : Number of volumes to be placed
Phi0 : Start value of phi (wrt the x-axis).
dPhi : If given: incremental value of phi
If absent: incremental value of phi is set
to 2*PI/ncopy
R_Z : Radius R and Z-coordinate
S : Move along the "ortho-radial" coordinate S
before placing the objects (default is 0).
impliedRot : (true | false) rotation of volumes to point to center
coordinate system (true) or not (false).
1.5.1.4) mposR/X/Y/Z
mposR, mposX, mposY, mposZ: multiple positioning of volumes along
the R, X, Y, Z directions respectively.
mposR: positioning along the radius R with fixed (Z,phi).
mposX: positioning along the X-axis with fixed (Y,Z).
mposY: positioning along the Y-axis with fixed (X,Z).
mposZ: positioning along the Z-axis with fixed (R,phi) or (X,Y).
ncopy : Number of volumes to be placed
R0,X0,Y0,Z0: Starting values in R,X,Y,Z
dR,dX,dY,dZ: Increment values in R,X,Y,Z
Z_Phi : transverse displacement for mposR
R_Phi : transverse displacement for mposZ
X_Y : transverse displacement for mposZ (alternate for R_Phi)
Y_Z : transverse displacement for mposX
Z_X : transverse displacement for mposY
S : Move along the "ortho-radial" coordinate S
before placing the objects.
Note that the origin of the coordinate system is implicitly
defined in the 'transverse' direction by the Z_Phi, R_phi, X_Y, Y_Z or Z_X
attributes. In the positioning-direction it is defined by the
attributes R0, X0, Y0 or Z0.
1.5.2) Geometry layers [new in release 1.1]
Some geometries, which are readily described in terms of elementary solids,
become very complicated to implement in hdds when overlaps between any two
members of the same containing object are forbidden. This was the case for
hdds geometries in release 1.0, but in 1.1 a new feature was introduced that
can accommodate certain kinds of overlaps within the geometry hierarchy.
Daughter solids which extend outside the bounds of their container are
still strictly forbidden, but it is now possible to place daughters within
a mother volume such that they overlap with each other, provided that they
are placed in different "layers". This feature was inspired by the
"layered mass geometry" that was introduced in geant4.9.5, and follows
those semantics closely, except that the layer priorities are reversed.
The default layer 0 has top priority in hdds, layer 1 second, and so on.
Geometries conforming to hdds version 1.0 are still valid in version 1.1,
all objects simply being placed in geometry layer 0.
In a layered geometry, the interior of certain volumes are treated as if
they were transparent layers in a CAD system, such that objects defined
in underlying layers "show through". The layer on which an object appears
is determined at placement time. Any given object can appear on different
layers in different parts of the geometry if it is placed multiple times.
The layer on which an object is placed is defined to be 0 by default, but
can be set to any higher integer (1,2,...) by the explicit use of the
geometry_layer="int" attribute in the placement tag. Objects placed on
higher-indexed layers are superseded by objects in lower-indexed layers
anywhere that they overlap. Objects placed within any given layer must
not overlap. Placement of any object on a non-default layer automatically
triggers the creation of an image of its mother on the same layer, and so
on all the way up the hierarchy to the root. This way, coordinates for
placement are the same no matter which layer is specified.
Once an object is placed on a non-default layer, any objects placed inside
it also inherit that base layer and will automatically be placed on that
layer or higher in the global geometry. For example, if volume X is on
layer 5, and then volume U and V are placed inside it with hdds attributes
geometry_layer="2" and geometry_layer="1", then this causes new copies of
U and V to be constructed on layers 7 and 6, respectively. Placing a third
daughter volume W inside X in hdds without any geometry_layer attribute is
the same as specifying geometry_layer="0", and results in a new copy of W
being constructed inside W on layer 5 in the global geometry. This scheme
guards against accidental collisions when complex objects (volumes with
many layers of nested volumes) are placed on non-default layers.
1.6) Regions
==============
A region is a set of properties relevant to particle tracking that are
shared by a number of detector elements. The most common use of regions
is to specify the magnetic field. The detector elements that belong to
a region are usually associated by spatial proximity but may be widely
separated in the geometry tree. Regions have been introduced because of
this, to allow an arbitrary subset of the volumes in a geometry heirarchy
to share a common set of tracking properties without requiring that they
have a common ancestor that also belongs to the region. Once a volume
is assigned to a region, all of its descendents in the geometry tree
inherit those properties as their default values, with nearer ancestors
taking precedence over more remote ones. These inherited defaults can
be overridden in a child by joining a region of its own where they are
explicitly assigned. The top node in the geometry tree belongs to the
implicit default region, which has no magnetic field and global default
values for all tracking properties. Any given volume may itself belong
to at most one region.
The association of a volume to a region occurs in the place where the
volume is declared, i.e. "box", "tube", etc. This is done using the
<apply> tag that defines how the region coordinate system is related
to the local coordinate system of the new volume. This is the reverse
of what one might expect on the basis that regions contain volumes and
not vice versa, but doing it this way has advantages for being able to
use region specifications more than once, eg. in the case of having
multiple identical magnets in a beam line. For details on the syntax
for assigning a volume to a region, see section 1.6.4 below.
A region may be assigned a uniform magnetic field, or a an arbitrary field
may be specified in terms of a field map. A field map is a list of magnetic
field values (three components) sampled on a regular three-dimensional grid.
The map data are stored in an external file and loaded into the simulation
at run time; only the field map metadata are stored in the hdds document.
At run time the simulation program reads the map data from the file and
uses the hdds metadata information to determine how to interpolate the
table to compute values of the field at real space points.
The top level of the regions description is the "regions" tag. Its
attributes are similar to those of the "materials" and "section" tags:
version : version of the region description
date : last modification date
author : last modification author
specification : version of the region tag schema
1.6.1) Region elements
=======================
The contents of the regions tag are individual region elements, each of
which describes a single contiguous region of space containing a magnetic
field and/or some other set of tracking properties. The region tag has
the following attributes:
name : a short descriptive ID of this field region
modifies : name of another region to provide default values
comment : a more verbose description
The region name must be a NMTOKEN type (begin with a letter, contain
alphanumeric characters and underscores, and contain no spaces) like
material names and identifier names so that it can be referenced by
volumes through the region="XXX" attribute. The properties of a region
are specified using the content elements described in the next section.
Any properties that are not specified obtain the default values, either
those of the modifies="REGION", if given, or the default region if not.
This attribute was introduced to make it simple to create copies of a
region which share a common set of properties, but must have private
values for a subset of their properties. Creating an empty region
element with only a modifies="REGION" argument effectively creates an
alias for "REGION".
1.6.2) Region contents: Bfield descriptions
============================================
It is foreseen that the region element may be expanded in the future to
contain a more general description of tracking properties. At present,
only magnetic field specifiers are defined. Only properties that are
explicitly declared within the region definition are modified from their
defaults. Magnetic fields are described using either a uniformBfield,
a computedBfield, or a mappedBfield element. A region that has no
magnetic field is defined using the noBfield tag. Assigning a region
with noBfield to a volume results in the same tracking behavior as if
the volume had no region assignment, i.e. belongs to the default region.
The noBfield specifier has been introduced to enable volumes that inherit
a region with a magnetic field from an ancestor to override that behavior
by specifying their own region with noBfield. The noBfield tag has no
attributes.
The uniformBfield tag supports the following attributes.
Bx_By_Bz : space-separated list of the three Cartesian
components of the uniform magnetic field.
unit : units for specifying magnetic field, eg. kG, T
(default is kG).
The computedBfield tag supports the following attributes.
function : name of the global function that computes the
magnetic field at a point r. The syntax of this
string is user-defined, and may be a global function
call in some language, a lookup key for a database,
or some keyword-based selector. In any case, the
language-specific interpreter needs to translate
this string into the function or method invocation
that is appropriate in that context.
maxBfield : maximum magnitude of the magnetic field within the
range specified by the map
unit : units for the magnetic field values returned by the
function, eg. kG, T (default is kG).
The mappedBfield element has the following attributes:
map : URL pointing to where the field map values are found.
encoding : indicates how the values are stored, eg. utf-8 for
a plain-text file, base-64, and so on.
maxBfield : maximum magnitude of the magnetic field within the
range specified by the map
unit : units for specifying magnetic field, eg. kG, T
(default is kG).
The mappedBfield requires additional information that explain how to
interpret the list of field values stored in the map file in terms of
real space points. The map file itself contains only a list of floating-
point triplets (Bx By Bz). The information regarding their ordering and
coordinate assignments is provided by the "grid" element. Each
mappedBfield element must contain at least one grid element. If more
than one grid element appears within a map element, the same map data are
reused by associating the map data with a second set of coordinates.
This is useful for describing field regions with inherent symmetries.
For example, a dipole spectrometer map with a mirror symmetry about the
midplane can be specified by storing only the upper half of the map in
in a file and then including two grid elements in the mappedBfield tag.
1.6.2.1) grid
There are two types of grids, cartesian and cylindrical. Both kinds
describe regions of space with simple boundaries: cartesian grids are
defined within a box and cylindrical grids within a tube section (see
solids element "tubs" below for the definition of a tube section). The
boundaries of the grid together with the number of samples along each of
the grid axes are defined by content elements within the grid tag. The
grid tag itself only has a single attribute.
type : "cartesian" or "cylindrical"
1.6.2.1.1) Cartesian grid
The organization of the field data in the map file is defined using a
sequence of three nested "samples" tags within the containing grid tag.
The samples tags define the bounds of the grid in terms of lower and
upper coordinates and the number of samples contained within those bounds.
The attributes of the samples tags are as follows.
axis : one of "x", "y" or "z".
n : number of samples along the given axis.
bounds : space-separated list of the lower and upper bounds
of the sampled grid along the given axis.
sense : whether the sign of the field component corresponding
to this axis in the map is "forward" or "reverse",
introduced to fold maps with mirror symmetry.
unit_length : length unit for bounds attribute [default: cm]
for grid points within the cartesian grid box.
There must be three nested samples tags within each grid tag, with no axis
values repeated. The nesting indicates the sequencing of the field data
contained in the map file. It is not necessary that the lower bound be
numerically less than the upper bound; the coordinate order must correspond
to the order the data are stored in the map file.
1.6.2.1.2) Cylindrical grid
The organization of the field data in the map file is defined using a
sequence of three nested "samples" tags within the containing grid tag.
The samples tags define the bounds of the grid in terms of lower and
upper coordinates and the number of samples contained within those bounds.
The attributes of the samples tags are as follows.
axis : one of "r", "phi" or "z".
n : number of samples along the given axis.
bounds : space-separated list of the lower and upper bounds
of the sampled grid along the given axis.
unit_length : length unit for bounds attribute [default: cm]
of r,z grid points within the grid tube section.
unit_angle : angle unit for bounds attribute [default: deg]
of phi grid points within the grid tube section.
There must be three nested samples tags within each grid tag, with no axis
values repeated. The nesting indicates the sequencing of the field data
contained in the map file. It is not necessary that the lower bound be
numerically less than the upper bound; the coordinate order must correspond
to the order the data are stored in the map file.
1.6.2.2) Field data
The field map metadata are stored in hdds, but the data themselves are
not. Instead they are saved either in a database or a flat file external
to hdds. The field data are represented in the encoding specified in the
mappedBfield element (see section 1.6.2 above) with one grid point per
line. Each line contains three space-separated numbers in free floating
point format, eg. "6 -2.176 3.4e-5". The meaning of these three components
depends upon the grid type. For a Cartesian grid, they are interpreted as
B_x B_y B_z. For a cylindrical grid, they are B_rho, B_phi, B_z. Note
that the order of the components is the same regardless of the nesting
order of the grid points.
1.6.3) Region contents: tracking advisories
============================================
The region element is supposed to contain any bits and pieces of advice
that the might be useful to the translator in deciding how to encode the
geometry for a particular simulation. Besides electromagnetic fields,
the rest of this information is advisory only and does not need to be
heeded by a translator unless it is deemed useful for setting up the
simulation. The following advisory tags are supported.
1.6.3.1) Swim
The "swim" element only makes sense in the case of a region containing
a mappedBfield. Its purpose is to advise the tracking code on how to
integrate the path of a charged particle in the magnetic field. The
following attributes are provided.
method : can take on one of the following values
*) method="helix" [default] is appropriate if the field is close
enough to uniform that a charged particle path is
approximated well by helical track segments.
*) method="RungeKutta" is appropriate if the field is sufficiently
nonuniform that charged particle tracks should be
found by numerical integration of the Lorentz equation.
maxArcStep: maximum step size before needing to sample the field
again, specified in terms of the angle subtended by
the arc segment, default is 1.
unit_angle: units for maxArcStep [degrees].
1.6.4) Region examples
=======================
<region name="beamlineDipoles" comment="photon beam dipole field">
<uniformBfield Bx_By_Bz="0 0 2" unit="kG"/>
</region>
<region name="pairSpectrometer" comment="photon beam pair spetrometer">
<computedBfield function="gufld_DB(r,B)" maxBfield="2.5" unit="kG"/>
</region>
<region name="taggerDipoles" comment="tagging spectrometer field map">
<mappedBfield map="file://taggermap.dat" maxBfield="80"
encoding="utf-8" unit="kG">
<grid type="cartesian">
<samples axis="x" n="351" bounds="-340 10" unit_length="cm">
<samples axis="z" n="1611" bounds="-10 1600" unit_length="cm">
<samples axis="y" n="16" bounds="0 -1.5" unit_length="cm"/>
</samples>
</samples>
</grid>
<grid type="cartesian">
<samples axis="x" n="351" bounds="-340 10"
sense="reverse" unit_length="cm">
<samples axis="z" n="1611" bounds="-10 1600"
sense="reverse" unit_length="cm">
<samples axis="y" n="16" bounds="0 -1.5" unit_length="cm"/>
</samples>
</samples>
</grid>
<grid type="cartesian">
<samples axis="x" n="351" bounds="-340 10" unit_length="cm">
<samples axis="z" n="1611" bounds="-10 1600" unit_length="cm">
<samples axis="y" n="16" bounds="0 1.5" unit_length="cm"/>
</samples>
</samples>
</grid>
</mappedBfield>
</region>
<region name="solenoidBfield" comment="LASS spectrometer field map">
<mappedBfield map="file://taggermap.dat" maxBfield="2.5"
encoding="utf-8" unit="Tesla">
<grid type="cylindrical">
<samples axis="phi" n="1" bounds="0 360" unit_angle="deg"/>
<samples axis="r" n="41" bounds="0 40" unit_length="in"/>
<samples axis="z" n="251" bounds="30 280" unit_length="in"/>
</samples>
</samples>
</grid>
</mappedBfield>
<swim method="RungeKutta"/>
</region>