From d82dfcfff7f765d8f5ea4d7410f5e48c2aad255f Mon Sep 17 00:00:00 2001
From: ext-calvo_p <pedro.calvo@ciemat.es>
Date: Wed, 9 Mar 2022 07:21:57 +0000
Subject: [PATCH] Resolve "Documentation for COMPUTEPERCENTILES option"
---
control.asciidoc | 16 +++++--
opalcycl.asciidoc | 44 +++++++++++++++--
opalmap.asciidoc | 5 +-
opalt.asciidoc | 120 ++++++++++++++++++++++++++++++++++++----------
4 files changed, 149 insertions(+), 36 deletions(-)
diff --git a/control.asciidoc b/control.asciidoc
index c8bbc8c..7c03de9 100644
--- a/control.asciidoc
+++ b/control.asciidoc
@@ -104,7 +104,7 @@ PSDUMPFREQ::
H5hut file. Its default value is 10.
STATDUMPFREQ::
Defines after how many time steps we dump statistical data, such as
- RMS beam emittance, to the .stat file. The default value is 10.
+ RMS beam emittance, to the _.stat_ file. The default value is 10.
Currently only available for _OPAL-t_.
PSDUMPEACHTURN::
Control option of phase space dumping. If true, dump phase space after
@@ -112,7 +112,7 @@ PSDUMPEACHTURN::
simulation in _OPAL-cycl_. Its default value is false.
PSDUMPFRAME::
Control option that defines the frame in which the phase space data is
- written for h5 and stat files. Beware that the data is written in a
+ written for _.h5_ and _.stat_ files. Beware that the data is written in a
given time step. Most accelerator
physics quantities are defined at a given s-step where s is distance
along the reference trajectory. For non-isochronous accelerators,
@@ -249,6 +249,13 @@ MEMORYDUMP::
FALSE
HALOSHIFT::
Constant parameter to shift halo value. Its default value is 0.0.
+COMPUTEPERCENTILES::
+ If true, the 68 (1 sigmas for normal distribution), the 95 (2 sigmas),
+ the 99.7 (3 sigmas) and the 99.99 (4 sigmas) percentiles of the bunch
+ size and the normalized emittance are calculated. The data are stored
+ into _.stat_ output file and loss file in HDF5 format (_.h5_). The
+ calculation is performed whenever the number of particles exceeds 100.
+ Default is false.
Examples:
@@ -303,6 +310,7 @@ OPTION,SEED=987456321
|`MEMORYDUMP` |= `FALSE`
|`HALOSHIFT` |= `0.0`
|`DELPARTFREQ` |= `1`
+|`COMPUTEPERCENTILES`|= `FALSE`
|=======================================================================
[[sec.consumption.parameter]]
@@ -647,8 +655,8 @@ Example:
// all OPAL runs will use the same OPTIONs
OPTION, ECHO=FALSE;
OPTION, INFO=FALSE; //psdump and statdump are in time steps
-OPTION, PSDUMPFREQ = 10000000; //How often 6d info is dumped to .h5
-OPTION, STATDUMPFREQ = 10; //How often beam stats dumped to .stat.
+OPTION, PSDUMPFREQ = 10000000; //How often 6d info is dumped to _.h5_
+OPTION, STATDUMPFREQ = 10; //How often beam stats dumped to _.stat_
OPTION, BOUNDPDESTROYFQ=10; //Delete lost particles, if any
OPTION, AUTOPHASE=4; //Always leave this on, unless doing a phase scan
OPTION, VERSION=20000;
diff --git a/opalcycl.asciidoc b/opalcycl.asciidoc
index 10c6258..b67f1d7 100644
--- a/opalcycl.asciidoc
+++ b/opalcycl.asciidoc
@@ -633,11 +633,47 @@ _OPAL-cycl_ writes out several output files, some specific to the Tracking mode
(see following sections).
[[sec.opalcycl.input_file_name-.stat]]
-==== _<input_file_name >.stat_
+==== Statistics output
+
+See link:opalt#sec.opalt.input_file_name-.stat[_OPAL-t_ Statistics output]. The only
+difference is in the cyclotron coordinate convention. The z (or s) coordinate
+refers to the vertical direction and y corresponds to the longitudinal or beam
+travel direction. In addition, _OPAL-cycl_ includes some extra data, as is
+described in the following table.
+
+.Additional data stored in statistics output file in _OPAL-cycl_.
+[cols="<1,<1,<5",options="header",]
+[[tab_opal_cycl_stat,{counter:tab-cnt}]]
+|=======================================================================
+|Name |Units |Meaning
+
+|R0_x |m |X-component of position of particle with ID 0 (only when
+run serial)
+
+|R0_y |m |Y-component of position of particle with ID 0 (only when
+run serial)
+
+|R0_s |m |S-component of position of particle with ID 0 (only when
+run serial)
+
+|P0_x |m |X-component of momentum of particle with ID 0 (only when
+run serial)
+
+|P0_y |m |Y-component of momentum of particle with ID 0 (only when
+run serial)
+
+|P0_s |m |S-component of momentum of particle with ID 0 (only when
+run serial)
+
+|halo_x |1 |Halo in x
+
+|halo_y |1 |Halo in y
+
+|halo_z |1 |Halo in z
+
+|azimuth |deg |Azimuth in global coordinates
+|=======================================================================
-See link:opalt#sec.opalt.input_file_name-.stat[_OPAL-t_ stat file]. The only
-difference is in the cyclotron coordinate convention. The z (or s) coordinate refers to the vertical
-direction and y corresponds to the longitudinal or beam travel direction.
[[sec.opalcycl.single-particle-tracking-mode-1]]
==== Single Particle Tracking mode
diff --git a/opalmap.asciidoc b/opalmap.asciidoc
index 9a1c77f..611f3b1 100644
--- a/opalmap.asciidoc
+++ b/opalmap.asciidoc
@@ -190,9 +190,10 @@ In addition to the progress report that _OPAL-map_ writes to the standard
output (stdout) it also writes different files for various purposes.
[[sec.opalmap.input_file_name-.stat]]
-==== _<input_file_name >.stat_
+==== Statistics output
-The file structure is analogous to link:opalt#sec.opalt.input_file_name-.stat[OPAL-t] .stat file.
+The file structure is analogous to
+link:opalt#sec.opalt.input_file_name-.stat[_OPAL-t_ Statistics output file].
[[sec.opalmap.datainput_file_name.dispersion]]
diff --git a/opalt.asciidoc b/opalt.asciidoc
index b6e859a..63cc7a6 100644
--- a/opalt.asciidoc
+++ b/opalt.asciidoc
@@ -316,16 +316,19 @@ In addition to the progress report that _OPAL-t_ writes to the standard
output (stdout) it also writes different files for various purposes.
[[sec.opalt.input_file_name-.stat]]
-==== _<input_file_name >.stat_
+==== Statistics output
This file is used to log the statistical properties of the bunch in the
ASCII variant of the SDDS format <<bib.borland1995_opalt>>. It can be viewed
with the SDDS Tools <<bib.borland2016>> or GNUPLOT. The frequency with
which the statistics are computed and written to file can be controlled
-With the option `STATDUMPFREQ`. The information that is stored are found
-in the following table.
+With the option `STATDUMPFREQ` (see link:control#sec.control.option[Option Statement]).
+The name of the output file is _<input_file_name >.stat_.
+The information that is stored are found in the following table.
+.Data stored in statistics output file in _OPAL-t_.
[cols="<1,<1,<1,<5",options="header",]
+[[tab_opal_t_stat,{counter:tab-cnt}]]
|=======================================================================
|Column Nr. |Name |Units |Meaning
|1 |t |ns |Time
@@ -421,35 +424,91 @@ in floor coordinate system
|42 |partsOutside |1 |Number of particles outside
latexmath:[n \times gma] of beam, where latexmath:[n] is controlled
-with `BEAMHALOBOUNDARY`
+with `BEAMHALOBOUNDARY` (see link:control#sec.control.option[Option Statement])
-|43 |R0_x |m |X-component of position of particle with ID 0 (only when
-run serial)
+|43 |68_Percentile_x |m |68.27 percentile (1 sigma of normal distribution)
+of x-component of position (only when `COMPUTEPERCENTILES=TRUE`)
-|44 |R0_y |m |Y-component of position of particle with ID 0 (only when
-run serial)
+|44 |68_Percentile_y |m |68.27 percentile (1 sigma of normal distribution)
+of y-component of position (only when `COMPUTEPERCENTILES=TRUE`)
-|45 |R0_s |m |S-component of position of particle with ID 0 (only when
-run serial)
+|45 |68_Percentile_z |m |68.27 percentile (1 sigma of normal distribution)
+of z-component of position (only when `COMPUTEPERCENTILES=TRUE`)
-|46 |P0_x |m |X-component of momentum of particle with ID 0 (only when
-run serial)
+|46 |95_Percentile_x |m |95.45 percentile (2 sigma of normal distribution)
+of x-component of position (only when `COMPUTEPERCENTILES=TRUE`)
-|47 |P0_y |m |Y-component of momentum of particle with ID 0 (only when
-run serial)
+|47 |95_Percentile_y |m |95.45 percentile (2 sigma of normal distribution)
+of y-component of position (only when `COMPUTEPERCENTILES=TRUE`)
-|48 |P0_s |m |S-component of momentum of particle with ID 0 (only when
-run serial)
+|48 |95_Percentile_z |m |95.45 percentile (2 sigma of normal distribution)
+of z-component of position (only when `COMPUTEPERCENTILES=TRUE`)
+
+|49 |99_Percentile_x |m |99.73 percentile (3 sigma of normal distribution)
+of x-component of position (only when `COMPUTEPERCENTILES=TRUE`)
+
+|50 |99_Percentile_y |m |99.73 percentile (3 sigma of normal distribution)
+of y-component of position (only when `COMPUTEPERCENTILES=TRUE`)
+
+|51 |99_Percentile_z |m |99.73 percentile (3 sigma of normal distribution)
+of z-component of position (only when `COMPUTEPERCENTILES=TRUE`)
+
+|52 |99_99_Percentile_x |m |99.994 percentile (4 sigma of normal distribution)
+of x-component of position (only when `COMPUTEPERCENTILES=TRUE`)
+
+|53 |99_99_Percentile_y |m |99.994 percentile (4 sigma of normal distribution)
+of y-component of position (only when `COMPUTEPERCENTILES=TRUE`)
+
+|54 |99_99_Percentile_z |m |99.994 percentile (4 sigma of normal distribution)
+of z-component of position (only when `COMPUTEPERCENTILES=TRUE`)
+
+|55 |normalizedEps68Percentile_x |m |x-component of normalized emittance at 68
+percentile (1 sigma of normal distribution) (only when `COMPUTEPERCENTILES=TRUE`)
+
+|56 |normalizedEps68Percentile_y |m |y-component of normalized emittance at 68
+percentile (1 sigma of normal distribution) (only when `COMPUTEPERCENTILES=TRUE`)
+
+|57 |normalizedEps68Percentile_z |m |z-component of normalized emittance at 68
+percentile (1 sigma of normal distribution) (only when `COMPUTEPERCENTILES=TRUE`)
+
+|58 |normalizedEps95Percentile_x |m |x-component of normalized emittance at 95
+percentile (2 sigma of normal distribution) (only when `COMPUTEPERCENTILES=TRUE`)
+
+|59 |normalizedEps95Percentile_y |m |y-component of normalized emittance at 95
+percentile (2 sigma of normal distribution) (only when `COMPUTEPERCENTILES=TRUE`)
+
+|60 |normalizedEps95Percentile_z |m |z-component of normalized emittance at 95
+percentile (2 sigma of normal distribution) (only when `COMPUTEPERCENTILES=TRUE`)
+
+|61 |normalizedEps99Percentile_x |m |x-component of normalized emittance at 99
+percentile (3 sigma of normal distribution) (only when `COMPUTEPERCENTILES=TRUE`)
+
+|62 |normalizedEps99Percentile_y |m |y-component of normalized emittance at 99
+percentile (3 sigma of normal distribution) (only when `COMPUTEPERCENTILES=TRUE`)
+
+|63 |normalizedEps99Percentile_z |m |z-component of normalized emittance at 99
+percentile (3 sigma of normal distribution) (only when `COMPUTEPERCENTILES=TRUE`)
+
+|64 |normalizedEps99_99Percentile_x |m |x-component of normalized emittance at 99.99
+percentile (4 sigma of normal distribution) (only when `COMPUTEPERCENTILES=TRUE`)
+
+|65 |normalizedEps99_99Percentil_y |m |y-component of normalized emittance at 99.99
+percentile (4 sigma of normal distribution) (only when `COMPUTEPERCENTILES=TRUE`)
+
+|66 |normalizedEps99_99Percentil_z |m |z-component of normalized emittance at 99.99
+percentile (4 sigma of normal distribution) (only when `COMPUTEPERCENTILES=TRUE`)
|=======================================================================
[[sec.opalt.datainput_file_name-_monitors.stat]]
-==== _data/<input_file_name >_Monitors.stat_
+==== Monitor statistics output
-_OPAL-t_ computes the statistics of the bunch for every `MONITOR` that
-it passes. The information that is written can be found in the following
-table.
+_OPAL-t_ computes the statistics of the bunch for every `MONITOR` that it
+passes. The name of the output file is _data/<input_file_name >_Monitors.stat_.
+The information that is written can be found in the following table.
+.Data stored in `MONITOR` statistics output file in _OPAL-t_.
[cols="<1,<1,<1,<5",options="header",]
+[[tab_opal_t_monitor_stat,{counter:tab-cnt}]]
|=======================================================================
|Column Nr. |Name |Units |Meaning
|1 |name |a string |Name of the monitor
@@ -530,14 +589,18 @@ in floor coordinate system
|=======================================================================
[[sec.opalt.datainput_file_name-_3d.opal]]
-==== _data/<input_file_name >_3D.opal_
+==== Input file transcription
_OPAL-t_ copies the input file into this file and replaces all
occurrences of `ELEMEDGE` with the corresponding position using `X`,
-`Y`, `Z`, `THETA`, `PHI` and `PSI`.
+`Y`, `Z`, `THETA`, `PHI` and `PSI`. The name of the output file is
+_data/<input_file_name >_3D.opal_.
+
+[[sec.opalt.datainput_file_name-_elementpositions]]
+==== Element positions output files
[[sec.opalt.datainput_file_name-_elementpositions.txt]]
-==== _data/<input_file_name >_ElementPositions.txt_
+===== _data/<input_file_name >_ElementPositions.txt_
_OPAL-t_ stores for every element the position of the entrance and the
exit. Additionally the reference trajectory inside dipoles is stored. On
@@ -547,7 +610,7 @@ store the z-component then the x-component and finally the y-component
of the position in floor coordinates.
[[sec.opalt.datainput_file_name-_elementpositions.py]]
-==== _data/<input_file_name >_ElementPositions.py_
+===== _data/<input_file_name >_ElementPositions.py_
This Python script can be used to generate visualizations of the beam
line in different formats. Beside an ASCII file that can be printed
@@ -575,13 +638,15 @@ The following arguments can be passed
* `--normal x y z` specify the normal for projection with the components `x`, `y` and `z`
[[sec.opalt.datainput_file_name-_elementpositions.sdds]]
-==== _data/<input_file_name >_ElementPositions.sdds_
+===== _data/<input_file_name >_ElementPositions.sdds_
This file can be used when plotting the statistics of the bunch to
indicate the positions of the magnets. It is written in the SDDS format.
The information that is written can be found in the following table.
+.Data stored in the element position output file in _OPAL-t_.
[cols="<1,<1,<1,<5",options="header",]
+[[tab_opal_t_elem_out,{counter:tab-cnt}]]
|=======================================================================
|Column Nr. |Name |Units |Meaning
|1 |s |m |The position in path length
@@ -627,12 +692,15 @@ This produces a plot as found in <<fig_elementIndicator>>
image::./figures/opalt/elementIndicator.png[scaledwidth=6cm,width=40%]
[[sec.opalt.datainput_file_name-_designpath.dat]]
-==== _data/<input_file_name >_DesignPath.dat_
+==== Reference particle trajectory output
The trajectory of the reference particle is stored in this ASCII file.
+The name of the output file is _data/<input_file_name >_DesignPath.dat_.
The content of the columns are listed in the following table.
+.Data stored in the reference particle output file in _OPAL-t_.
[cols="<1,<1,<1,<5",options="header",]
+[[tab_opal_t_ref_out,{counter:tab-cnt}]]
|========================================================
|Column Nr. |Name |Units |Meaning
|1 | |m |Position in path length
--
GitLab