« back to all changes in this revision
Viewing changes to doc/doc_src/mice_modules/mice_module.tex
- browse files at revision 779.1.13
- compare with another revision
- download diff
- download tarball
- view history from revision 779.1.13
- Committer: Edward Santos
- Date: 2012-07-04 13:24:18 UTC
- mfrom: (661.1.11 release)
- mto: (794.1.3 tracker_devel) (779.2.3 tracker_devel)
- mto: This revision was merged to the branch mainline in revision 792.
- Revision ID: e.santos10@imperial.ac.uk-20120704132418-iwilezz80ggb1208
merging with trunk.
- files added:
- doc/doc_src/mice_modules
- files removed:
- src/legacy/BeamTools/BTFastSolenoid.cc
- files modified:
- .bzrignore
added
removed
doc/doc_src/mice_modules/mice_module.tex
1
% This file was converted to LaTeX by Writer2LaTeX ver. 1.2
2
% see http://writer2latex.sourceforge.net for more info
3
\documentclass[letterpaper]{article}
4
\usepackage[ascii]{inputenc}
5
\usepackage[T1]{fontenc}
6
\usepackage[english]{babel}
7
\usepackage{amsmath}
8
\usepackage{amssymb,amsfonts,textcomp}
9
\usepackage{color}
10
\usepackage{array}
11
\usepackage{supertabular}
12
\usepackage{hhline}
13
\usepackage{hyperref}
14
\hypersetup{pdftex, colorlinks=true, linkcolor=blue, citecolor=blue, filecolor=blue, urlcolor=blue, pdftitle=, pdfauthor=, pdfsubject=, pdfkeywords=}
15
\usepackage[pdftex]{graphicx}
16
\newcommand\textsubscript[1]{\ensuremath{{}_{\text{#1}}}}
17
% Outline numbering
18
\setcounter{secnumdepth}{0}
19
\makeatletter
20
\newcommand\arraybslash{\let\\\@arraycr}
21
\makeatother
22
% List styles
23
\newcommand\liststyleLi{%
24
\renewcommand\labelitemi{${\bullet}$}
25
\renewcommand\labelitemii{${\circ}$}
26
\renewcommand\labelitemiii{${\blacksquare}$}
27
\renewcommand\labelitemiv{${\bullet}$}
28
}
29
\newcommand\liststyleLii{%
30
\renewcommand\labelitemi{${\bullet}$}
31
\renewcommand\labelitemii{${\circ}$}
32
\renewcommand\labelitemiii{${\blacksquare}$}
33
\renewcommand\labelitemiv{${\bullet}$}
34
}
35
\newcommand\liststyleLiii{%
36
\renewcommand\labelitemi{${\bullet}$}
37
\renewcommand\labelitemii{${\circ}$}
38
\renewcommand\labelitemiii{${\blacksquare}$}
39
\renewcommand\labelitemiv{${\bullet}$}
40
}
41
\newcommand\liststyleLiv{%
42
\renewcommand\labelitemi{${\bullet}$}
43
\renewcommand\labelitemii{${\circ}$}
44
\renewcommand\labelitemiii{${\blacksquare}$}
45
\renewcommand\labelitemiv{${\bullet}$}
46
}
47
\newcommand\liststyleLv{%
48
\renewcommand\labelitemi{${\bullet}$}
49
\renewcommand\labelitemii{${\circ}$}
50
\renewcommand\labelitemiii{${\blacksquare}$}
51
\renewcommand\labelitemiv{${\bullet}$}
52
}
53
\newcommand\liststyleLvi{%
54
\renewcommand\labelitemi{${\bullet}$}
55
\renewcommand\labelitemii{${\circ}$}
56
\renewcommand\labelitemiii{${\blacksquare}$}
57
\renewcommand\labelitemiv{${\bullet}$}
58
}
59
\newcommand\liststyleLvii{%
60
\renewcommand\labelitemi{${\bullet}$}
61
\renewcommand\labelitemii{${\circ}$}
62
\renewcommand\labelitemiii{${\blacksquare}$}
63
\renewcommand\labelitemiv{${\bullet}$}
64
}
65
\newcommand\liststyleLviii{%
66
\renewcommand\labelitemi{{\textbullet}}
67
\renewcommand\labelitemii{${\circ}$}
68
\renewcommand\labelitemiii{${\blacksquare}$}
69
\renewcommand\labelitemiv{{\textbullet}}
70
}
71
\newcommand\liststyleLix{%
72
\renewcommand\labelitemi{{\textbullet}}
73
\renewcommand\labelitemii{${\circ}$}
74
\renewcommand\labelitemiii{${\blacksquare}$}
75
\renewcommand\labelitemiv{{\textbullet}}
76
}
77
\newcommand\liststyleLx{%
78
\renewcommand\labelitemi{{\textbullet}}
79
\renewcommand\labelitemii{${\circ}$}
80
\renewcommand\labelitemiii{${\blacksquare}$}
81
\renewcommand\labelitemiv{{\textbullet}}
82
}
83
\newcommand\liststyleLxi{%
84
\renewcommand\theenumi{\arabic{enumi}}
85
\renewcommand\theenumii{\arabic{enumii}}
86
\renewcommand\theenumiii{\arabic{enumiii}}
87
\renewcommand\theenumiv{\arabic{enumiv}}
88
\renewcommand\labelenumi{\theenumi.}
89
\renewcommand\labelenumii{\theenumii.}
90
\renewcommand\labelenumiii{\theenumiii.}
91
\renewcommand\labelenumiv{\theenumiv.}
92
}
93
\newcommand\liststyleLxii{%
94
\renewcommand\labelitemi{${\bullet}$}
95
\renewcommand\labelitemii{${\circ}$}
96
\renewcommand\labelitemiii{${\blacksquare}$}
97
\renewcommand\labelitemiv{${\bullet}$}
98
}
99
\newcommand\liststyleLxiii{%
100
\renewcommand\labelitemi{${\bullet}$}
101
\renewcommand\labelitemii{${\circ}$}
102
\renewcommand\labelitemiii{${\blacksquare}$}
103
\renewcommand\labelitemiv{${\bullet}$}
104
}
105
\newcommand\liststyleLxiv{%
106
\renewcommand\labelitemi{${\bullet}$}
107
\renewcommand\labelitemii{${\circ}$}
108
\renewcommand\labelitemiii{${\blacksquare}$}
109
\renewcommand\labelitemiv{${\bullet}$}
110
}
111
% Page layout (geometry)
112
\setlength\voffset{-1in}
113
\setlength\hoffset{-1in}
114
\setlength\topmargin{2cm}
115
\setlength\oddsidemargin{2cm}
116
\setlength\textheight{23.017668cm}
117
\setlength\textwidth{17.59cm}
118
\setlength\footskip{26.144882pt}
119
\setlength\headheight{0cm}
120
\setlength\headsep{0cm}
121
% Footnote rule
122
\setlength{\skip\footins}{0.119cm}
123
\renewcommand\footnoterule{\vspace*{-0.018cm}\setlength\leftskip{0pt}\setlength\rightskip{0pt plus 1fil}\noindent\textcolor{black}{\rule{0.25\columnwidth}{0.018cm}}\vspace*{0.101cm}}
124
% Pages styles
125
\makeatletter
126
\newcommand\ps@Standard{
127
\renewcommand\@oddhead{}
128
\renewcommand\@evenhead{}
129
\renewcommand\@oddfoot{\thepage{}}
130
\renewcommand\@evenfoot{\@oddfoot}
131
\renewcommand\thepage{\arabic{page}}
132
}
133
\makeatother
134
\pagestyle{Standard}
135
\setlength\tabcolsep{1mm}
136
\renewcommand\arraystretch{1.3}
137
\title{}
138
\author{}
139
\date{2012-03-12}
140
\begin{document}
141
\section{Mice Module Documentation}
142
This document documents the main functionality of the Mice Modules that control geometry and fields of G4MICE. The
143
document is divided into three parts. Part 1 gives an overview of the basic usage of Mice Modules. Part 2 gives details
144
on how to implement different geometry models in G4MICE. Part 3 gives details on how to implement different
145
electromagnetic field models in G4MICE.
146
147
\subsection{How to Use this document}
148
This document is best used in conjunction with the various examples than can be found in any installation of G4MICE. If
149
you are familiar with Mice Modules already, the first part can be omitted and the latter two parts used as reference
150
materials.
151
152
Any problems or omissions should be emailed to the document author, chris.rogers@stfc.ac.uk. I really like to get
153
feedback on what is annoying in the documentation, what doesn't make sense and what is just wrong -- so I encourage you
154
to hassle me!
155
156
\clearpage
157
\bigskip
158
159
\setcounter{tocdepth}{10}
160
\renewcommand\contentsname{Table of Contents}
161
\tableofcontents
162
163
\bigskip
164
165
\clearpage\section{Overview}
166
Mice Modules are the objects that control the geometry and fields that are simulated in G4MICE. They are used in
167
conjunction with a datacard file, which provides global run control parameters. Mice Modules are created by reading in
168
a series of text files when G4MICE applications are run. All Mice Module files must be in a subdirectory of the
169
directory defined by the environment variable \textit{\$\{MICEFILES\}}.
170
171
This geometry information is used primarily by the Simulation application for tracking of particles through magnetic
172
fields. A few commands are specific to detector Reconstruction and accelerator beam Optics applications.
173
174
The Mice Modules are created in a tree structure. Each module is a parent of any number of child modules. Typically the
175
parent module will describe a physical volume, and child modules will describe physical volumes that sit inside the
176
parent module. Modules cannot be used to describe volumes that do not sit at least partially inside the volume if the
177
parent module.
178
179
Each Mice Module file consists of a series of lines of text. Firstly the Module name is defined. This is followed by an
180
opening curly bracket, then the description of the module and the placement of any child modules, and finally a closing
181
curly bracket. Commands, curly brackets etc must be separated by an end of line character.
182
183
Comments are indicated using either two slashes or an exclamation mark. Characters placed after a comment on a line are
184
ignored.
185
186
G4MICE operates in a right handed coordinate system \textit{(x,y,z)}. In the absence of any rotation, lengths are
187
considered to be extent along the \textit{z}{}-axis, widths to be extent along the \textit{x}{}-axis and heights to be
188
extent along the \textit{y}{}-axis. Rotations (q\textsubscript{x}, q\textsubscript{y}, q\textsubscript{z}) are defined
189
as a rotation about the z-axis through q\textsubscript{z}, followed by a rotation about the y-axis through
190
q\textsubscript{y}, followed by a rotation about the x-axis through q\textsubscript{x}.
191
192
\subsection{Configuration File}
193
The Configuration file places the top level objects in MICE. The location of the file is controlled by the datacard
194
\textit{MiceModel}. G4MICE looks for the configuration file in the first instance in the directory
195
196
\ \ \$\textit{\{MICEFILES\}/Models/Configuration/{\textless}MiceModel{\textgreater}}
197
198
where \textit{\$\{MICEFILES\}} is a user-defined environment variable. If G4MICE fails to find the file it searches the
199
local directory.
200
201
The world volume is defined in the Configuration file and any children of the world volume are referenced by the
202
Configuration file. The Configuration file looks like:
203
204
{\ttfamily
205
\ \ Configuration \textit{{\textless}Configuration Name{\textgreater}}}
206
207
{\ttfamily
208
\ \ \{}
209
210
{\ttfamily\itshape
211
\ \ \ \ \textup{Dimensions\ \ }{\textless}x{\textgreater} {\textless}y{\textgreater} {\textless}z{\textgreater}
212
{\textless}Units{\textgreater}}
213
214
{\ttfamily\itshape
215
\ \ \ \ {\textless}Properties{\textgreater}}
216
217
{\ttfamily\itshape
218
\ \ \ \ {\textless}Child Modules{\textgreater}}
219
220
{\ttfamily
221
\ \ \}}
222
223
\textit{{\textless}Configuration Name{\textgreater}} is the name of the configuration. Typically the Configuration file
224
name is given by \textit{{\textless}Configuration Name{\textgreater}}.dat. The world volume is always a rectangular box
225
centred on (0,0,0) with x, y, and z extent set by the Dimensions. Properties and Child Modules are described below and
226
added as in any Module.
227
228
\subsubsection{Substitutions}
229
It is possible to make keyword substitutions that substitutes all instances of {\textless}name{\textgreater} with
230
{\textless}value{\textgreater} in all Modules. The syntax is
231
232
{\ttfamily
233
\ \ Substitution {\textless}name{\textgreater} {\textless}value{\textgreater}}
234
235
{\textless}name{\textgreater} must start with a single \$ sign. Substitutions must be defined in the Configuration file.
236
Note this is a direct text substitution in the MiceModules before the modules are parsed properly. So for example,
237
238
{\ttfamily
239
\ \ Substitution \$Sub SomeText}
240
241
{\ttfamily
242
\ \ PropertyString FieldType \$Sub}
243
244
{\ttfamily
245
\ \ PropertyDouble \$SubValue 10}
246
247
would be parsed as G4MICE like
248
249
{\ttfamily
250
\ \ PropertyString FieldType \ \ \ \ SomeText}
251
252
{\ttfamily
253
\ \ PropertyDouble SomeTextValue 10}
254
255
\subsubsection{Expressions}
256
The use of equations in properties of type double and Hep3Vector is also allowed in place of a single value. So, for
257
example,
258
259
\ \ \texttt{PropertyDouble FieldStrength 0.5*2 T}
260
261
would result in a FieldStrength property of 1 Tesla.\texttt{ }
262
263
\subsubsection{Expression Substitutions}
264
Some additional variables can be defined in specific cases by G4MICE itself for substitution into experssions, in which
265
case they will start with @ symbol. For these variable substitutions, it is only possible to make the substitution into
266
expressions. So for example,
267
268
{\ttfamily
269
\ \ PropertyDouble ScaleFactor 2*@RepeatNumber}
270
271
Would substitute @RepeatNumber \ into the expression. @RepeatNumber \ is defined by G4MICE when repeating modules are
272
used (see RepeatModule2, below). Note the following code is not valid
273
274
{\ttfamily
275
\ \ PropertyString FileName File@RepeatNumber //NOT VALID}
276
277
This is because Expression Substitutions can only be used in an expression (i.e. an equation).
278
279
\subsection[Module Files]{Module Files}
280
Children of the top level Mice Module are defined by Modules. G4MICE will attempt to find a module in an external file.
281
The location of the file is controlled by the parent Module. Initially G4MICE looks in the directory
282
283
\ \ \$\textit{\{MICEFILES\}/Models/Modules/{\textless}Module{\textgreater}}
284
285
If the Mice Module cannot be found, G4MICE searches the local directory. If the module file still cannot be found,
286
G4MICE will issue a warning and proceed.
287
288
The Module description is similar in structure to the Configuration file:
289
290
{\ttfamily
291
\ \ Module \textit{{\textless}Module Name{\textgreater}}}
292
293
{\ttfamily
294
\ \ \{}
295
296
{\ttfamily
297
\ \ \ \ Volume\ \ \textit{{\textless}Volume Type{\textgreater}}}
298
299
{\ttfamily\itshape
300
\ \ \ \ \textup{Dimensions\ \ }{\textless}Dimension1{\textgreater} {\textless}Dimension2{\textgreater}
301
{\textless}Dimension3{\textgreater} {\textless}Units{\textgreater}}
302
303
{\ttfamily\itshape
304
\ \ \ \ {\textless}Properties{\textgreater}}
305
306
{\ttfamily\itshape
307
\ \ \ \ {\textless}Child Modules{\textgreater}}
308
309
{\ttfamily
310
\ \ \}}
311
312
\textit{{\textless}Module Name{\textgreater}} is the name of the module. Typically the Module file name is given by
313
\textit{{\textless}Module Name{\textgreater}}.dat.
314
315
The definition of Volume, Dimensions, Properties and Child Modules are described below.
316
317
\subsection{Volume and Dimensions}
318
The volume described by the MiceModule can be one of several types. Replace \textit{{\textless}Volume
319
Type{\textgreater}} with the appropriate volume below. Cylinder, Box and Tube define cylindrical and cuboidal volumes.
320
Polycone defines an arbitrary volume of rotation and is described in detail below. Wedge describes a wedge with a
321
triangular projection in the y-z plane and rectangular projections in x-z and x-y planes. Quadrupole defines an
322
aperture with four cylindrical pole tips.
323
324
In general, the physical volumes that scrape the beam are defined independently of the field maps. This is the more
325
versatile way to do things, but there are some pitfalls which such an implementation introduces. For example, in
326
hard-edged fields like pillboxes, tracking errors can be introduced when G4MICE steps into the field region. This can
327
be avoided by adding windows (probably made of vacuum material) to force GEANT4 to stop tracking, make a small step
328
over the field boundary, and then restart tracking inside the field. However, such details are left for the user to
329
implement.
330
331
\begin{center}
332
\tablefirsthead{\hline
333
{\bfseries Volume} &
334
\multicolumn{1}{m{4.321cm}|}{{\bfseries Dimension1}} &
335
\multicolumn{1}{m{4.564cm}|}{{\bfseries Dimension2}} &
336
{\bfseries Dimension3}\\}
337
\tablehead{\hline
338
{\bfseries Volume} &
339
\multicolumn{1}{m{4.321cm}|}{{\bfseries Dimension1}} &
340
\multicolumn{1}{m{4.564cm}|}{{\bfseries Dimension2}} &
341
{\bfseries Dimension3}\\}
342
\tabletail{}
343
\tablelasttail{}
344
\begin{supertabular}{|m{2.659cm}|m{4.321cm}m{4.564cm}m{5.25cm}|}
345
\hline
346
None &
347
\multicolumn{3}{m{14.535cm}|}{No dimensions required. Note cannot define daughter Modules for this volume type.}\\\hline
348
Cylinder &
349
\multicolumn{1}{m{4.321cm}|}{Radius} &
350
\multicolumn{1}{m{4.564cm}|}{Length in z} &
351
Not used (leave blank)\\\hline
352
Box &
353
\multicolumn{1}{m{4.321cm}|}{Width in x} &
354
\multicolumn{1}{m{4.564cm}|}{Height in y} &
355
Length along z\\\hline
356
Tube &
357
\multicolumn{1}{m{4.321cm}|}{Inner Radius} &
358
\multicolumn{1}{m{4.564cm}|}{Outer Radius} &
359
Length in z\\\hline
360
Trapezoid &
361
\multicolumn{1}{m{4.321cm}|}{Half Width in x} &
362
\multicolumn{1}{m{4.564cm}|}{Half Height in y} &
363
Half Length in z\\\hline
364
Wedge &
365
\multicolumn{3}{m{14.535cm}|}{See documentation below.}\\\hline
366
Polycone &
367
\multicolumn{3}{m{14.535cm}|}{No dimensions required. Volume defined from external file.}\\\hline
368
Quadrupole &
369
\multicolumn{3}{m{14.535cm}|}{No dimensions required. Dimensions defined from module properties.}\\\hline
370
Multipole &
371
\multicolumn{3}{m{14.535cm}|}{No dimensions required. Dimensions defined from module properties.}\\\hline
372
Boolean &
373
\multicolumn{3}{m{14.535cm}|}{No dimensions required. Dimensions defined from module properties.}\\\hline
374
Sphere &
375
\multicolumn{3}{m{14.535cm}|}{See documentation below.}\\\hline
376
\end{supertabular}
377
\end{center}
378
\clearpage\subsection{Properties}
379
Many of the features of G4MICE that can be enabled in a module are described using properties. For example, properties
380
enable the user to define detectors and fields. Properties can be either of several types: PropertyDouble,
381
PropertyString, PropertyBool, PropertyHep3Vector or PropertyInt. A property is declared via
382
383
{\ttfamily\itshape
384
\ \ \ \ {\textless}Property Type{\textgreater} {\textless}Property Name{\textgreater} {\textless}Value{\textgreater}
385
{\textless}Units if appropriate{\textgreater}}
386
387
Different properties that can be enabled for Mice Modules are described elsewhere in this document. Properties of type
388
PropertyDouble and PropertyHep3Vector can have units. Units are defined in the CLHEP library. Units are case sensitive;
389
G4MICE will return an error message if it fails to parse units. Combinations of units such as T/m or N*m can be defined
390
using '*' and '/' as appropriate. Properties cannot be defined more than once within the same module.
391
392
\subsection{Child Modules}
393
Child Modules are defined with a position, rotation and scale factor. This places, and rotates, the child volume and any
394
fields present relative to the parent volume. Scale factor scales fields defined in the child module and any of its
395
children. Scale factors are recursively multiplicative; that is the field generated by a child module will be scaled by
396
the product of the scale factor defined in the parent module and all of its parents.
397
398
The child module definition looks like:
399
400
{\ttfamily
401
\ \ Module \textit{{\textless}Module File Name{\textgreater}}}
402
403
{\ttfamily
404
\ \ \{}
405
406
{\ttfamily
407
\ \ \ \ Position\ \ \textit{{\textless}x position{\textgreater} {\textless}y position{\textgreater} {\textless}z
408
position{\textgreater} {\textless}Units{\textgreater}}}
409
410
{\ttfamily\itshape
411
\ \ \ \ \textup{Rotation\ \ }{\textless}x rotation{\textgreater} {\textless}y rotation{\textgreater} {\textless}z
412
rotation{\textgreater} {\textless}Units{\textgreater}}
413
414
{\ttfamily\itshape
415
\ \ \ \ \textup{ScaleFactor\ \ }{\textless}Value{\textgreater}}
416
417
{\ttfamily\itshape
418
\ \ \ \ {\textless}Define volume, dimensions and properties for this instance only{\textgreater}}
419
420
{\ttfamily
421
\ \ \}}
422
423
\textit{{\textless}Module File Name{\textgreater}} is defined relative to the folder
424
\textit{\$\{MICEFILES\}/Models/Modules/}. The position and rotation default to 0 0 0 and the scale factor defaults to
425
1.
426
427
\liststyleLi
428
\begin{itemize}
429
\item Volume, Dimension and Properties of the child module can be defined at the level of the parent; in this case these
430
values will be used only for this instance of the module.
431
\end{itemize}
432
\liststyleLii
433
\begin{itemize}
434
\item If no file can be found, G4MICE will press on regardless, attempting to build a geometry using the information
435
defined in the parent volume.
436
\end{itemize}
437
\subsection[Module Hierarchy and GEANT4 Physical Volumes]{Module Hierarchy and GEANT4 Physical Volumes}
438
[Warning: Draw object ignored]G4MICE enables users to place arbitrary physical volumes in a GEANT4 geometry. The
439
formatting of G4MICE is such that users are encouraged to use the GEANT4 tree structure for placing physical volumes.
440
This is a double-edged sword, in that it provides users with a convenient interface for building geometries, but it is
441
not a terribly safe interface.
442
443
Consider the cartoon of physical volumes shown above. Here there is a blue volume sitting inside a red volume sitting
444
inside the black world volume. For the volumes to be represented properly, the module that represents the blue volume
445
MUST be a child of the module that represents the red volume. The module that represents the red volume MUST, in turn,
446
be a child of the module that represents the black volume, in this case the Configuration file.
447
448
What would happen if we placed the blue volume directly into the Black volume, i.e. the Configuration file? GEANT4 would
449
silently ignore the blue volume, or the red volume, depending on the order in which they are added into the GEANT4
450
geometry. What would happen if we placed the blue volume overlapping the red and black volumes? The behaviour of GEANT4
451
is not clear in this case.
452
453
\liststyleLiii
454
\begin{itemize}
455
\item Never allow a volume to overlap any part of another volume that is not it's direct parent.
456
\end{itemize}
457
It is possible to check for overlaps by setting the datacard \textit{CheckVolumeOverlaps} to 1.
458
459
\subsection{}
460
\clearpage\subsection{A Sample Configuration File}
461
Below is listed a sample configuration file, which is likely to be included in the file
462
\textit{ExampleConfiguration.dat;} the actual name is specified by the datacard MiceModel.
463
464
{\ttfamily
465
\ \ Configuration ExampleConfiguration}
466
467
{\ttfamily
468
\ \ \{}
469
470
{\ttfamily
471
\ \ \ \ Dimensions 1500.0 1000.0 5000.0 cm}
472
473
{\ttfamily
474
\ \ \ \ PropertyString Material AIR}
475
476
{\ttfamily
477
\ \ \ \ Substitution \ \ \$MyRedColour 0.75}
478
479
{\ttfamily
480
\ \ \ \ Module BeamLine/SolMag.dat}
481
482
{\ttfamily
483
\ \ \ \ \{}
484
485
{\ttfamily
486
\ \ \ \ \ \ Position 140.0 0.0 -2175.0 cm}
487
488
{\ttfamily
489
\ \ \ \ \ \ Rotation 0.0 30.0 0.0 degree}
490
491
{\ttfamily
492
\ \ \ \ \ \ ScaleFactor 1.}
493
494
{\ttfamily
495
\ \ \ \ \}}
496
497
{\ttfamily
498
\ \ \ \ Module BeamLine/BendMag.dat}
499
500
{\ttfamily
501
\ \ \ \ \ \ \{}
502
503
{\ttfamily
504
\ \ \ \ \ \ \ \ Position 0.0 0.0 -1935.0 cm}
505
506
{\ttfamily
507
\ \ \ \ \ \ \ \ Rotation 0.0 15.0 0.0 degree}
508
509
{\ttfamily
510
\ \ \ \ \ \ ScaleFactor 1.}
511
512
{\ttfamily
513
\ \ \ \ \ \ \}}
514
515
{\ttfamily
516
\ \ \ \ Module NoFile\_Box1}
517
518
{\ttfamily
519
\ \ \ \ \ \ \{}
520
521
{\ttfamily
522
\ \ \ \ \ \ Volume \ \ \ Box}
523
524
{\ttfamily
525
\ \ \ \ \ \ Dimension 1.0 1.0 1.0}
526
527
{\ttfamily
528
\ \ \ \ \ \ \ \ Position 0.0 0.0 \ 200.0 cm}
529
530
{\ttfamily
531
\ \ \ \ \ \ \ \ Rotation 0.0 15.0 0.0 degree}
532
533
{\ttfamily
534
\ \ \ \ \ \ PropertyString Material Galactic}
535
536
{\ttfamily
537
\ \ \ \ \ \ PropertyDouble RedColour \$MyRedColour}
538
539
{\ttfamily
540
\ \ \ \ \ \ Module NoFile\_Box2}
541
542
{\ttfamily
543
\ \ \ \ \ \ \ \ \{}
544
545
{\ttfamily
546
\ \ \ \ \ \ \ \ Volume \ \ \ Box}
547
548
{\ttfamily
549
\ \ \ \ \ \ \ \ Dimension 0.5 0.5 0.5*3 m //z length = 0.5*3 = 1.5 m}
550
551
{\ttfamily
552
\ \ \ \ \ \ \ \ \ \ Rotation \ 0.0 15.0 0.0 degree //Rotation relative to parent}
553
554
{\ttfamily
555
\ \ \ \ \ \ \ \ PropertyString Material Galactic}
556
557
{\ttfamily
558
\ \ \ \ \ \ \ \ PropertyDouble RedColour \$MyRedColour}
559
560
{\ttfamily
561
\ \ \ \ \ \ \}}
562
563
{\ttfamily
564
\ \ \ \ \ \ \}}
565
566
\ \ \}
567
568
\clearpage\subsection{A Sample Child Module File}
569
Below is listed a sample module file, which is likely to be included in the file \textit{SolMag.dat}; the actual
570
location is specified by the module or configuration that calls FCoil. The module contains a number of properties that
571
define the field.
572
573
{\ttfamily
574
\ \ Module SolMag}
575
576
{\ttfamily
577
\ \ \{}
578
579
{\ttfamily
580
\ \ \ \ Volume Tube }
581
582
{\ttfamily
583
\ \ \ \ Dimensions 263.0 347.0 210.0 mm}
584
585
{\ttfamily
586
\ \ \ \ PropertyString Material Al}
587
588
{\ttfamily
589
\ \ \ \ PropertyDouble BlueColour 0.75}
590
591
{\ttfamily
592
\ \ \ \ PropertyDouble GreenColour 0.75}
593
594
{\ttfamily
595
\ \ \ \ //field}
596
597
{\ttfamily
598
\ \ \ \ PropertyString FieldType \ \ \ \ \ \ Solenoid}
599
600
{\ttfamily
601
\ \ \ \ PropertyString FileName \ \ \ \ \ \ \ focus.dat}
602
603
{\ttfamily
604
\ \ \ \ PropertyDouble CurrentDensity \ \ \ \ \ 1.}
605
606
{\ttfamily
607
\ \ \ \ PropertyDouble Length \ \ \ \ \ \ \ \ \ \ \ 210. mm}
608
609
{\ttfamily
610
\ \ \ \ PropertyDouble Thickness \ \ \ \ \ \ \ \ \ 84. mm}
611
612
{\ttfamily
613
\ \ \ \ PropertyDouble InnerRadius \ \ \ \ \ \ 263. mm}
614
615
{\ttfamily
616
\ \ \}}
617
618
\subsection{}
619
\clearpage\section{Geometry and Tracking Properties}
620
Properties for various aspects of the physical and engineering model of the simulation are described below. This
621
includes properties for sensitive detectors.
622
623
\subsection{General Properties}
624
There are a number of properties that are applicable to any MiceModule.
625
626
\begin{center}
627
\tablefirsthead{\hline
628
{\bfseries Property} &
629
{\bfseries Type} &
630
{\bfseries Description}\\}
631
\tablehead{\hline
632
{\bfseries Property} &
633
{\bfseries Type} &
634
{\bfseries Description}\\}
635
\tabletail{}
636
\tablelasttail{}
637
\begin{supertabular}{|m{3.665cm}|m{1.278cm}|m{12.052cm}|}
638
\hline
639
Material &
640
string &
641
The material that the volume is made up from\\\hline
642
Invisible &
643
bool &
644
Set to 1 to make the object invisible in visualisation, or 0 to make the object visible.\\\hline
645
\multicolumn{2}{m{5.143cm}|}{\hspace*{-\tabcolsep}\begin{tabular}{|m{3.665cm}|m{1.278cm}}
646
647
RedColour &
648
double\\\hline
649
GreenColour &
650
double\\\hline
651
BlueColour &
652
double\\\hline
653
\end{tabular}\hspace*{-\tabcolsep}
654
} &
655
Alter the colour of objects as they are visualised\\\hhline{~~-}
656
G4StepMax &
657
double &
658
The maximum step length that Geant4 can make in the volume. Inherits values from the parent volumes.\\\hline
659
\multicolumn{2}{m{5.143cm}|}{\hspace*{-\tabcolsep}\begin{tabular}{|m{3.665cm}|m{1.278cm}}
660
661
G4TrackMax &
662
double\\\hline
663
G4TimeMax &
664
double\\\hline
665
\end{tabular}\hspace*{-\tabcolsep}
666
} &
667
The maximum track length and particle time of a track. Tracks outside this bound are killed. Inherits values from the
668
parent volumes.\\\hhline{~~-}
669
G4KinMin &
670
double &
671
The minimum kinetic energy of a track. Tracks outside this bound are killed. Inherits values from the parent
672
volumes.\\\hline
673
SensitiveDetector &
674
string &
675
Set to the type of sensitive detector required. Possible sensitive detectors are \textit{TOF}, \textit{SciFi},
676
\textit{CKOV}, \textit{SpecialVirtual, Virtual, Envelope} or \textit{EMCAL}.\\\hline
677
\end{supertabular}
678
\end{center}
679
\subsection{Sensitive Detectors}
680
A sensitive detector (one in which hits are recorded) can be defined by including the SensitiveDetector property. When a
681
volume is set to be a sensitive detector G4MICE will automatically record tracks entering, exiting and crossing the
682
volume. Details such as the energy deposited by the track are sometimes also recorded in order to enable subsequent
683
modelling of the detector response.
684
685
Some sensitive detectors use extra properties.
686
687
\subsubsection[Scintillating Fibre Detector (SciFi)]{Scintillating Fibre Detector (SciFi)}
688
\subsubsection{Cerenkov Detector (CKOV)}
689
\subsubsection{Time Of Flight Counter (TOF)}
690
\subsubsection{Special Virtual Detectors}
691
Special virtual detectors are used to monitor tracking through a particular physical volume. Normally particle tracks
692
are written in the global coordinate system, although an alternate coordinate system can be defined. Additional
693
properties can be used to parameterise special virtual detectors.
694
695
\begin{center}
696
\tablefirsthead{\hline
697
{\bfseries Property} &
698
{\bfseries Type} &
699
{\bfseries Description}\\}
700
\tablehead{\hline
701
{\bfseries Property} &
702
{\bfseries Type} &
703
{\bfseries Description}\\}
704
\tabletail{}
705
\tablelasttail{}
706
\begin{supertabular}{|m{3.665cm}|m{1.3579999cm}|m{11.973001cm}|}
707
\hline
708
\multicolumn{2}{m{5.223cm}|}{\hspace*{-\tabcolsep}\begin{tabular}{|m{3.665cm}|m{1.3579999cm}}
709
710
ZSegmentation &
711
int\\\hline
712
PhiSegmentation &
713
int\\\hline
714
RSegmentation &
715
int\\\hline
716
\end{tabular}\hspace*{-\tabcolsep}
717
} &
718
Set the number of segments in the detector in Z, R or f. Defaults to 1.\\\hhline{~~-}
719
\multicolumn{2}{m{5.223cm}|}{\hspace*{-\tabcolsep}\begin{tabular}{|m{3.665cm}|m{1.3579999cm}}
720
721
SteppingThrough &
722
bool\\\hline
723
SteppingInto &
724
bool\\\hline
725
SteppingOutOf &
726
bool\\\hline
727
SteppingAcross &
728
bool\\\hline
729
\end{tabular}\hspace*{-\tabcolsep}
730
} &
731
Set to true to record tracks stepping through, into, out of or across the volume. Defaults to true.\\\hhline{~~-}
732
Station &
733
int &
734
Define an integer that is written to the output file to identify the station. Defaults to a unique integer identifier
735
chosen by G4MICE, which will be different each time the same Special Virtual is placed.\\\hline
736
LocalRefRotation &
737
Hep3
738
739
Vector &
740
If set, record hits relative to a reference rotation in the coordinate system of the SpecialVirtual detector.\\\hline
741
GlobalRefRotation &
742
Hep3
743
744
Vector &
745
If set, record hits relative to a reference rotation in the coordinate system of the Configuration.\\\hline
746
LocalRefPosition &
747
Hep3
748
749
Vector &
750
If set, record hits relative to a reference position in the coordinate system of the SpecialVirtual detector.\\\hline
751
GlobalRefPosition &
752
Hep3
753
754
Vector &
755
If set, record hits relative to a reference position in the coordinate system of the Configuration.\\\hline
756
\end{supertabular}
757
\end{center}
758
\subsubsection{}
759
\clearpage\subsubsection{Virtual Detectors}
760
Virtual detectors are used to extract all particle data at a particular plane, irrespective of geometry. Virtual
761
detectors do not need to have a physical volume. The \textit{plane} can be a plane in z, time, proper time, or a
762
physical plane with some arbitrary rotation and translation.
763
764
\begin{center}
765
\tablefirsthead{\hline
766
{\bfseries Property} &
767
{\bfseries Type} &
768
{\bfseries Description}\\}
769
\tablehead{\hline
770
{\bfseries Property} &
771
{\bfseries Type} &
772
{\bfseries Description}\\}
773
\tabletail{}
774
\tablelasttail{}
775
\begin{supertabular}{|m{3.665cm}|m{1.3579999cm}|m{11.973001cm}|}
776
\hline
777
{\itshape IndependentVariable} &
778
String &
779
\liststyleLiv
780
\begin{itemize}
781
\item If set to \textit{t}, particle data will be written for particles at the time defined by the \textit{PlaneTime}
782
property.
783
\end{itemize}
784
\liststyleLv
785
\begin{itemize}
786
\item If set to \textit{tau},\textit{ }particle data will be written for particles at the proper time defined by the
787
PlaneTime property.
788
\end{itemize}
789
\liststyleLvi
790
\begin{itemize}
791
\item If set to \textit{z}, particle data will be written for particles crossing the module's z-position.
792
\end{itemize}
793
\liststyleLvii
794
\begin{itemize}
795
\item If set to \textit{u}, particle data will be written for particles crossing a plane extending in \textit{x} and
796
\textit{y}.
797
\end{itemize}
798
\\\hline
799
{\itshape PlaneTime} &
800
Double &
801
If \textit{IndependentVariable} is \textit{t }or \textit{tau,} particle data will be written out at this time. Mandatory
802
if \textit{IndependentVariable} is \textit{t} or \textit{tau}.\\\hline
803
RadialExtent &
804
Double &
805
If set, particles outside this radius in the plane of the detector will not be recorded by the Virtual detector.\\\hline
806
GlobalCoordinates &
807
Bool &
808
If set to 0, particle data is written in the coordinate system of the module. Otherwise particle data is written in
809
global coordinates.\\\hline
810
MultiplePasses &
811
String &
812
Set how the VirtualPlane handles particles that pass through more than once. If set to Ignore, particles will be ignored
813
on second and subsequent passes. If set to SameStation, particles will be registered with the same station number. If
814
set to NewStation, particles will be registered with a NewStation number given by the \textit{(total number of
815
stations) + (this plane's station number)}, i.e. a new station number appropriate for a ring geometry.\\\hline
816
AllowBackwards &
817
Bool &
818
Set to false to prevent backwards-going particles from being recorded. Default is true.\\\hline
819
\end{supertabular}
820
\end{center}
821
\subsubsection{}
822
\clearpage\subsubsection{Envelope Detectors}
823
Envelope detectors are a type of Virtual detector that take all of the properties listed under virtual detectors, above.
824
In addition, in the optics application they can be used to interact with the beam envelope in a special way. The
825
following properties can be defined for Envelope Detectors \textit{in addition to} the properties specified above for
826
virtual detectors.
827
828
The The EnvelopeOut properties are used to make output from the envelope for use in the Optics optimiser.
829
830
\begin{center}
831
\tablefirsthead{\hline
832
{\bfseries Property} &
833
{\bfseries Type} &
834
{\bfseries Description}\\}
835
\tablehead{\hline
836
{\bfseries Property} &
837
{\bfseries Type} &
838
{\bfseries Description}\\}
839
\tabletail{}
840
\tablelasttail{}
841
\begin{supertabular}{|m{3.665cm}|m{1.3579999cm}|m{11.973001cm}|}
842
\hline
843
{\itshape EnvelopeOut1\_Name} &
844
String &
845
Defines the variable name that can be used as an expression substitution at the end of each iteration, typically
846
substituted into the Score parameters in the optimiser (see optimiser, below).\\\hline
847
{\itshape EnvelopeOut1\_Type} &
848
String &
849
Defines the type of variable that will be calculated for the substitution. Options are
850
851
\liststyleLviii
852
\begin{itemize}
853
\item Mean
854
\item Covariance
855
\item Standard\_Deviation
856
\item Correlation
857
\item Bunch\_Parameter
858
\end{itemize}
859
\\\hline
860
{\itshape EnvelopeOut1\_Variable} &
861
String &
862
Defines the variable that will be calculated for the substitution. Options are for Bunch\_Parameter
863
864
\liststyleLix
865
\begin{itemize}
866
\item \begin{itemize}
867
\item {\itshape emit\_6d \textup{: 6d emittance}}
868
\item {\itshape emit\_4d:\textup{ 4d emittance (in x-y space)}}
869
\item {\itshape emit\_t:\textup{ 2d emittance (in time space)}}
870
\item {\itshape emit\_x:\textup{ 2d emittance (in x space)}}
871
\item {\itshape emit\_y:\textup{ 2d emittance (in y space)}}
872
\item {\itshape beta\_4d:\textup{ 4d transverse beta function}}
873
\item {\itshape beta\_t:\textup{ 2d longitudinal beta function}}
874
\item {\itshape beta\_x: \textup{2d beta function (in(x space)}}
875
\item {\itshape beta\_y: \textup{2d beta function (in y space)}}
876
\item {\itshape alpha\_4d:\textup{ 4d transverse alpha function}}
877
\item {\itshape alpha\_t:\textup{ 2d longitudinal alpha function}}
878
\item {\itshape alpha\_x: \textup{2d alpha function (in(x space)}}
879
\item {\itshape alpha\_y: \textup{2d alpha function (in y space)}}
880
\item {\itshape gamma\_4d:\textup{ 4d transverse gamma function}}
881
\item {\itshape gamma\_t:\textup{ 2d longitudinal gamma function}}
882
\item {\itshape gamma\_x: \textup{2d gamma function (in(x space)}}
883
\item {\itshape gamma\_y: \textup{2d gamma function (in y space)}}
884
\item {\itshape disp\_x:\textup{ x-dispersion}}
885
\item {\itshape disp\_y:\textup{ y-dispersion}}
886
\item {\itshape ltwiddle:\textup{ normalised angular momentum}}
887
\item {\itshape lkin:\textup{ standard angular momentum}}
888
\end{itemize}
889
890
\end{itemize}
891
For Mean, Standard\_Deviation, Covariance and Correlation, variables should be selected from the options
892
893
\liststyleLx
894
\begin{itemize}
895
\item \textit{x: x-}position
896
\item {\itshape y:y-position}
897
\item {\itshape t: \textup{time}}
898
\item {\itshape px:\textup{ x-momentum}}
899
\item {\itshape py:\textup{ y-momentum}}
900
\item {\itshape E:\textup{ energy}}
901
\end{itemize}
902
For Mean, a single variable should be selected and value corresponding to the reference trajectory will be returned.
903
904
For Standard\_Deviation, a single variable should be selected and the 1 sigma beam size will be returned.
905
906
For Covariance and Correlation, two variables should be selected separated by a comma.\\\hline
907
\end{supertabular}
908
\end{center}
909
\subsection{Unconventional Volumes}
910
It is possible to define a number of volumes that use properties rather than the Dimensions keyword to define the volume
911
size.
912
913
{\sffamily\bfseries
914
Volume Trapezoid}
915
916
Volume Trapezoid gives a trapezoid which is not necessarily isosceles. Its dimensions are given by:
917
918
\begin{center}
919
\tablefirsthead{\hline
920
{\bfseries Property} &
921
{\bfseries Type} &
922
{\bfseries Description}\\}
923
\tablehead{\hline
924
{\bfseries Property} &
925
{\bfseries Type} &
926
{\bfseries Description}\\}
927
\tabletail{}
928
\tablelasttail{}
929
\begin{supertabular}{|m{3.665cm}|m{1.278cm}|m{12.052cm}|}
930
\hline
931
TrapezoidWidthX1 &
932
Double &
933
Gives width1 in x\\\hline
934
TrapezoidWidthX2 &
935
Double &
936
Gives width2 in x\\\hline
937
TrapezoidWidthY1 &
938
Double &
939
Gives height1 in y\\\hline
940
TrapezoidWidthY2 &
941
Double &
942
Gives height2 in y\\\hline
943
TrapezoidLengthZ &
944
Double &
945
Gives length along z\\\hline
946
\end{supertabular}
947
\end{center}
948
\subsubsection{A Trapezoid Volume is like a Wedge Volume (look visualization below) with the possibility to have
949
different values for x width and 2 (non-zero) values for y.}
950
\subsubsection{}
951
\clearpage\subsubsection{Volume Wedge}
952
A wedge is a triangular prism as shown in the diagram. Here the blue line extends along the positive z-axis and the red
953
line extends along the x-axis.
954
955
\begin{center}
956
\includegraphics[width=13.968cm,height=8.394cm]{MiceModule-img001.png}
957
\end{center}
958
\begin{center}
959
\tablefirsthead{\hline
960
{\bfseries Property} &
961
{\bfseries Type} &
962
{\bfseries Description}\\}
963
\tablehead{\hline
964
{\bfseries Property} &
965
{\bfseries Type} &
966
{\bfseries Description}\\}
967
\tabletail{}
968
\tablelasttail{}
969
\begin{supertabular}{|m{3.665cm}|m{1.278cm}|m{12.052cm}|}
970
\hline
971
Dimensions &
972
Hep3
973
974
Vector &
975
\liststyleLxi
976
\begin{enumerate}
977
\item Width of the prism in x
978
\item Open end height of the prism in y
979
\item Length of the prism in z
980
\end{enumerate}
981
\\\hline
982
\end{supertabular}
983
\end{center}
984
\subsubsection{Volume Polycone}
985
A polycone is a volume of rotation, defined by a number of points in r and z. The volume is found by a linear
986
interpolation of the points.
987
988
\begin{center}
989
\tablefirsthead{\hline
990
{\bfseries Property} &
991
{\bfseries Type} &
992
{\bfseries Description}\\}
993
\tablehead{\hline
994
{\bfseries Property} &
995
{\bfseries Type} &
996
{\bfseries Description}\\}
997
\tabletail{}
998
\tablelasttail{}
999
\begin{supertabular}{|m{3.665cm}|m{1.278cm}|m{12.052cm}|}
1000
\hline
1001
PolyconeType &
1002
string &
1003
Set to Fill to define a solid volume of rotation. Set to Cone to define a shell volume of rotation with an inner and
1004
outer surface.\\\hline
1005
FieldMapMode &
1006
string &
1007
The name of the file that contains the polycone data.\\\hline
1008
\end{supertabular}
1009
\end{center}
1010
\subsubsection{Volume Quadrupole}
1011
Quadrupoles are defined by an empty cylinder with four further cylinders that are approximations to pole tips.
1012
1013
\begin{center}
1014
\tablefirsthead{\hline
1015
{\bfseries Property} &
1016
{\bfseries Type} &
1017
{\bfseries Description}\\}
1018
\tablehead{\hline
1019
{\bfseries Property} &
1020
{\bfseries Type} &
1021
{\bfseries Description}\\}
1022
\tabletail{}
1023
\tablelasttail{}
1024
\begin{supertabular}{|m{3.665cm}|m{1.278cm}|m{12.052cm}|}
1025
\hline
1026
PhysicalLength &
1027
double &
1028
The length of the quadrupole container.\\\hline
1029
QuadRadius &
1030
double &
1031
The distance from the quad centre to the outside of the quad.\\\hline
1032
PoleTipRadius &
1033
double &
1034
The distance from the quad centre to the pole tip.\\\hline
1035
CoilRadius &
1036
double &
1037
~
1038
\\\hline
1039
CoilHalfWidth &
1040
double &
1041
~
1042
\\\hline
1043
BeamlineMaterial &
1044
string &
1045
The material from which the beamline volume is made.\\\hline
1046
QuadMaterial &
1047
string &
1048
The material from which the quadrupole volume is made.\\\hline
1049
\end{supertabular}
1050
\end{center}
1051
\subsubsection{Volume Multipole}
1052
Multipoles are defined by an empty box with an arbitrary number of cylinders that are approximations to pole tips. Poles
1053
are placed around the centre of the box with n-fold symmetry. Multipoles can be curved, in which case poles cannot be
1054
defined -- only a curved rectangular aperture will be present.
1055
1056
\begin{center}
1057
\tablefirsthead{\hline
1058
{\bfseries Property} &
1059
{\bfseries Type} &
1060
{\bfseries Description}\\}
1061
\tablehead{\hline
1062
{\bfseries Property} &
1063
{\bfseries Type} &
1064
{\bfseries Description}\\}
1065
\tabletail{}
1066
\tablelasttail{}
1067
\begin{supertabular}{|m{3.892cm}|m{1.333cm}|m{11.77cm}|}
1068
\hline
1069
{\itshape ApertureCurvature} &
1070
double &
1071
Radius of curvature of the multipole aperture. For now curved apertures cannot have poles. Set to 0 for a straight
1072
aperture.\\\hline
1073
{\itshape ApertureLength} &
1074
double &
1075
Length of the multipole aperture.\\\hline
1076
NumberOfPoles &
1077
int &
1078
Number of poles.\\\hline
1079
PoleCentreRadius &
1080
double &
1081
The distance from the centre of the aperture to the centre of the cylindrical pole.\\\hline
1082
PoleTipRadius &
1083
double &
1084
The distance from the centre of the aperture to the tip of the cylindrical pole.\\\hline
1085
{\itshape ApertureInnerHeight} &
1086
double &
1087
The inner full height of the aperture.\\\hline
1088
{\itshape ApertureInnerWidth} &
1089
double &
1090
The inner full width of the aperture.\\\hline
1091
{\itshape AppertureOuterHeight} &
1092
double &
1093
The outer full height of the aperture.\\\hline
1094
{\itshape ApertureOuterWidth} &
1095
double &
1096
The outer full width of the aperture.\\\hline
1097
\end{supertabular}
1098
\end{center}
1099
\subsubsection{Volume Boolean}
1100
Boolean volumes enable several volumes to be combined to make very sophisticated shapes from a number of elements.
1101
Elements can be combined either by union, intersection or subtraction operations. A union creates a volume that is the
1102
sum of two elements; an intersection creates a volume that covers the region where two volumes intersect each other;
1103
and a subtraction creates a volume that contains all of one volume except the region that another volume sits in.
1104
1105
Boolean volumes combine volumes modelled by other MiceModules (submodules), controlled using the properties listed
1106
below. Only the volume shape is used; position, rotation and field models etc are ignored. Materials, colours and other
1107
relevant properties are all taken only from the Boolean Volume's properties.
1108
1109
Note that unlike in other parts of G4MICE, submodules for use in Booleans (BaseModule, BooleanModule1, BooleanModule2
1110
...) must be defined in a separate file, either defined in \$MICEFILES/Models/Modules or in the working directory.
1111
1112
Also note that visualisation of boolean volumes is rather unreliable. Unfortunately this is a feature of GEANT4. An
1113
alternative technique is to use special virtual detectors to examine hits in boolean volumes.
1114
1115
\begin{center}
1116
\tablefirsthead{\hline
1117
{\bfseries Property} &
1118
{\bfseries Type} &
1119
{\bfseries Description}\\}
1120
\tablehead{\hline
1121
{\bfseries Property} &
1122
{\bfseries Type} &
1123
{\bfseries Description}\\}
1124
\tabletail{}
1125
\tablelasttail{}
1126
\begin{supertabular}{|m{3.89cm}|m{1.333cm}|m{11.772cm}|}
1127
\hline
1128
{\itshape BaseModule} &
1129
string &
1130
Name of the physical volume that the BooleanVolume is based on. This volume will be placed at (0,0,0) with no rotation,
1131
and all subsequent volumes will be added, subtracted or intersected with this one.\\\hline
1132
{\itshape BooleanModule1} &
1133
string &
1134
The first module to add. G4MICE will search for the MiceModule with path
1135
\$MICEFILES/Models/Modules/{\textless}BooleanModule1{\textgreater}.\\\hline
1136
{\itshape BooleanModule1Type} &
1137
string &
1138
The type of boolean operation to apply, either ``Union'', ``Intersection'' or ``Subtraction''.\\\hline
1139
{\itshape BooleanModule1Pos} &
1140
Hep3
1141
1142
Vector &
1143
The position of the new volume with respect to the Base volume.\\\hline
1144
{\itshape BooleanModule1Rot} &
1145
Hep3
1146
1147
Vector &
1148
The rotation of the new volume with respect to the Base volume.\\\hline
1149
{\itshape BooleanModuleN} &
1150
string &
1151
Add extra modules as required. Replace ``N'' with the module number. N must be a continuous series incrementing by 1 for
1152
each new module. Note that the order in which modules are added is important -- (A-B) \textsf{U }C is different to A-(B
1153
\textsf{U }C).\\\hline
1154
{\itshape BooleanModuleNType} &
1155
\multicolumn{1}{m{1.333cm}}{string} &
1156
\\\hhline{--~}
1157
{\itshape BooleanModuleNPos} &
1158
\multicolumn{1}{m{1.333cm}}{Hep3
1159
1160
Vector} &
1161
\\\hhline{--~}
1162
{\itshape BooleanModuleNRot} &
1163
\multicolumn{1}{m{1.333cm}}{Hep3
1164
1165
Vector} &
1166
\\\hhline{--~}
1167
\end{supertabular}
1168
\end{center}
1169
\subsubsection{Volume Sphere}
1170
A sphere is a spherical shell, with options for opening angles to make segments.
1171
1172
\begin{center}
1173
\tablefirsthead{\hline
1174
{\bfseries Property} &
1175
{\bfseries Type} &
1176
{\bfseries Description}\\}
1177
\tablehead{\hline
1178
{\bfseries Property} &
1179
{\bfseries Type} &
1180
{\bfseries Description}\\}
1181
\tabletail{}
1182
\tablelasttail{}
1183
\begin{supertabular}{|m{3.89cm}|m{1.333cm}|m{11.772cm}|}
1184
\hline
1185
{\itshape Dimensions} &
1186
Hep3
1187
1188
Vector &
1189
The x value defines the inner radius. The y value defines the outer radius of the shell. The z value is not
1190
used.\\\hline
1191
Phi &
1192
Hep3
1193
1194
Vector &
1195
The x value defines the start opening angle in phi. The y value defines the end opening angle. The z value is not used.
1196
Phi values must be in the range 0 to 360 degrees. If undefined, defaults to the range 0-360 degrees.\\\hline
1197
Theta &
1198
Hep3
1199
1200
Vector &
1201
The x value defines the start opening angle in theta. The y value defines the end opening angle. The z value is not
1202
used. Theta values must be in the range 0 to 180 degrees. If undefined, defaults to the range 0-360 degrees.\\\hline
1203
\end{supertabular}
1204
\end{center}
1205
\clearpage\subsection{Repeating Modules}
1206
It is possible to set up a repeating structure for e.g. a repeating magnet lattice. The RepeatModule property enables
1207
the user to specify that a particular module will be repeated a number of times, with all properties passed onto the
1208
child module, but with a new position, orientation and scale factor. Each successive repetition will be given a
1209
translation and a rotation relative to the coordinate system of the previous repetition, enabling the construction of
1210
circular and straight accelerator lattices. Additionally, successive repetitions can have fields scaled relative to
1211
previous repetitions, enabling for example alternating lattices.
1212
1213
\begin{center}
1214
\tablefirsthead{\hline
1215
{\bfseries Property} &
1216
{\bfseries Type} &
1217
{\bfseries Description}\\}
1218
\tablehead{\hline
1219
{\bfseries Property} &
1220
{\bfseries Type} &
1221
{\bfseries Description}\\}
1222
\tabletail{}
1223
\tablelasttail{}
1224
\begin{supertabular}{|m{3.892cm}|m{1.333cm}|m{11.77cm}|}
1225
\hline
1226
{\itshape RepeatModule} &
1227
bool &
1228
Set to 1 to enable repeats in this module.\\\hline
1229
{\itshape NumberOfRepeats} &
1230
int &
1231
Number of times the module will be repeated in addition to the initial placement.\\\hline
1232
{\itshape RepeatTranslation} &
1233
Hep3
1234
1235
Vector &
1236
Translation applied to successive repeats, applied in the coordinate system of the previous repetition.\\\hline
1237
{\itshape RepeatRotation} &
1238
Hep3
1239
1240
Vector &
1241
Rotation applied to successive repeats, applied in the coordinate system of the previous repetition.\\\hline
1242
{\itshape RepeatScaleFactor} &
1243
double &
1244
ScaleFactor applied to successive repeats, applied relative to previous repetition's scale factor.\\\hline
1245
\end{supertabular}
1246
\end{center}
1247
The RepeatModule2 property also enables the user to specify that a particular module will be repeated a number of times.
1248
In this case, G4MICE will set a substitution variable @RepeatNumber that holds an index between 0 and NumberOfRepeats.
1249
This can be used in an expression in to provide a versatile interface between user and accelerator lattice.
1250
1251
\begin{center}
1252
\tablefirsthead{\hline
1253
{\bfseries Property} &
1254
{\bfseries Type} &
1255
{\bfseries Description}\\}
1256
\tablehead{\hline
1257
{\bfseries Property} &
1258
{\bfseries Type} &
1259
{\bfseries Description}\\}
1260
\tabletail{}
1261
\tablelasttail{}
1262
\begin{supertabular}{|m{3.892cm}|m{1.333cm}|m{11.77cm}|}
1263
\hline
1264
{\itshape RepeatModule2} &
1265
bool &
1266
Set to 1 to enable repeats in this module.\\\hline
1267
{\itshape NumberOfRepeats} &
1268
int &
1269
Number of times the module will be repeated in addition to the initial placement.\\\hline
1270
\end{supertabular}
1271
\end{center}
1272
\subsection{}
1273
\clearpage\subsection{Beam Definition and Beam Envelopes}
1274
The Optics application can be used to track a trajectory and associated beam envelope through the accelerator structure.
1275
Optics works by finding the Jacobian around some arbitrary trajectory using a numerical differentiation. This is used
1276
to define a linear mapping about this trajectory, which can then be used to transport the beam envelope.
1277
1278
The Simulation application can be used to generate a random particle beam with a Gaussian distribution and RMS
1279
parameters defined in the same way as the Optics beam envelope. Alternatively, pencil beams and beams from some input
1280
file can also be defined here.
1281
1282
A beam envelope is defined by a reference trajectory and a beam ellipse. The reference trajectory takes its position and
1283
direction from the position and rotation of the module. No rotation builds a reference trajectory along the z-axis. The
1284
magnitude of the momentum and the initial time of the reference trajectory is defined by properties. RF cavities are
1285
phased using the reference trajectory defined here.
1286
1287
The beam ellipse is represented by a matrix, which can either be set using
1288
1289
\liststyleLxii
1290
\begin{itemize}
1291
\item Twiss-style parameters in (x,px),(y,py) and (t,E) spaces.
1292
\item Twiss-style parameters in (t,E) space and Penn-style parameters in a cylindrically symmetric (x,px,y,py) space.
1293
\item A 6x6 beam ellipse matrix where the ellipse equation is given by \textbf{X}.\textbf{T}() \textbf{M} \textbf{X} =
1294
1.
1295
\end{itemize}
1296
The Penn ellipse matrix is given by
1297
1298
\begin{equation*}
1299
M=\left(\begin{matrix}\epsilon _Lmc\frac{\beta _L}{p}&-\epsilon _Lmc\alpha _L&0&0&0&0\\&\epsilon _Lmc\gamma
1300
_Lp&\frac{D_x}{E}V(E)&\frac{D_x'}{E}V(E)&\frac{D_y}{E}V(E)&\frac{D_y'}{E}V(E)\\&&\epsilon _Tmc\frac{\beta _T}{p}&-\epsilon
1301
_Tmc\alpha _T&0&-\epsilon _Tmc(\frac{q}{2}\beta _T\frac{B_z}{P}-L)\\&&&\epsilon _Tmc\gamma _Tp&\epsilon _Tmc(\frac{q}{
1302
2}\beta _T\frac{B_z}{P}-L)&0\\&&&&\epsilon _Tmc\frac{\beta _T}{p}&-\epsilon _Tmc\alpha _T\\&&&&&\epsilon _Lmc\gamma
1303
_Tp\end{matrix}\right)
1304
\end{equation*}
1305
Here L is a normalised canonical angular momentum, \textit{q} is the reference particle charge,
1306
\textit{B}\textit{\textsubscript{z}} is the nominal on-axis magnetic field, \textit{p} is the reference momentum,
1307
\textit{m} is the reference mass, e\textsubscript{T} is the transverse emittance, b\textsubscript{T} and
1308
a\textsubscript{T} are the transverse Twiss-like functions, e\textsubscript{L} is the longitudinal emittance and
1309
b\textsubscript{L} and a\textsubscript{L} are the longitudinal Twiss-like functions. Additionally D\textsubscript{x},
1310
D\textsubscript{y}, D'\textsubscript{x}, D'\textsubscript{y} are the dispersions and their derivatives with respect to
1311
z and V(E) is the variance of energy (given by the (2,2) term in the matrix above).
1312
1313
The Twiss ellipse matrix is given by
1314
1315
\begin{equation*}
1316
M=\left(\begin{matrix}\epsilon _Lmc\frac{\beta _L}{p}&-\epsilon _Lmc\alpha _L&0&0&0&0\\&\epsilon _Lmc\gamma
1317
_Lp&\frac{D_x}{E}V(E)&\frac{D_x'}{E}V(E)&\frac{D_y}{E}V(E)&\frac{D_y'}{E}V(E)\\&&\epsilon _xmc\frac{\beta _x}{p}&-\epsilon
1318
_xmc\alpha _x&0&0\\&&&\epsilon _xmc\gamma _xp&0&0\\&&&&\epsilon _ymc\frac{\beta _y}{p}&-\epsilon _ymc\alpha
1319
_y\\&&&&&\epsilon _ymc\gamma _yp\end{matrix}\right)
1320
\end{equation*}
1321
Here \textit{p} is the reference momentum, \textit{m} is the reference mass, e\textsubscript{i}, b\textsubscript{i} and
1322
a\textsubscript{i} are the emittances and Twiss functions in the (t,E), (x,p\textsubscript{x}) and
1323
(y,p\textsubscript{y}) planes respectively, D\textsubscript{x}, D\textsubscript{y}, D'\textsubscript{x},
1324
D'\textsubscript{y} are the dispersions and their derivatives with respect to z and V(E) is the variance of energy
1325
(given by the (2,2) term in the matrix above).
1326
1327
\begin{center}
1328
\tablefirsthead{\hline
1329
{\bfseries Property} &
1330
{\bfseries Type} &
1331
{\bfseries Description}\\}
1332
\tablehead{\hline
1333
{\bfseries Property} &
1334
{\bfseries Type} &
1335
{\bfseries Description}\\}
1336
\tabletail{}
1337
\tablelasttail{}
1338
\begin{supertabular}{|m{3.319cm}|m{1.2019999cm}|m{11.974cm}|}
1339
\hline
1340
{\itshape EnvelopeType} &
1341
string &
1342
Set to \textit{TrackingDerivative} to evolve a beam envelope in the Optics application.\\\hline
1343
{\itshape BeamType} &
1344
string &
1345
Set to \textit{Random} to generate a beam using the parameters below for the Simulation application. Set to
1346
\textit{Pencil }to generate a pencil beam (with no random distribution). Set to \textit{ICOOL}, \textit{Turtle,
1347
G4MICE\_PrimaryGenHit} or \textit{G4BeamLine} to use a beam file.\\\hline
1348
{\itshape Pid} &
1349
int &
1350
The particle ID of particles in the envelope or beam.\\\hline
1351
{\itshape Longitudinal}
1352
1353
{\itshape Variable} &
1354
string &
1355
Set the longitudinal variable used to define the reference trajectory momentum. Options are \textit{Energy},
1356
\textit{KineticEnergy, Momentum} and\textit{ ZMomentum.}\\\hline
1357
\multicolumn{1}{m{3.319cm}}{\hspace*{-\tabcolsep}\begin{tabular}{|m{3.319cm}}
1358
1359
Energy\\\hline
1360
KineticEnergy\\\hline
1361
Momentum\\\hline
1362
ZMomentum\\\hline
1363
\end{tabular}\hspace*{-\tabcolsep}
1364
} &
1365
\hspace*{-\tabcolsep}\begin{tabular}{|m{1.2019999cm}}
1366
1367
double\\\hline
1368
double\\\hline
1369
double\\\hline
1370
double\\\hline
1371
\end{tabular}\hspace*{-\tabcolsep}
1372
&
1373
Define the value of the longitudinal variable used to calculate the mean momentum and energy. The usual relationship
1374
E\textsuperscript{2}+p\textsuperscript{2}c\textsuperscript{2}=m\textsuperscript{2}c\textsuperscript{4} applies. Kinetic
1375
energy E\textsubscript{k} is related to energy E by E\textsubscript{k}+m=E.\\\hhline{~~-}
1376
{\itshape EllipseDefinition} &
1377
string &
1378
Define the beam ellipse that will be used in calculating the evolution of the Envelope, or used to generate a beam for
1379
BeamType \textit{Random}. Options are \textit{Twiss, Penn} and\textit{ Matrix}.\\\hline
1380
\multicolumn{3}{|m{16.894999cm}|}{{\itshape The following properties are only used if EllipseDefinition is set to
1381
Twiss}}\\\hline
1382
\multicolumn{2}{m{4.721cm}|}{\hspace*{-\tabcolsep}\begin{tabular}{|m{3.319cm}|m{1.2019999cm}}
1383
1384
{\itshape Emittance\_X} &
1385
double\\\hline
1386
{\itshape Emittance\_Y} &
1387
double\\\hline
1388
{\itshape Emittance\_L} &
1389
double\\\hline
1390
\end{tabular}\hspace*{-\tabcolsep}
1391
} &
1392
Emittance in each 2d subspace, (x,px), (y,py) and (t,E).\\\hhline{~~-}
1393
\multicolumn{2}{m{4.721cm}|}{\hspace*{-\tabcolsep}\begin{tabular}{|m{3.319cm}|m{1.2019999cm}}
1394
1395
{\itshape Beta\_X} &
1396
double\\\hline
1397
{\itshape Beta\_Y} &
1398
double\\\hline
1399
{\itshape Beta\_L} &
1400
double\\\hline
1401
\end{tabular}\hspace*{-\tabcolsep}
1402
} &
1403
Twiss b function in each 2d subspace, (x,px), (y,py) and (t,E).\\\hhline{~~-}
1404
\multicolumn{2}{m{4.721cm}|}{\hspace*{-\tabcolsep}\begin{tabular}{|m{3.319cm}|m{1.2019999cm}}
1405
1406
{\itshape Alpha\_X} &
1407
double\\\hline
1408
{\itshape Alpha\_Y} &
1409
double\\\hline
1410
{\itshape Alpha\_L} &
1411
double\\\hline
1412
\end{tabular}\hspace*{-\tabcolsep}
1413
} &
1414
Twiss a function in each 2d subspace, (x,px), (y,py) and (t,E).\\\hhline{~~-}
1415
\multicolumn{3}{|m{16.894999cm}|}{{\itshape The following properties are only used if EllipseDefinition is set to
1416
Matrix}}\\\hline
1417
\multicolumn{2}{m{4.721cm}|}{\hspace*{-\tabcolsep}\begin{tabular}{|m{3.319cm}|m{1.2019999cm}}
1418
1419
{\itshape Covariance(t,t)} &
1420
double\\\hline
1421
{\itshape Covariance(t,E)} &
1422
double\\\hline
1423
{\itshape Covariance(t,x)} &
1424
double\\\hline
1425
{\itshape ...} &
1426
double\\\hline
1427
{\itshape Covariance(Py,Py)} &
1428
double\\\hline
1429
\end{tabular}\hspace*{-\tabcolsep}
1430
} &
1431
Set the 6x6 matrix that will be used in the to define the beam ellipse. Covariances should be covariances of elements of
1432
the matrix (x,Px,y,Py,t,E).
1433
1434
\ This must be a positive definite matrix, i.e. determinant {\textgreater} 0. Note that this means that at least the 6
1435
terms on the diagonal must be defined. Other terms default to 0.\\\hline
1436
\multicolumn{3}{|m{16.894999cm}|}{{\itshape The following properties are only used if EllipseDefinition is set to
1437
Penn}}\\\hline
1438
{\itshape Emittance\_T} &
1439
double &
1440
Transverse emittance for the 4d (x,px,y,py) subspace.\\\hline
1441
{\itshape Emittance\_L} &
1442
double &
1443
Longitudinal emittance for the 2d (t,E) subspace.\\\hline
1444
{\itshape Beta\_T} &
1445
double &
1446
Transverse beta for the 4d (x,px,y,py) subspace.\\\hline
1447
{\itshape Beta\_L} &
1448
double &
1449
Longitudinal beta for the 2d (t,E) subspace.\\\hline
1450
{\itshape Alpha\_T} &
1451
double &
1452
Transverse alpha for the 4d (x,px,y,py) subspace.\\\hline
1453
{\itshape Alpha\_L} &
1454
double &
1455
Longitudinal alpha for the 2d (t,E) subspace.\\\hline
1456
{\itshape Normalised}
1457
1458
{\itshape AngularMomentu} &
1459
double &
1460
Normalised angular momentum for the transverse phase space.\\\hline
1461
Bz &
1462
double &
1463
Nominal magnetic field on the reference particle.\\\hline
1464
\multicolumn{3}{|m{16.894999cm}|}{{\itshape The following properties are used if EllipseDefinition is set to Penn or
1465
Twiss}}\\\hline
1466
Dispersion\_X &
1467
double &
1468
Dispersion in x (x-energy correlation).\\\hline
1469
Dispersion\_Y &
1470
double &
1471
Dispersion in y (y-energy correlation).\\\hline
1472
DispersionPrime\_X &
1473
double &
1474
D' in x (Px-energy correlation).\\\hline
1475
DispersionPrime\_Y &
1476
double &
1477
D' in y (Py-energy correlation).\\\hline
1478
\multicolumn{3}{|m{16.894999cm}|}{{\itshape The following properties are only relevant for generating a beam
1479
envelope}}\\\hline
1480
RootOutput &
1481
string &
1482
Output file name for writing output beam envelope in ROOT binary format.\\\hline
1483
LongTextOutput &
1484
string &
1485
Output file name for writing output beam envelope in string format.\\\hline
1486
ShortTextOutput &
1487
string &
1488
Output file name for writing output beam envelope in string format. This abbreviated output omits some of the fields
1489
that are present in LongTextOutput files.\\\hline
1490
BeamOutput &
1491
string &
1492
If a BeamType is defined, this property controls the file name to which beam data is written.\\\hline
1493
Delta\_t &
1494
double &
1495
Offset in time used for calculating numerical derivatives. Default is 0.1 ns.\\\hline
1496
Delta\_E &
1497
double &
1498
Offset in energy used for calculating numerical derivatives. Default is 1 MeV.\\\hline
1499
Delta\_x &
1500
double &
1501
Offset in x position used for calculating numerical derivatives. Default is 1 mm.\\\hline
1502
Delta\_Px &
1503
double &
1504
Offset in x momentum used for calculating numerical derivatives. Default is 1 MeV/c.\\\hline
1505
Delta\_y &
1506
double &
1507
Offset in y position used for calculating numerical derivatives. Default is 1 mm.\\\hline
1508
Delta\_Py &
1509
double &
1510
Offset in y momentum used for calculating numerical derivatives. Default is 1 MeV/c.\\\hline
1511
\multicolumn{2}{m{4.721cm}|}{\hspace*{-\tabcolsep}\begin{tabular}{|m{3.319cm}|m{1.2019999cm}}
1512
1513
Max\_Delta\_t &
1514
double\\\hline
1515
Max\_Delta\_E &
1516
double\\\hline
1517
Max\_Delta\_x &
1518
double\\\hline
1519
Max\_Delta\_Px &
1520
double\\\hline
1521
Max\_Delta\_y &
1522
double\\\hline
1523
Max\_Delta\_Py &
1524
double\\\hline
1525
\end{tabular}\hspace*{-\tabcolsep}
1526
} &
1527
Maximum offsets when polyfit algorithm is used. In some cases the offset can keep increasing without limit unless these
1528
maximum offsets are defined. Default is no limit.\\\hhline{~~-}
1529
\multicolumn{3}{|m{16.894999cm}|}{{\itshape The following properties are only relevant for generating a particle
1530
beam}}\\\hline
1531
UseAsReference &
1532
Bool &
1533
If set to true and the datacard \textit{FirstParticleIsReference} is set to 0, the first event in the Module will be
1534
used as the reference particle that sets cavity phases. This particle will then have the mean trajectory (i.e. no
1535
gaussian distribution).\\\hline
1536
{\itshape BeamFile} &
1537
string &
1538
If the BeamType is \textit{ICOOL}, \textit{Turtle, G4MICE\_PrimaryGenHit} or \textit{G4BeamLine}, this property defines
1539
the name of the file containing tracks for G4MICE.\\\hline
1540
NumberOfEvents &
1541
int &
1542
Set the maximum number of events to take from this module. If other modules are defined, G4MICE will iterate over the
1543
modules until it the datacard \textit{numEvts} is reached or all modules have been run to \textit{NumberOfEvents}.
1544
Default is for G4MICE to keep tracking from the first module it finds until \textit{numEvts} is reached.\\\hline
1545
\end{supertabular}
1546
\end{center}
1547
\subsection{Optimiser}
1548
It is possible to define an optimiser for use in the Optics application. The optimiser enables the user to vary
1549
parameters in the MiceModule file and try to find some optimum setting. For each value of the parameters, G4MICE Optics
1550
will calculate a score; the optimiser attempts to find a minimum value for this score.
1551
1552
\begin{center}
1553
\tablefirsthead{\hline
1554
{\bfseries Property} &
1555
{\bfseries Type} &
1556
{\bfseries Description}\\}
1557
\tablehead{\hline
1558
{\bfseries Property} &
1559
{\bfseries Type} &
1560
{\bfseries Description}\\}
1561
\tabletail{}
1562
\tablelasttail{}
1563
\begin{supertabular}{|m{3.319cm}|m{1.2019999cm}|m{11.974cm}|}
1564
\hline
1565
{\itshape Optimiser} &
1566
string &
1567
Controls the function used for optimising. For now Minuit is the only available option.\\\hline
1568
{\itshape Algorithm} &
1569
string &
1570
For \textit{Minuit} optimiser, controls the \textit{Minuit} algorithm used. In general Simplex is a good option to use
1571
here. An alternative is Migrad. See Minuit documentation (for example at http://root.cern.ch/root/html/TMinuit.html)
1572
for further information. Minuit attempts to minimise the score function defined by the Score properties.\\\hline
1573
{\itshape NumberOfTries} &
1574
int &
1575
Maximum number of iterations G4MICE will make in order to find the optimum value.\\\hline
1576
{\itshape StartError} &
1577
double &
1578
Guess at the initial error in the score.\\\hline
1579
{\itshape EndError} &
1580
double &
1581
Required final error in the score for the optimisation to converge successfully.\\\hline
1582
RebuildSimulation &
1583
bool &
1584
Set to False to tell G4MICE not to rebuild the simulation on each iteration. This should be used to speed up the
1585
optimiser when a parameter is used that does not change the field maps. Default is true.\\\hline
1586
{\itshape Parameter1\_Start} &
1587
double &
1588
Seed value for the parameter, that is used in the first iteration.\\\hline
1589
{\itshape Parameter1\_Name} &
1590
string &
1591
Name of the parameter. This name is used as an expression substitution variable elsewhere in the code and should start
1592
with @. See Expression Substitutions above for details on usage of expression substitutions.\\\hline
1593
Parameter1\_Delta &
1594
double &
1595
Estimated initial error on the parameter. Default is 1.\\\hline
1596
Parameter1\_Fixed &
1597
bool &
1598
Set to true to fix the parameter (so that it is excluded from the optimisation). Default is false.\\\hline
1599
Parameter1\_Min &
1600
double &
1601
If required, set to the minimum value that the parameter can hold.\\\hline
1602
Parameter1\_Max &
1603
double &
1604
If required, set to the maximum value that the parameter can hold.\\\hline
1605
\multicolumn{2}{m{4.721cm}}{\hspace*{-\tabcolsep}\begin{tabular}{|m{3.319cm}|m{1.2019999cm}}
1606
1607
Parameter2\_Start &
1608
...\\\hline
1609
... &
1610
...\\\hline
1611
Parameter2\_Max &
1612
...\\\hline
1613
{\itshape Score1} &
1614
double\\\hline
1615
Score2 &
1616
...\\\hline
1617
... &
1618
...\\\hline
1619
\end{tabular}\hspace*{-\tabcolsep}
1620
} &
1621
\multicolumn{1}{m{11.974cm}}{\hspace*{-\tabcolsep}\begin{tabular}{|m{11.974cm}|}
1622
1623
Define an arbitrary number of parameters. Parameters must be numbered consecutively, and each parameter must have at
1624
least the start value and name defined.\\\hline
1625
The optimiser will attempt to optimise against a score that is calculated by summing the Score1, Score2,... parameters
1626
on each iteration.\\\hline
1627
\end{tabular}\hspace*{-\tabcolsep}
1628
}\\
1629
\end{supertabular}
1630
\end{center}
1631
\clearpage\section{Field Properties}
1632
Invoke a field using PropertyString FieldType {\textless}fieldtype{\textgreater}. The field will be placed, normally
1633
centred on the MiceModule Position and with the appropriate Rotation. Further options for each field type are specified
1634
below, and relevant datacards are also given. If a fieldtype is specified some other properties must also be specified,
1635
while others may be optional, usually taking their value from defaults specified in the datacards. Only one fieldtype
1636
can be specified per module. However, fields from multiple modules are superimposed, each transformed according to the
1637
MiceModule specification. This enables many different field configurations to be simulated using G4MICE.
1638
1639
To use BeamTools fields, datacard FieldMode Full must be set. This is the default.
1640
1641
\begin{center}
1642
\tablefirsthead{\hline
1643
{\bfseries Property} &
1644
{\bfseries Type} &
1645
{\bfseries Description}\\}
1646
\tablehead{\hline
1647
{\bfseries Property} &
1648
{\bfseries Type} &
1649
{\bfseries Description}\\}
1650
\tabletail{}
1651
\tablelasttail{}
1652
\begin{supertabular}{|m{3.665cm}|m{1.278cm}|m{12.052cm}|}
1653
\hline
1654
{\itshape FieldType} &
1655
string &
1656
Set the field type of the MiceModule.\\\hline
1657
\end{supertabular}
1658
\end{center}
1659
\subsection{FieldType CylindricalField}
1660
Sets a constant magnetic field in a cylindrical region symmetric about the z-axis of the module.
1661
1662
\begin{center}
1663
\tablefirsthead{\hline
1664
{\bfseries Property} &
1665
{\bfseries Type} &
1666
{\bfseries Description}\\}
1667
\tablehead{\hline
1668
{\bfseries Property} &
1669
{\bfseries Type} &
1670
{\bfseries Description}\\}
1671
\tabletail{}
1672
\tablelasttail{}
1673
\begin{supertabular}{|m{3.665cm}|m{1.278cm}|m{12.052cm}|}
1674
\hline
1675
{\itshape ConstantField} &
1676
Hep3
1677
1678
Vector &
1679
The magnetic field that will be placed in the region.\\\hline
1680
\multicolumn{2}{m{5.143cm}|}{\hspace*{-\tabcolsep}\begin{tabular}{|m{3.665cm}|m{1.278cm}}
1681
1682
{\itshape Length} &
1683
double\\\hline
1684
{\itshape Radius} &
1685
double\\\hline
1686
\end{tabular}\hspace*{-\tabcolsep}
1687
} &
1688
The physical extent of the region.\\\hhline{~~-}
1689
\end{supertabular}
1690
\end{center}
1691
\subsection{FieldType RectangularField}
1692
Sets a constant magnetic field in a rectangular region.
1693
1694
\begin{center}
1695
\tablefirsthead{\hline
1696
{\bfseries Property} &
1697
{\bfseries Type} &
1698
{\bfseries Description}\\}
1699
\tablehead{\hline
1700
{\bfseries Property} &
1701
{\bfseries Type} &
1702
{\bfseries Description}\\}
1703
\tabletail{}
1704
\tablelasttail{}
1705
\begin{supertabular}{|m{3.665cm}|m{1.278cm}|m{12.052cm}|}
1706
\hline
1707
{\itshape ConstantField} &
1708
Hep3
1709
1710
Vector &
1711
The magnetic field that will be placed in the region.\\\hline
1712
\multicolumn{2}{m{5.143cm}|}{\hspace*{-\tabcolsep}\begin{tabular}{|m{3.665cm}|m{1.278cm}}
1713
1714
{\itshape Length} &
1715
double\\\hline
1716
{\itshape Width} &
1717
double\\\hline
1718
{\itshape Height} &
1719
double\\\hline
1720
\end{tabular}\hspace*{-\tabcolsep}
1721
} &
1722
The physical extent of the region.\\\hhline{~~-}
1723
\end{supertabular}
1724
\end{center}
1725
\subsection{FieldType Solenoid}
1726
G4MICE simulates solenoids using a series of current sheets. The field for each solenoid is written to a field map on a
1727
rectangular grid and can then be reused. The field from each current sheet is calculated using the formula for current
1728
sheets detailed in MUCOOL Note 281, \textit{Modeling solenoids using coil, sheet and block conductors}.
1729
1730
\begin{center}
1731
\tablefirsthead{\hline
1732
{\bfseries Property} &
1733
{\bfseries Type} &
1734
{\bfseries Description}\\}
1735
\tablehead{\hline
1736
{\bfseries Property} &
1737
{\bfseries Type} &
1738
{\bfseries Description}\\}
1739
\tabletail{}
1740
\tablelasttail{}
1741
\begin{supertabular}{|m{3.665cm}|m{1.278cm}|m{12.052cm}|}
1742
\hline
1743
{\itshape FileName} &
1744
string &
1745
Read or write solenoid data to the filename. If different modules have the same filename, G4MICE assumes they are the
1746
same.\\\hline
1747
FieldMapMode &
1748
string &
1749
If set to Read, G4MICE will attempt to read existing data from the FileName. If set to Write, G4MICE will generate new
1750
data and write it to the FileName. If set to Analytic, G4MICE will calculate fields directly without interpolating. If
1751
set to WriteDynamic acts as in Write except the grid extent and grid spacing at each point is chosen dynamically to
1752
some tolerance defined in the FieldTolerance property. Takes default from datacard SolDataFiles (Write).\\\hline
1753
\multicolumn{2}{m{5.143cm}|}{\hspace*{-\tabcolsep}\begin{tabular}{|m{3.665cm}|m{1.278cm}}
1754
1755
{\itshape Length} &
1756
double\\\hline
1757
{\itshape Thickness} &
1758
double\\\hline
1759
{\itshape InnerRadius} &
1760
double\\\hline
1761
{\itshape CurrentDensity} &
1762
double\\\hline
1763
\end{tabular}\hspace*{-\tabcolsep}
1764
} &
1765
Coil physical parameters. Only used in Write/Analytic mode where they are mandatory.\\\hhline{~~-}
1766
ZExtentFactor &
1767
double &
1768
Field map extends to length + ZExtentFactor*innerRadius in Write mode. Takes default from datacard SolzMapExtendFactor
1769
(10.). Map size is chosen dynamically in WriteDynamic mode.\\\hline
1770
RExtentFactor &
1771
double &
1772
Field map extends to radius RExtentFactor*innerRadius in Write mode. Takes default from datacard SolrMapExtendFactor
1773
(2.018...). Avoid allowing grid nodes to fall on sheets.\\\hline
1774
NumberOfZCoords &
1775
int &
1776
Number of coordinates in \textit{z} in field map grid in Write mode. Takes default from datacard NumberNodesZGrid
1777
(500).\\\hline
1778
NumberOfRCoords &
1779
int &
1780
Number of coordintes in \textit{r} in field map grid in Write mode. Takes default from datacard NumberNodesRGrid
1781
(100).\\\hline
1782
NumberOfSheets &
1783
int &
1784
Number of sheets used to calculate the field. Takes default from datacard DefaultNumberOfSheets (10).\\\hline
1785
{\itshape FieldTolerance } &
1786
double &
1787
Mandatory when FieldMapMode is WriteDynamic. If field map mode is write dynamic, this datacard controls the tolerance on
1788
errors in the field with which the field grid and the grid extent will be chosen. \\\hline
1789
Interpolation
1790
1791
Algorithm &
1792
string &
1793
Choose the interpolation algorithm. Options are BiLinear for a linear interpolation in \textit{r} and \textit{z}, or
1794
LinearCubic \ for a linear interpolation in \textit{r} and a cubic spline in \textit{z}. Default is
1795
LinearCubic.\\\hline
1796
IsAmalgamated &
1797
bool &
1798
Set to 1 to add the coil to CoilAmalgamtion parent field (see below).\\\hline
1799
\end{supertabular}
1800
\end{center}
1801
\subsection{}
1802
\clearpage\subsection{FieldType FieldAmalgamation}
1803
During tracking, G4MICE stores a list of fields and for each one G4MICE checks to see if tracking is performed through a
1804
particular field map's bounding box. This can be slow if a large number of fields are present. One way to speed this up
1805
is to store contributions from many coils in a single CoilAmalgamation. A CoilAmalgamation searches through child
1806
modules for solenoids with PropertyBool IsAmalgamated set to true. If it finds such a coil, it will add the field
1807
generated by the solenoid to its own field map and disable the coil.
1808
1809
\begin{center}
1810
\tablefirsthead{\hline
1811
{\bfseries Property} &
1812
{\bfseries Type} &
1813
{\bfseries Description}\\}
1814
\tablehead{\hline
1815
{\bfseries Property} &
1816
{\bfseries Type} &
1817
{\bfseries Description}\\}
1818
\tabletail{}
1819
\tablelasttail{}
1820
\begin{supertabular}{|m{3.665cm}|m{1.278cm}|m{12.052cm}|}
1821
\hline
1822
{\itshape Length} &
1823
double &
1824
The Length of the field map generated by the CoilAmalgamation.\\\hline
1825
{\itshape RMax} &
1826
double &
1827
The maximum radius of the field map generated by the CoilAmalgamation.\\\hline
1828
Interpolation
1829
1830
Algorithm &
1831
string &
1832
Choose the interpolation algorithm. Options are BiLinear for a linear interpolation in \textit{r} and \textit{z}, or
1833
LinearCubic \ for a linear interpolation in \textit{r} and a cubic spline in \textit{z}. Default is
1834
LinearCubic.\\\hline
1835
\multicolumn{2}{m{5.143cm}|}{\hspace*{-\tabcolsep}\begin{tabular}{|m{3.665cm}|m{1.278cm}}
1836
1837
{\itshape ZStep} &
1838
double\\\hline
1839
{\itshape RStep} &
1840
double\\\hline
1841
\end{tabular}\hspace*{-\tabcolsep}
1842
} &
1843
Step size of the field map generated by the CoilAmalgamation.\\\hhline{~~-}
1844
\end{supertabular}
1845
\end{center}
1846
1847
\bigskip
1848
1849
\clearpage\subsection{FieldType FastSolenoid}
1850
This is an alternative field model for solenoids that uses a power law expansion of the on-axis magnetic field and its
1851
derivatives, and an exponential fall-off for the fringe field (tanh).
1852
1853
\begin{center}
1854
\tablefirsthead{\hline
1855
{\bfseries Property} &
1856
{\bfseries Type} &
1857
{\bfseries Description}\\}
1858
\tablehead{\hline
1859
{\bfseries Property} &
1860
{\bfseries Type} &
1861
{\bfseries Description}\\}
1862
\tabletail{}
1863
\tablelasttail{}
1864
\begin{supertabular}{|m{3.665cm}|m{1.278cm}|m{12.052cm}|}
1865
\hline
1866
{\itshape PeakField} &
1867
double &
1868
Nominal peak field of the solenoid.\\\hline
1869
{\itshape EFoldLength} &
1870
double &
1871
The fall-off length for the fringe field.\\\hline
1872
{\itshape CentreLength} &
1873
double &
1874
Nominal length for the peak field region.\\\hline
1875
{\itshape Order} &
1876
int &
1877
Order to which the field will be calculated.\\\hline
1878
FieldTolerance &
1879
double &
1880
If positive, G4MICE will abort tracking if a particle crosses through a field with estimated error {\textgreater}
1881
FieldTolerance. G4MICE estimates the error as the field value calculated at highest order. Default is -1 (i.e.
1882
inactive).\\\hline
1883
\end{supertabular}
1884
\end{center}
1885
\subsection{Phasing Models}
1886
G4MICE has a number of sophisticated models for phasing RF cavities. These powerful models can make setting up RF
1887
cavities with realistic fields both quick and easy.
1888
1889
When CavityMode is Unphased, G4MICE attempts to phase the cavity itself. When using CavityMode Unphased G4MICE needs to
1890
know when particles enter, cross the middle, and leave cavities. This means that:
1891
1892
\liststyleLxiii
1893
\begin{itemize}
1894
\item The cavity must sit in a rectangular or cylindrical physical volume.
1895
\item No other physical volumes may overlap or sit within the physical volume of the cavity.
1896
\end{itemize}
1897
If these conditions are not met the phasing algorithm is likely to fail.
1898
1899
To phase a cavity, G4MICE builds a volume in the centre of the cavity that is used for phasing and then fires a
1900
reference particle through the system. Stochastic processes are always disabled during this process, while mean energy
1901
loss can be disabled using the datacard ReferenceEnergyLossModel. If a reference particle crosses a plane through the
1902
centre of a cavity, it sets the phase of the cavity to the time at which the particle crosses.
1903
1904
The field of the cavity during phasing is controlled by the property FieldDuringPhasing. There are four modes:
1905
1906
\liststyleLxiv
1907
\begin{itemize}
1908
\item \textit{None}: Cavity fields are disabled during phasing
1909
\item \textit{Electrostatic}: An electrostatic field with no positional dependence given by
1910
PeakEField*sin(ReferenceParticlePhase) is enabled during phasing.
1911
\item \textit{TimeVarying}: A standard time varying field is applied during phasing, initially with arbitrary phase
1912
relative to the reference particle. G4MICE uses a Newton-Raphson method to find the appropriate reference phase
1913
iteratively, with tolerance set by the datacard PhaseTolerance.
1914
\item \textit{EnergyGainOptimised}: A standard time varying field is applied during phasing, initially with arbitrary
1915
phase and peak field relative to the reference particle. G4MICE uses a 2D Newton-Raphson method to find the appropriate
1916
reference phase and peak field iteratively, so that the reference particle crosses the cavity centre with phase given
1917
by property ReferenceParticlePhase and gains energy over the whole cavity given by property EnergyGain with tolerances
1918
set by the datacards PhaseTolerance and RFDeltaEnergyTolerance.
1919
\end{itemize}
1920
\subsection{Tracking Stability Around RF Cavities}
1921
Usually RF cavities have little or no fringe field, and this can lead to some instability in the tracking algorithms.
1922
When G4MICE makes a step into an RF cavity volume, the tracking algorithms tend to smooth out a field in a non-physical
1923
way. This can be prevented by either (i) making the step size rather small in the RF cavity or (ii) forcing G4MICE to
1924
stop tracking by adding a physical volume at the entrance of the RF cavity (a window, typically made of vacuum). Doing
1925
this should improve stability of tracking.
1926
1927
\subsection{FieldType PillBox}
1928
Sets a PillBox field in a particular region. G4MICE represents pillboxes using a sinusoidally varying TM010 pill box
1929
field, with non-zero field vector elements given by
1930
1931
\begin{equation*}
1932
\begin{gathered}B_{\phi }=J_1(k_rr)\cos (\omega t)\\E_z=J_0(k_rr)\cos (\omega t)\end{gathered}
1933
\end{equation*}
1934
Here J\textsubscript{n} are Bessel functions and k\textsubscript{r} is a constant. See, for example, SY Lee VI.1. All
1935
other fields are 0.
1936
1937
\begin{center}
1938
\tablefirsthead{\hline
1939
{\bfseries Property} &
1940
{\bfseries Type} &
1941
{\bfseries Description}\\}
1942
\tablehead{\hline
1943
{\bfseries Property} &
1944
{\bfseries Type} &
1945
{\bfseries Description}\\}
1946
\tabletail{}
1947
\tablelasttail{}
1948
\begin{supertabular}{|m{3.665cm}|m{1.278cm}|m{12.052cm}|}
1949
\hline
1950
{\itshape Length} &
1951
double &
1952
Length of the region in which the field is present.\\\hline
1953
{\itshape CavityMode} &
1954
string &
1955
Phasing mode of the cavity - options are Phased, Unphased and Electrostatic.\\\hline
1956
{\itshape FieldDuringPhasing} &
1957
string &
1958
Controls the field during cavity phasing -- options are None, Electrostatic, TimeVarying and
1959
EnergyGainOptimised.\\\hline
1960
{\itshape EnergyGain} &
1961
double &
1962
WhenFieldDuringPhasing is set to EnergyGainOptimised, controls the peak electric field.\\\hline
1963
{\itshape Frequency} &
1964
double &
1965
The cavity frequency.\\\hline
1966
{\itshape PeakEField} &
1967
double &
1968
The peak field of the cavity. Not used when the FieldDuringPhasing is EnergyGainOptimised.\\\hline
1969
{\itshape TimeDelay} &
1970
double &
1971
In Phased mode the time delay (absolute time) of the cavity.\\\hline
1972
PhasingVolume &
1973
string &
1974
Set to SpecialVirtual to make the central volume a special virtual.\\\hline
1975
\multicolumn{2}{m{5.143cm}|}{\hspace*{-\tabcolsep}\begin{tabular}{|m{3.665cm}|m{1.278cm}}
1976
1977
ReferenceParticle
1978
1979
Energy &
1980
double\\\hline
1981
ReferenceParticle
1982
1983
Charge &
1984
double\\\hline
1985
\end{tabular}\hspace*{-\tabcolsep}
1986
} &
1987
In Electrostatic mode, G4MICE calculates the peak field and the field the reference particle sees using a combination of
1988
the reference particle energy, charge and phase. Take defaults from datacards NominalKineticEnergy and MuonCharge
1989
\\\hhline{~~-}
1990
ReferenceParticle
1991
1992
Phase &
1993
double &
1994
G4MICE tries to phase the field so that the reference particle crosses the cavity at ReferenceParticlePhase (units are
1995
angular). 0\textsuperscript{o} corresponds to no energy gain, 90\textsuperscript{o} corresponds to operation on-crest.
1996
Default from datacard rfAcclerationPhase.\\\hline
1997
\end{supertabular}
1998
\end{center}
1999
\subsection{FieldType RFFieldMap}
2000
Sets a cavity with an RF field map in a particular region. RFFieldMap uses the same phasing algorithm as described
2001
above.
2002
2003
\begin{center}
2004
\tablefirsthead{\hline
2005
{\bfseries Property} &
2006
{\bfseries Type} &
2007
{\bfseries Description}\\}
2008
\tablehead{\hline
2009
{\bfseries Property} &
2010
{\bfseries Type} &
2011
{\bfseries Description}\\}
2012
\tabletail{}
2013
\tablelasttail{}
2014
\begin{supertabular}{|m{3.665cm}|m{1.278cm}|m{12.052cm}|}
2015
\hline
2016
{\itshape Length} &
2017
double &
2018
Length of the region in which the field is present.\\\hline
2019
{\itshape CavityMode} &
2020
string &
2021
Phasing mode of the cavity - options are Phased and Unphased. RFFieldMaps cannot operated in Electrostatic mode.\\\hline
2022
{\itshape FieldDuringPhasing} &
2023
string &
2024
Controls the field during cavity phasing -- options are None, Electrostatic, TimeVarying and
2025
EnergyGainOptimised.\\\hline
2026
{\itshape EnergyGain} &
2027
double &
2028
WhenFieldDuringPhasing is set to EnergyGainOptimised, controls the peak electric field.\\\hline
2029
{\itshape Frequency} &
2030
double &
2031
The cavity frequency.\\\hline
2032
{\itshape PeakEField} &
2033
double &
2034
The peak field of the cavity. Not used when the FieldDuringPhasing is EnergyGainOptimised.\\\hline
2035
{\itshape TimeDelay} &
2036
double &
2037
In Phased mode the time delay (absolute time) of the cavity.\\\hline
2038
PhasingVolume &
2039
string &
2040
Set to SpecialVirtual to make the central volume a special virtual.\\\hline
2041
\multicolumn{2}{m{5.143cm}|}{\hspace*{-\tabcolsep}\begin{tabular}{|m{3.665cm}|m{1.278cm}}
2042
2043
ReferenceParticle
2044
2045
Energy &
2046
double\\\hline
2047
ReferenceParticle
2048
2049
Charge &
2050
double\\\hline
2051
\end{tabular}\hspace*{-\tabcolsep}
2052
} &
2053
In Electrostatic mode, G4MICE calculates the peak. field and the field the reference particle sees using a combination
2054
of the reference particle energy, charge and phase. Take defaults from datacards NominalKineticEnergy and MuonCharge
2055
\\\hhline{~~-}
2056
ReferenceParticle
2057
2058
Phase &
2059
double &
2060
G4MICE tries to phase the field so that the reference particle crosses the cavity at ReferenceParticlePhase (units are
2061
angular). 0\textsuperscript{o} corresponds to no energy gain, 90\textsuperscript{o} corresponds to operation on-crest.
2062
Default from datacard rfAcclerationPhase.\\\hline
2063
{\itshape FileName} &
2064
string &
2065
The file name of the field map file.\\\hline
2066
{\itshape FileType} &
2067
string &
2068
The file type of the field map. Only supported option is SuperFishSF7.\\\hline
2069
\end{supertabular}
2070
\end{center}
2071
\subsection{}
2072
\clearpage\subsection{FieldType Multipole}
2073
Creates a multipole of arbitrary order. Fields are generated using either a hard edged model, with no fringe fields at
2074
all; or an Enge model similar to ZGoubi and COSY. In the former case fields are calculated using a simple polynomial
2075
expansion. In the latter case fields are calculated using the polynomial expansion with an additional exponential drop
2076
off. Fields can be superimposed onto a bent coordinate system to generate a sector multipole with arbitrary fixed
2077
radius of curvature.
2078
2079
Unlike most other field models in G4MICE, the zero position corresponds to the center of the entrance of the multipole;
2080
and the multipole extends in the +z direction.
2081
2082
The method to define end fields is described in the section EndFieldTypes below
2083
2084
\begin{center}
2085
\tablefirsthead{\hline
2086
{\bfseries Property} &
2087
{\bfseries Type} &
2088
{\bfseries Description}\\}
2089
\tablehead{\hline
2090
{\bfseries Property} &
2091
{\bfseries Type} &
2092
{\bfseries Description}\\}
2093
\tabletail{}
2094
\tablelasttail{}
2095
\begin{supertabular}{|m{3.691cm}|m{1.252cm}|m{12.052cm}|}
2096
\hline
2097
{\itshape Pole} &
2098
int &
2099
The reference pole of the magnet. 1=dipole, 2=quadrupole, 3=sextupole etc.\\\hline
2100
{\itshape FieldStrength} &
2101
double &
2102
Scale the field strength in the good field region. For dipoles, this sets the dipole field; for quadrupoles this sets
2103
the field gradient. Note that for some end field settings there can be no good field region (e.g. if the end length is
2104
{\textgreater}\~{} centre length).\\\hline
2105
{\itshape Height} &
2106
double &
2107
Height of the field region.\\\hline
2108
{\itshape Width} &
2109
double &
2110
Width or delta radius of the field region.\\\hline
2111
{\itshape Length} &
2112
double &
2113
Length of the field along the bent trajectory.\\\hline
2114
EndFieldType &
2115
string &
2116
Set to HardEdged to disable fringe fields. Set to Enge or Tanh to use those models, as described elsewhere. Default is
2117
HardEdged.\\\hline
2118
CurvatureModel &
2119
string &
2120
Choose the model for curvature. Straight forces no curvature. Constant gives a constant radius of curvature;
2121
StraightEnds gives a constant radius of curvature along the length of the multipole with straight end fields beyond
2122
this length. MomentumBased gives radius of curvature determined by a momentum and a total bending angle.\\\hline
2123
ReferenceCurvature &
2124
double &
2125
Radius of curvature of the magnet in Constant or StraightEnds mode. Set to 0 for a straight magnet. Default is
2126
0.\\\hline
2127
ReferenceMomentum &
2128
double &
2129
Reference momentum used to calculate the radius of curvature of a dipole in MomentumBased mode. Default is 0.\\\hline
2130
{\itshape BendingAngle} &
2131
double &
2132
The angle used to calculate the radius of curvature of a dipole in MomentumBased mode. Note that this is mandatory in
2133
MomentumBased mode.\\\hline
2134
\end{supertabular}
2135
\end{center}
2136
2137
\bigskip
2138
2139
\clearpage\subsection{FieldType CombinedFunction}
2140
This creates superimposed dipole, quadrupole and sextupole fields with a common radius of curvature. The field is
2141
intended to mimic the first few terms in a multipole expansion of a field like
2142
2143
\begin{equation*}
2144
B(y=0)=B_0\left(\frac r{r_0}\right)^k
2145
\end{equation*}
2146
The field index is a user defined parameter, while the dipole field and radius of curvature can either be defined
2147
directly by the user or defined in terms of a reference momentum and total bending angle. Fields are calculated as in
2148
the multipole field type defined above.
2149
2150
\begin{center}
2151
\tablefirsthead{\hline
2152
{\bfseries Property} &
2153
{\bfseries Type} &
2154
{\bfseries Description}\\}
2155
\tablehead{\hline
2156
{\bfseries Property} &
2157
{\bfseries Type} &
2158
{\bfseries Description}\\}
2159
\tabletail{}
2160
\tablelasttail{}
2161
\begin{supertabular}{|m{3.689cm}|m{1.252cm}|m{12.054cm}|}
2162
\hline
2163
{\itshape Pole} &
2164
int &
2165
The reference pole of the magnet. 1=dipole, 2=quadrupole, 3=sextupole etc.\\\hline
2166
{\itshape BendingField} &
2167
double &
2168
The nominal dipole field \textit{B}\textit{\textsubscript{0}}. Note that this is mandatory in all cases except where
2169
CurvatureModel is MomentumBased, when the BendingAngle and ReferenceMomentum is used to calculate the \ dipole field
2170
instead.\\\hline
2171
{\itshape FieldIndex} &
2172
double &
2173
The field index \textit{k}.\\\hline
2174
{\itshape Height} &
2175
double &
2176
Height of the field region.\\\hline
2177
{\itshape Width} &
2178
double &
2179
Width or delta radius of the field region.\\\hline
2180
{\itshape Length} &
2181
double &
2182
Length of the field along the bent trajectory.\\\hline
2183
EndFieldType &
2184
string &
2185
Set to HardEdged to disable fringe fields. Set to Enge or Tanh to use those models, as described elsewhere. Default is
2186
HardEdged.\\\hline
2187
CurvatureModel &
2188
string &
2189
Choose the model for curvature. Straight forces no curvature. Constant gives a constant radius of curvature;
2190
StraightEnds gives a constant radius of curvature along the length of the multipole with straight end fields beyond
2191
this length. MomentumBased gives radius of curvature determined by a momentum and a total bending angle.\\\hline
2192
ReferenceCurvature &
2193
double &
2194
Radius of curvature of the magnet in Constant or StraightEnds mode. Set to 0 for a straight magnet. Default is
2195
0.\\\hline
2196
ReferenceMomentum &
2197
double &
2198
Reference momentum used to calculate the radius of curvature of a dipole in MomentumBased mode. Default is 0.\\\hline
2199
{\itshape BendingAngle} &
2200
double &
2201
The angle used to calculate the radius of curvature of a dipole in MomentumBased mode. Note that this is mandatory in
2202
MomentumBased mode.\\\hline
2203
\end{supertabular}
2204
\end{center}
2205
\clearpage\subsection{EndFieldTypes}
2206
In the absence of current sources, the magnetic field can be calculated from a scalar potential using the standard
2207
relation
2208
2209
\begin{equation*}
2210
\vec B=\nabla V_n
2211
\end{equation*}
2212
The scalar magnetic potential of the n\textsuperscript{th}{}-order multipole field is given by
2213
2214
\begin{equation*}
2215
V_n=\sum _{q=0}^{q_m}\sum _{m=0}^nn!^2\frac{G^{(2q)}(s)(r^2+y^2)^q\sin (\frac{m\pi } 2)r^{n-m}y^m}{4^qq!(n+q)!m!(n-m)!}
2216
\end{equation*}
2217
where \textit{G(s)} is either the double Enge function,
2218
2219
\begin{equation*}
2220
G(s)=E[(x-x_0)/\lambda ]+E[(-x-x_0)/\lambda ]-1
2221
\end{equation*}
2222
\begin{equation*}
2223
E(s)=\frac{B_0}{R_0^n}\frac 1{1+\exp (C_1+C_2s+C_3s^2+...)}
2224
\end{equation*}
2225
or G(s) is the double tanh function,
2226
2227
\begin{equation*}
2228
G(s)=\tanh [(x+x_0)/\lambda ]/2+\tanh [(x-x_0)/\lambda ]/2
2229
\end{equation*}
2230
and \textit{(r, y, s)} is the position vector in the rotating coordinate system. Note that here s is the distance from
2231
the nominal end of the field map.
2232
2233
\begin{center}
2234
\tablefirsthead{\hline
2235
{\bfseries Property} &
2236
{\bfseries Type} &
2237
{\bfseries Description}\\}
2238
\tablehead{\hline
2239
{\bfseries Property} &
2240
{\bfseries Type} &
2241
{\bfseries Description}\\}
2242
\tabletail{}
2243
\tablelasttail{}
2244
\begin{supertabular}{|m{3.689cm}|m{1.252cm}|m{12.054cm}|}
2245
\hline
2246
EndFieldType &
2247
string &
2248
Set to HardEdged to disable fringe fields. Set to Enge or Tanh to use those models, as described elsewhere. Default is
2249
HardEdged.\\\hline
2250
\multicolumn{3}{|m{17.394999cm}|}{{\itshape The following properties are used for EndFieldType Tanh}}\\\hline
2251
EndLength &
2252
double &
2253
Set the l parameter that defines the rapidity of the field fall off.\\\hline
2254
CentreLength &
2255
double &
2256
Set the \textit{x}\textit{\textsubscript{0}} parameter that defines the length of the flat field region.\\\hline
2257
MaxEndPole &
2258
int &
2259
Set the maximum pole that will be calculated -- should be larger than the multipole pole.\\\hline
2260
\multicolumn{3}{|m{17.394999cm}|}{{\itshape The following properties are used for EndFieldType Enge}}\\\hline
2261
EndLength &
2262
double &
2263
Set the l parameter that defines the rapidity of the field fall off.\\\hline
2264
CentreLength &
2265
double &
2266
Set the \textit{x}\textit{\textsubscript{0}} parameter that defines the length of the flat field region.\\\hline
2267
MaxEndPole &
2268
int &
2269
Set the maximum pole that will be calculated -- should be larger than the multipole pole.\\\hline
2270
\multicolumn{2}{m{5.1410003cm}|}{\hspace*{-\tabcolsep}\begin{tabular}{|m{3.689cm}|m{1.252cm}}
2271
2272
Enge1 &
2273
double\\\hline
2274
Enge2 &
2275
double\\\hline
2276
... &
2277
double\\\hline
2278
EngeN &
2279
double\\\hline
2280
\end{tabular}\hspace*{-\tabcolsep}
2281
} &
2282
Set the parameters C\textsubscript{i} as defined in the Enge function above.\\\hhline{~~-}
2283
\end{supertabular}
2284
\end{center}
2285
\subsection{FieldType MagneticFieldMap}
2286
Reads or writes a magnetic field map in a particular region. Two sorts of field maps are supported; either a 2d field
2287
map, in which cylindrical symmetry is assumed, or a 3d field map.
2288
2289
For 2d field maps, G4MICE reads or writes a file that contains information about the radial and longitudinal field
2290
components. This is intended for solenoidal field maps where only radial and longitudinal field components are present.
2291
Note that in write mode, G4MICE assumes cylindrical symmetry of the fields. In this case, G4MICE writes the \textit{x}
2292
and \textit{z} components of the magnetic field at points on a grid in \textit{x} and \textit{z}. Fields with an
2293
electric component are excluded from this summation.
2294
2295
For 3d field maps, G4MICE reads a file that contains the position and field in cartesian coordinates and performs a
2296
linear interpolation. This requires quite large field map files; the file size can be slightly reduced by using certain
2297
symmetries, as described below. It is currently not possible to write 3d field maps.
2298
2299
\begin{center}
2300
\tablefirsthead{\hline
2301
{\bfseries Property} &
2302
{\bfseries Type} &
2303
{\bfseries Description}\\}
2304
\tablehead{\hline
2305
{\bfseries Property} &
2306
{\bfseries Type} &
2307
{\bfseries Description}\\}
2308
\tabletail{}
2309
\tablelasttail{}
2310
\begin{supertabular}{|m{3.665cm}|m{1.278cm}|m{12.052cm}|}
2311
\hline
2312
{\itshape FieldMapMode} &
2313
string &
2314
Set to Read to read a field map; and Write to write a field map.\\\hline
2315
{\itshape FileName} &
2316
string &
2317
The file name that is used for reading or writing.\\\hline
2318
FileType &
2319
string &
2320
The file format. Supported options in Read mode are g4micetext, g4micebinary, g4beamline, icool, g4bl3dGrid. Only
2321
g4micetext is supported in Write mode. Default is g4micetext.\\\hline
2322
Symmetry &
2323
string &
2324
Symmetry option for g4bl3dGrid file type. Options are None, Dipole or Quadrupole. None uses the field map as is, while
2325
Dipole and Quadrupole reflect the octant between the positive \textit{x}, \textit{y} and \textit{z} axes to give an
2326
appropriate field for a dipole or quadrupole.\\\hline
2327
\multicolumn{2}{m{5.143cm}|}{\hspace*{-\tabcolsep}\begin{tabular}{|m{3.665cm}|m{1.278cm}}
2328
2329
{\itshape ZStep} &
2330
double\\\hline
2331
{\itshape RStep} &
2332
double\\\hline
2333
\end{tabular}\hspace*{-\tabcolsep}
2334
} &
2335
Step size in \textit{z} and \textit{r}. Mandatory in Write mode but not used in Read mode (where step size comes from
2336
the map file).\\\hhline{~~-}
2337
\multicolumn{2}{m{5.143cm}|}{\hspace*{-\tabcolsep}\begin{tabular}{|m{3.665cm}|m{1.278cm}}
2338
2339
{\itshape ZMin} &
2340
double\\\hline
2341
{\itshape ZMax} &
2342
double\\\hline
2343
{\itshape RMin} &
2344
double\\\hline
2345
{\itshape RMax} &
2346
double\\\hline
2347
\end{tabular}\hspace*{-\tabcolsep}
2348
} &
2349
Upper and lower bounds in \textit{z} and \textit{r}. Mandatory in Write mode but not used in Read mode (where boundaries
2350
come from the map file).\\\hhline{~~-}
2351
\end{supertabular}
2352
\end{center}
2353
Some file formats are described below. I am working towards making the file format more generic and hence possibly
2354
easier to use, but backwards compatibility will hopefully be maintained.
2355
2356
\clearpage\subsubsection{g4micetext Field Map Format}
2357
The native field map format used by g4mice in text mode is described below.
2358
2359
{\ttfamily
2360
\# GridType = Uniform N = \textbf{number\_rows}}
2361
2362
{\ttfamily
2363
\# Z1 = \textbf{z\_start} Z2 = \textbf{z\_end} dZ = \textbf{z\_step}}
2364
2365
{\ttfamily
2366
\# R1 = \textbf{r\_start} R2 = \textbf{r\_end} dR = \textbf{r\_step}}
2367
2368
{\ttfamily\bfseries
2369
Bz\_Values\ \ Br\_Values}
2370
2371
{\ttfamily\bfseries
2372
...\ \ \ \ ...}
2373
2374
{\ttfamily\bfseries
2375
{\textless}Repeat as necessary{\textgreater}}
2376
2377
In this mode, field maps are represented by field values on a regular 2d grid that is assumed to have solenoidal
2378
symmetry, i.e. cylindrical symmetry with no tangential component.
2379
2380
\begin{center}
2381
\tablefirsthead{\hline
2382
{\bfseries Name} &
2383
{\bfseries Type} &
2384
{\bfseries Description}\\}
2385
\tablehead{\hline
2386
{\bfseries Name} &
2387
{\bfseries Type} &
2388
{\bfseries Description}\\}
2389
\tabletail{}
2390
\tablelasttail{}
2391
\begin{supertabular}{|m{3.665cm}|m{2.305cm}|m{11.025001cm}|}
2392
\hline
2393
{\ttfamily\bfseries number\_rows} &
2394
double &
2395
Number of rows in the field map file.\\\hline
2396
{\ttfamily\bfseries z\_start} &
2397
double &
2398
Position of the grid start along the \textit{z} axis.\\\hline
2399
{\ttfamily\bfseries z\_end} &
2400
double &
2401
Position of the grid end along the \textit{z} axis.\\\hline
2402
{\ttfamily\bfseries z\_step} &
2403
double &
2404
Step size in \textit{z}.\\\hline
2405
{\ttfamily\bfseries r\_start} &
2406
double &
2407
Position of the grid start along the \textit{r} axis.\\\hline
2408
{\ttfamily\bfseries r\_end} &
2409
double &
2410
Position of the grid end along the \textit{r} axis.\\\hline
2411
{\ttfamily\bfseries r\_step} &
2412
double &
2413
Step size in \textit{r}.\\\hline
2414
{\ttfamily\bfseries Bz\_Values} &
2415
double &
2416
\textit{Bz} field value.\\\hline
2417
{\ttfamily\bfseries Br\_Values} &
2418
double &
2419
\textit{Br} field value.\\\hline
2420
\end{supertabular}
2421
\end{center}
2422
\subsubsection{g4bl3dGrid Field Map Format}
2423
The file format for 3d field maps is a slightly massaged version of a file format used by another code, g4beamline. In
2424
this mode, field maps are represented by field values on a regular cartesian 3d grid.
2425
2426
{\ttfamily\bfseries
2427
number\_x\_points number\_y\_points number\_z\_points global\_scale}
2428
2429
{\ttfamily
2430
1 X [\textbf{x\_scale}]}
2431
2432
{\ttfamily
2433
2 Y [\textbf{y\_scale}]}
2434
2435
{\ttfamily
2436
3 Z [\textbf{z\_scale}]}
2437
2438
{\ttfamily
2439
4 BX [\textbf{bx\_scale}]}
2440
2441
{\ttfamily
2442
5 BY [\textbf{by\_scale}]}
2443
2444
{\ttfamily
2445
6 BZ [\textbf{bz\_scale}]}
2446
2447
{\ttfamily
2448
0}
2449
2450
{\ttfamily\bfseries
2451
X\_Values \ \ Y\_Values\ \ Z\_Values\ \ Bx\_values\ \ By\_values\ \ Bz\_values}
2452
2453
{\ttfamily\bfseries
2454
...\ \ \ \ ...\ \ \ \ ...\ \ \ \ ...\ \ \ \ ...\ \ \ \ ...}
2455
2456
{\ttfamily\bfseries
2457
{\textless}Repeat as necessary{\textgreater}}
2458
2459
where text in bold indicates a value described in the following table
2460
2461
\begin{center}
2462
\tablefirsthead{\hline
2463
{\bfseries Name} &
2464
{\bfseries Type} &
2465
{\bfseries Description}\\}
2466
\tablehead{\hline
2467
{\bfseries Name} &
2468
{\bfseries Type} &
2469
{\bfseries Description}\\}
2470
\tabletail{}
2471
\tablelasttail{}
2472
\begin{supertabular}{|m{3.665cm}|m{2.305cm}|m{11.025001cm}|}
2473
\hline
2474
{\ttfamily\bfseries number\_x\_points} &
2475
double &
2476
Number of points along x axis.\\\hline
2477
{\ttfamily\bfseries number\_y\_points} &
2478
double &
2479
Number of points along y axis.\\\hline
2480
{\ttfamily\bfseries number\_z\_points} &
2481
double &
2482
Number of points along z axis.\\\hline
2483
{\ttfamily\bfseries global\_scale} &
2484
double &
2485
Global scale factor applied to all x, y, z and Bx, By, Bz values.\\\hline
2486
{\ttfamily\bfseries x\_scale} &
2487
double &
2488
Scale factor applied to all x values.\\\hline
2489
{\ttfamily\bfseries y\_scale} &
2490
double &
2491
Scale factor applied to all y values.\\\hline
2492
{\ttfamily\bfseries z\_scale} &
2493
double &
2494
Scale factor applied to all z values.\\\hline
2495
{\ttfamily\bfseries bx\_scale} &
2496
double &
2497
Scale factor applied to all Bx values.\\\hline
2498
{\ttfamily\bfseries by\_scale} &
2499
double &
2500
Scale factor applied to all By values.\\\hline
2501
{\ttfamily\bfseries bz\_scale} &
2502
double &
2503
Scale factor applied to all Bz values.\\\hline
2504
{\ttfamily\bfseries X\_Values} &
2505
double &
2506
List (column) of each x value.\\\hline
2507
{\ttfamily\bfseries Y\_Values} &
2508
double &
2509
List (column) of each y value.\\\hline
2510
{\ttfamily\bfseries Z\_Values} &
2511
double &
2512
List (column) of each z value.\\\hline
2513
{\ttfamily\bfseries Bx\_Values} &
2514
double &
2515
List (column) of each Bx value.\\\hline
2516
{\ttfamily\bfseries By\_Values} &
2517
double &
2518
List (column) of each By value.\\\hline
2519
{\ttfamily\bfseries Bz\_Values} &
2520
double &
2521
List (column) of each Bz value.\\\hline
2522
\end{supertabular}
2523
\end{center}
2524
2525
\bigskip
2526
\end{document}
Loggerhead is a web-based interface for Breezy
Version: 2.0.1