diff --git a/control.asciidoc b/control.asciidoc
index de7e1cc1543f7f8cb18657dc92c07cd8c3dadf28..3de35bc8cf8ae139e352a62953a9495d6cc052c4 100644
--- a/control.asciidoc
+++ b/control.asciidoc
@@ -53,16 +53,15 @@ Any statement following the `STOP` or `QUIT` statement is ignored.
[[sec.control.option]]
=== OPTION Statement
-The `OPTION` command controls global command execution and sets a few
-global quantities. Starting with version 1.6.0 of _OPAL_ the option
-`VERSION` is mandatory in the _OPAL_ input file. Example:
+The `OPTION` command controls global command execution and sets a few global
+quantities. Each of the settings options are listed in <<tab_Options_Defaults>>
+with their corresponding default values.
----
-OPTION,ECHO=logical,INFO=logical,TRACE=logical,
- WARN=logical,
- SEED=real,PSDUMPFREQ=integer,
- STATDUMPFREQ=integer, SPTDUMFREQ=integer,
- REPARTFREQ=integer, REBINFREQ=integer, TELL=logical, VERSION=integer;
+OPTION, VERSION=integer, ECHO=logical,INFO=logical,TRACE=logical,
+ WARN=logical, SEED=real, PSDUMPFREQ=integer,
+ STATDUMPFREQ=integer, SPTDUMFREQ=integer,
+ REPARTFREQ=integer, REBINFREQ=integer, TELL=logical;
----
VERSION::
@@ -71,9 +70,10 @@ VERSION::
have to match. The patch version of _OPAL_ must be greater or equal to
the patch version of the input file. If the version doesn’t fulfill
above criteria _OPAL_ stops immediately and prints instructions on how
- to convert the input file. The format is `Mmmpp` where `M` stands for
- the major, `m` for the minor and `p` for the patch version. For
- version 1.6.0 of _OPAL_ `VERSION` should read `10600`.
+ to convert the input file. Starting with version 1.6.0 of _OPAL_ the option
+ `VERSION` is mandatory in the _OPAL_ input file. The format is `Mmmpp` where
+ `M` stands for the major, `m` for the minor and `p` for the patch version.
+ For version 1.6.0 of _OPAL_ `VERSION` should read `10600`.
The next five logical flags activate or deactivate execution options:
@@ -83,95 +83,57 @@ ECHO::
INFO::
If this option is turned off, _OPAL_ suppresses all information
messages. It also affects the _gnu.out_ and _eb.out_ files in case of
- _OPAL-cycl_ simulations. Its default value is true.
+ _OPAL-cycl_ simulations
+ (see link:opalcycl#sec.opalcycl.fields-maps-1[_OPAL-cycl_ output field maps]).
+ The level of information showed is controlled with `--info` command line
+ (see <<tab_CommandLineArg>>) Its default value is true.
+TELL::
+ If true, the current option settings are listed. Must be the last option in
+ the input file in order to render correct results. Its default value is false.
TRACE::
If true, print execution trace. Must be the first option in the
inputfile in order to render correct results. Its default value is false.
WARN::
If this option is turned off, _OPAL_ suppresses all warning messages.
Its default value is true.
-TELL::
- If true, the current settings are listed. Must be the last option in
- the inputfile in order to render correct results.
-SEED::
- Selects a particular sequence of random values. A SEED value is an
- integer in the range [0...999999999] (default: 123456789). SEED can be
- an expression. If SEED latexmath:[=] -1, the time is used as seed
- and the generator is not portable anymore. See also: random values
- see link:format#sec.format.adefer[Deferred Expressions and Random Values].
-PSDUMPFREQ::
- Defines after how many time steps the phase space is dumped into the
- 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.
- Currently only available for _OPAL-t_.
-PSDUMPEACHTURN::
- Control option of phase space dumping. If true, dump phase space after
- each turn. For the time being, this is only use for multi-bunch
- 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
- 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,
- particles at a given time step can be quite a long way away from the
- reference particle, yielding unexpected results. Currently only
- available for _OPAL-cycl_. In _OPAL-t_ the phase-space is always
- written in the frame of the reference particle.
- * `GLOBAL`: data is written in the global Cartesian frame;
- * `BUNCH_MEAN`: data is written in the bunch mean frame or;
- * `REFERENCE`: data is written in the frame of the reference particle.
-SPTDUMPFREQ::
- Defines after how many time steps we dump the phase space of single
- particle. It is always useful to record the trajectory of reference
- particle or some specified particle for primary study. Its default
- value is 1.
-REPARTFREQ::
- Defines after how many time steps we do particles repartition to
- balance the computational load of the computer nodes. Its default
- value is 10.
-MINBINEMITTED::
- The number of bins that have to be emitted before the bin are squashed
- into a single bin. Its default value is 10.
-MINSTEPFORREBIN::
- The number of steps into the simulation before the bins are squashed
- into a single bin. This should be used instead of the global variable
- of the same name. Its default value is 200.
-REBINFREQ::
- Defines after how many time steps we update the energy Bin ID of each
- particle. For the time being. Only available for multi-bunch
- simulation in _OPAL-cycl_. Its default value is 100.
-SCSOLVEFREQ::
- If the space charge field is slowly varying w.r.t. external fields,
- this option allows to change the frequency of space charge
- calculation, i.e. the space charge forces are evaluated every
- SCSOLVEFREQ step and then reused for the following steps. Affects
- integrators `LF2` and `RK4` of _OPAL-cycl_. Its default value is 1.
- Note: as the multiple-time-stepping (`MTS`) integrator maintains
- accuracy much better with reduced space charge solve frequency, this
- option should probably not be used anymore.
-MTSSUBSTEPS::
- Only used for multiple-time-stepping (`MTS`) integrator in _OPAL-cycl_.
- Specifies how many sub-steps for external field integration are done
- per step. Default value is 1. Making less steps per turn and
- increasing this value is the recommended way to reduce space charge
- solve frequency.
-REMOTEPARTDEL::
- Artificially delete remote particles if their distances to the beam
- centroid is larger than `REMOTEPARTDEL` times of the beam rms size. The
- default value is 0, i.e. no particles are deleted. In _OPAL-t_ only the
- longitudinal component of the particles is considered. In _OPAL-cycl_ all
- components are considered if the the value is negative (further on using its
- absolute value) and only the transverse components if the value is positive.
-RHODUMP::
- If true the scalar latexmath:[\rho] field is saved each time a phase
- space is written. There exists a reader in Visit with versions greater
- or equal 1.11.1. Its default value is false.
-EBDUMP::
- If true the electric and magnetic field on the particle is saved each
- time a phase space is written. Its default value is false.
+
+The remaining options (ordered alphabetically) are used to control
+diverse _OPAL_ features:
+
+AMR::
+ Enable adaptive mesh refinement (see link:fieldsolver#sec.fieldsolvers.AMR[`AMR` Solver]).
+ Its default value is false.
+AMR_REGRID_FREQ::
+ Defines after how many steps an link:fieldsolver#sec.fieldsolvers.AMR[`AMR`]
+ regrid is performed. Its default value is 10.
+AMR_YT_DUMP_FREQ::
+ The frequency to dump grid and particle data for link:fieldsolver#sec.fieldsolvers.AMR[`AMR`].
+ Its default value is 10.
+ASCIIDUMP::
+ If true, instead of HDF5, ASCII output is generated for the following
+ elements: Collimator, Geometry, Monitor, Probe, Stripper,
+ Vacuum and global losses. Its default value is false.
+AUTOPHASE::
+ Defines how accurate the search for the phase at which the maximal energy
+ is gained should be. The higher this number the more accurate the phase
+ will be. If it is set to 0 then the auto-phasing algorithm isn't
+ run. Its default value is 6.
+BEAMHALOBOUNDARY::
+ Defines in terms of sigma where the halo starts. Only used in _OPAL-cycl_.
+ Its default value is 0.0.
+BOUNDPDESTROYFQ::
+ The frequency to delete particles which are too far away from the
+ center of beam. Only used in _OPAL-cycl_. Its default value is 10.
+CLOTUNEONLY::
+ If set to true, stop after closed orbit finder and tune calculation.
+ Only used in _OPAL-cycl_. Its default value is false.
+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.
+ Its default value is false.
CSRDUMP::
If true the electric csr field component, latexmath:[E_z], line
density and the derivative of the line density is written into the
@@ -185,136 +147,176 @@ CSRDUMP::
text file is named "Bend Name" (from input file) + "-CSRWake"
+ "time step number in that bend (starting from 1)" + ".txt".
Its default value is false.
-AUTOPHASE::
- Defines how accurate the search for the phase at which the maximal energy
- is gained should be. The higher this number the more accurate the phase
- will be. If it is set to 0 then the auto-phasing algorithm isn't
- run. Default: 6.
-NUMBLOCKS::
- Maximum number of vectors in the Krylov space (for RCGSolMgr). Default
- value is 0 and BlockCGSolMgr will be used.
-RECYCLEBLOCKS::
- Number of vectors in the recycle space (for RCGSolMgr). Default value
- is 0 and BlockCGSolMgr will be used.
-NLHS::
- Number of stored old solutions for extrapolating the new starting
- vector. Default value is 1 and just the last solution is used.
CZERO::
If true the distributions are generated such that the centroid is
exactly zero and not statistically dependent. Its default value is false.
-RNGTYPE::
- The name (see link:format#sec.format.astring[String Attributes]) of a random
- number generator can be provided. The default random number generator (RANDOM)
- is a portable 48-bit generator. Three quasi random generators are available:
-+
- 1. HALTON
- 2. SOBOL
- 3. NIEDERREITER.
-+
-For details see the GSL reference manual (18.5).
+DELPARTFREQ::
+ The frequency to delete particles in _OPAL-cycl_. Its default value is 1.
+DUMPBEAMMATRIX::
+ If true, the 6-dimensional beam matrix (upper triangle only) is stored
+ in the statistics output file (_.stat_). Its default value is false.
+EBDUMP::
+ If true the electric and magnetic field on the particle is saved each
+ time a phase space is written. Its default value is false.
ENABLEHDF5::
If true (default), HDF5 read and write is enabled.
ENABLEVTK::
If true (default), VTK write of geometry voxel mesh is enabled.
-ASCIIDUMP::
- If true, instead of HDF5, ASCII output is generated for the following
- elements: Probe, Collimator, Monitor, Stripper, Geometry,
- Beam stripping losses and global losses. Its default value is false.
-BOUNDPDESTROYFQ::
- The frequency to do `boundp_destroy` to delete lost particles. Default 10.
- Only used in _OPAL-cycl_.
-DELPARTFREQ::
- The frequency to delete particles in _OPAL-cycl_. Its default value is 1.
-BEAMHALOBOUNDARY::
- Defines in terms of sigma where the halo starts. Default: 0.0. Only used in _OPAL-cycl_.
-CLOTUNEONLY::
- If set to true stop after closed orbit finder and tune calculation. Only used in _OPAL-cycl_.
+HALOSHIFT::
+ Constant parameter to shift halo value. Its default value is 0.0.
IDEALIZED::
Instructs to use the hard edge model for the calculation of the path
length in _OPAL-t_. The path length is computed to place the elements
- in the three-dimensional space from `ELEMEDGE`. Default is false.
+ in the three-dimensional space from `ELEMEDGE`. Its default value is false.
LOGBENDTRAJECTORY::
Save the reference trajectory inside dipoles in an ASCII file. For
each dipole a separate file is written to the directory _data/_.
- Default is false.
-AMR::
- Enable adaptive mesh refinement. Default is false.
-AMR_YT_DUMP_FREQ::
- The frequency to dump grid and particle data for AMR. Default: 10
-AMR_REGRID_FREQ::
- Defines after how many steps an AMR regrid is performed. Default: 10
+ Its default value is false.
MEMORYDUMP::
If true, it writes the memory consumption of every core to a SDDS file
- (*.mem). The write frequency corresponds to STATDUMPFREQ. Default:
- 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.
-DUMPBEAMMATRIX::
- If true, the 6-dimensional beam matrix (upper triangle only) is stored
- in the statistics output file. Default is false.
-
-Examples:
-
-----
-OPTION,ECHO=FALSE,TELL;
-OPTION,SEED=987456321
-----
+ (_.mem_). The write frequency corresponds to `STATDUMPFREQ`.
+ Its default value is false.
+MINBINEMITTED::
+ The number of bins that have to be emitted before the bin are squashed
+ into a single bin. Its default value is 10.
+MINSTEPFORREBIN::
+ The number of steps into the simulation before the bins are squashed
+ into a single bin. This should be used instead of the global variable
+ of the same name. Its default value is 200.
+MTSSUBSTEPS::
+ Only used for multiple-time-stepping (`MTS`) integrator in _OPAL-cycl_.
+ Specifies how many sub-steps for external field integration are done
+ per step. Making less steps per turn and increasing this value is the
+ recommended way to reduce space charge solve frequency.
+ Its default value is 1.
+NLHS::
+ Number of stored old solutions for extrapolating the new starting
+ vector. Default value is 1 and just the last solution is used.
+NUMBLOCKS::
+ Maximum number of vectors in the Krylov space for `ITSOLVER=CG` or `ITSOLVER=GMRES`
+ (see link:fieldsolver#sec.fieldsolvers.fieldsolvercmd[`FIELDSOLVER` command]).
+ Its default value is 0.
+PSDUMPFREQ::
+ Defines after how many time steps the phase space is dumped into the H5hut
+ file (_.h5_). It also controls the frequency of phase space printed on the
+ standard output. Its default value is 10.
+PSDUMPEACHTURN::
+ Control option of phase space dumping. If true, dump phase space after
+ each turn. For the time being, this is only use for multi-bunch
+ 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
+ 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, particles at a given time step can be quite a
+ long way away from the reference particle, yielding unexpected results.
+ Currently only available for _OPAL-cycl_. In _OPAL-t_ the phase-space is always
+ written in the frame of the reference particle.
+ * `GLOBAL`: data is written in the global Cartesian frame;
+ * `BUNCH_MEAN`: data is written in the bunch mean frame or;
+ * `REFERENCE`: data is written in the frame of the reference particle.
+REBINFREQ::
+ Defines after how many time steps we update the energy Bin ID of each
+ particle. For the time being. Only available for multi-bunch
+ simulation in _OPAL-cycl_. Its default value is 100.
+RECYCLEBLOCKS::
+ Number of vectors in the recycle space for `ITSOLVER=CG` or `ITSOLVER=GMRES`
+ (see link:fieldsolver#sec.fieldsolvers.fieldsolvercmd[`FIELDSOLVER` command]).
+ Its default value is 0.
+REMOTEPARTDEL::
+ Artificially delete remote particles if their distances to the beam
+ centroid is larger than `REMOTEPARTDEL` times of the beam rms size.
+ In _OPAL-t_ only the longitudinal component of the particles is considered.
+ In _OPAL-cycl_ all components are considered if the the value is negative
+ (further on using its absolute value) and only the transverse components if
+ the value is positive. Its default value is 0.0, i.e. no particles are deleted.
+REPARTFREQ::
+ Defines after how many time steps we do particles repartition to
+ balance the computational load of the computer nodes. Its default
+ value is 10.
+RHODUMP::
+ If true the scalar latexmath:[\rho] field is saved each time a phase
+ space is written. There exists a reader in Visit with versions greater
+ or equal 1.11.1. Its default value is false.
+RNGTYPE::
+ The name (see link:format#sec.format.astring[String Attributes]) of a random
+ number generator can be provided. The default random number generator
+ (RANDOM) is a portable 48-bit generator. Three quasi random generators are
+ available: `HALTON`, `SOBOL` and `NIEDERREITER`. For details see the GSL
+ reference manual (18.5).
+SCSOLVEFREQ::
+ If the space charge field is slowly varying w.r.t. external fields,
+ this option allows to change the frequency of space charge
+ calculation, i.e. the space charge forces are evaluated every
+ `SCSOLVEFREQ` step and then reused for the following steps. Affects
+ integrators `LF2` and `RK4` of _OPAL-cycl_. Its default value is 1.
+ Note: as the multiple-time-stepping (`MTS`) integrator maintains
+ accuracy much better with reduced space charge solve frequency, this
+ option should probably not be used anymore.
+SEED::
+ Selects a particular sequence of random values. A `SEED` value is an
+ integer in the range [0...999999999] (default: 123456789). `SEED` can be
+ an expression. If `SEED` latexmath:[=] -1, the time is used as seed
+ and the generator is not portable anymore. See also link:format#sec.format.adefer[Deferred Expressions and Random Values].
+SPTDUMPFREQ::
+ Defines after how many time steps we dump the phase space of single
+ particle in _OPAL-cycl_. It is always useful to record the trajectory
+ of reference particle or some specified particle for primary study.
+ Its default value is 1.
+STATDUMPFREQ::
+ Defines after how many time steps we dump statistical data, such as
+ RMS beam emittance, to the _.stat_ file. Its default value is 10.
-.Default Settings for Options
+.Default settings for Options
[[tab_Options_Defaults,Table {counter:tab-cnt}]]
-[cols="<,<,<,<,<,<",options="header",]
+[cols="<,<,<,<,<,<",]
|=======================================================================
+|`AMR` |= `FALSE`
+|`AMR_REGRID_FREQ` |= `10`
+|`AMR_YT_DUMP_FREQ` |= `10`
+|`ASCIIDUMP` |= `FALSE`
+|`AUTOPHASE` |= `6`
+|`BEAMHALOBOUNDARY` |= `0.0`
+|`BOUNDPDESTROYFQ` |= `10`
+|`CLOTUNEONLY` |= `FALSE`
+|`COMPUTEPERCENTILES`|= `FALSE`
+|`CSRDUMP` |= `FALSE`
+|`CZERO` |= `FALSE`
+|`DELPARTFREQ` |= `1`
+|`DUMPBEAMMATRIX` |= `FALSE`
+|`EBDUMP` |= `FALSE`
|`ECHO` |= `FALSE`
+|`ENABLEHDF5` |= `TRUE`
+|`ENABLEVTK` |= `TRUE`
+|`HALOSHIFT` |= `0.0`
+|`IDEALIZE` |= `FALSE`
|`INFO` |= `TRUE`
-|`TRACE` |= `FALSE`
-|`WARN` |= `TRUE`
-|`TELL` |= `FALSE`
-|`SEED` |= `123456789`
-|`PSDUMPFREQ` |= `10`
-|`STATDUMPFREQ` |= `10`
-|`PSDUMPEACHTURN` |= `FALSE`
-|`PSDUMPFRAME` |= `GLOBAL`
-|`SPTDUMPFREQ` |= `1`
-|`REPARTFREQ` |= `10`
-|`REBINFREQ` |= `100`
+|`LOGBENDTRAJECTORY` |= `FALSE`
+|`MEMORYDUMP` |= `FALSE`
|`MINBINEMITTED` |= `10`
|`MINSTEPFORREBIN` |= `200`
-|`SCSOLVEFREQ` |= `1`
|`MTSSUBSTEPS` |= `1`
-|`REMOTEPARTDEL` |= `0`
-|`RHODUMP` |= `FALSE`
-|`EBDUMP` |= `FALSE`
-|`CSRDUMP` |= `FALSE`
-|`AUTOPHASE` |= `6`
+|`NLHS` |= `1`
|`NUMBLOCKS` |= `0`
+|`PSDUMPEACHTURN` |= `FALSE`
+|`PSDUMPFRAME` |= `GLOBAL`
+|`PSDUMPFREQ` |= `10`
|`RECYCLEBLOCKS` |= `0`
-|`NLHS` |= `1`
-|`CZERO` |= `FALSE`
+|`REBINFREQ` |= `100`
+|`REMOTEPARTDEL` |= `0.0`
+|`REPARTFREQ` |= `10`
+|`RHODUMP` |= `FALSE`
|`RNGTYPE` |= `RANDOM`
-|`ENABLEHDF5` |= `TRUE`
-|`ENABLEVTK` |= `TRUE`
-|`ASCIIDUMP` |= `FALSE`
-|`BOUNDPDESTROYFQ` |= `10`
-|`BEAMHALOBOUNDARY` |= `0.0`
-|`CLOTUNEONLY` |= `FALSE`
-|`IDEALIZE` |= `FALSE`
-|`LOGBENDTRAJECTORY` |= `FALSE`
+|`SCSOLVEFREQ` |= `1`
+|`SEED` |= `123456789`
+|`SPTDUMPFREQ` |= `1`
+|`STATDUMPFREQ` |= `10`
+|`TELL` |= `FALSE`
+|`TRACE` |= `FALSE`
|`VERSION` |= `none`
-|`AMR` |= `FALSE`
-|`AMR_YT_DUMP_FREQ` |= `10`
-|`AMR_REGRID_FREQ` |= `10`
-|`MEMORYDUMP` |= `FALSE`
-|`HALOSHIFT` |= `0.0`
-|`DELPARTFREQ` |= `1`
-|`COMPUTEPERCENTILES`|= `FALSE`
-|`DUMPBEAMMATRIX` |= `FALSE`
+|`WARN` |= `TRUE`
+| |
|=======================================================================
[[sec.consumption.parameter]]