Code indexing in gitaly is broken and leads to code not being visible to the user. We work on the issue with highest priority.

Skip to content
Snippets Groups Projects
Commit fa15e306 authored by ext-calvo_p's avatar ext-calvo_p
Browse files

Merge branch '96-update-option-command' into 'master' 

Resolve "Update OPTION command"

Closes #96

See merge request OPAL/documentation/manual!195
parents 41f2745d 029e1063
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 199 additions and 197 deletions
control.asciidoc
+ 199
− 197
View file @ fa15e306
......@@ -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]]
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment