The following variables specify the properties of simulations that are performed via the ParaDRAM routine of ParaMonte library. The abbreviation ParaDRAM stands for Parallel DelayedRejection Adaptive MetropolisHastings Markov Chain Monte Carlo. The simulation specifications listed on this page can appear either in an external input file whose path is passed to the ParaDRAM sampler from within any programming environment or can be set as ParaDRAM sampler object components from within specific programming environments such as MATLAB and Python. Refer to the corresponding programming language documentations for more details on the usage.
Base specifications
description
The simulation specification description
is a scalar string of maximum length 8191
characters containing general information about the simulation to be performed. It has no effects on the simulation and serves only as a general description for future reference. The sampler parser automatically recognizes the Cstyle '\n'
escape sequence as the newline character and '\\'
as the backslash character '\'
if used in the contents of description
. For example, '\\n'
will be converted to '\n'
on the output, while '\n'
translates to the newline character. The default value for description
is 'UNDEFINED'
.
domain
The simulation specification domain
is a scalar string of maximum length 63
, containing the model’s name that defines the objective function’s domain. The string value must be enclosed by either single or double quotation marks when provided as input. The following domain models are currently supported:

domain = 'cube'
This is equivalent to a
ndim
dimensional hypercube (ncube) whose upper and lower bounds are specified by the input simulation specificationsdomainCubeLimitUpper
anddomainCubeLimitLower
respectively. 
domain = 'ball'
This is equivalent to a
ndim
dimensional hyperellipsoid (nball) whose center and covariance matrix can be specified by the input simulation specificationdomainBallAvg
anddomainBallCov
respectively. Alternatively, the user can let the ParaMonte samplers construct the covariance matrix of the ellipsoidal domain from the input values for thedomainBallCor
anddomainBallStd
simulation specifications. Note that a spherical domain can be defined by dropping thedomainBallCov
anddomainBallCor
specifications from the input and setting all elements ofdomainBallStd
to the desired radius of the domain.
The default value for domain
is an infinite cube for the ParaDRAM and ParaDISE samplers, and a unitsized cube for the ParaNest sampler.
Related specifications: domain, domainBallAvg, domainBallCor, domainBallCor, domainBallCov, domainBallStd, domainCubeLimitLower, domainCubeLimitUpper.
domainAxisName
The simulation specification domainAxisName
is a vector of scalar string values, each element of which contains the names of the corresponding axis of the density function domain (to be explored/sampled). It is used to construct the headers of the simulation output files. Any element of domainAxisName
not set by the user will automatically be assigned a default name. If all elements of domainAxisName
are set to the same value, then a number will be suffixed to each element representing the ID of the corresponding dimension of the domain of the density function. The default value for domainAxisName
is ‘sampleStatei’, where the integer 'i'
at the end of the name is replaced by the index of the corresponding domain axis.
domainBallAvg
The simulation specification domainBallAvg
is a vector of type real
of the highest precision supported by the ParaMonte library, of size ndim
containing the coordinates of the center of the hyperellipsoidal (or spherical) ndim
dimensional domain of the objective function, such that all states X(1 : ndim)
visited by the sampler would obey the following inequality:
where \(\mu\) represents the specification domainBallAvg
and \(\Sigma^{1}\) is the inverse of the specification domainBallCov
.
When passed to the sampler from within an external input file, every missing element of domainBallAvg
will be set to the origin (zero). Together with domainBallCov
, or with domainBallCor
and domainBallStd
, it forms a hyperellipsoidal or hyperspherical domain for the ParaMonte samplers. Note that an ellipsoidal/spherical domain is used if and only if the input simulation specification domain
is set to ‘ellipsoid’ or ‘sphere’ or ball
. Otherwise, a cubical domain will be used. The key Avg
(standing for Average
) is used in the name of this variable to denote the center of the hyperellipsoid. The default value for domainBallAvg
is the origin (i.e., a zerovalued vector of size ndim
).
Related specifications: domain, domainBallAvg, domainBallCor, domainBallCor, domainBallCov, domainBallStd.
domainBallCor
The simulation specification domainBallCor
is a positivedefinite matrix of type real
of the highest precision available in the ParaMonte Library of size (ndim, ndim)
representing the correlation matrix of the domain of the objective function, where ndim
is the dimension of the domain, such that all states X(1 : ndim)
visited by the sampler would obey the following inequality:
where \(\mu\) represents the specification domainBallAvg
and \(\Sigma^{1}\) is the inverse of \(\Sigma\) computed as,
where \(\rho\) stands for specification domainBallCor
and \(\mathrm{eye}(V)\) stands for diagonal matrix whose diagonals are set to the specification domainBallStd
.
Combined with the input simulation specification domainBallStd
it defines the objective function’s hyperellipsoidal (or spherical) domain. If the input simulation specification domainBallCov
is provided by the user, then any values set for domainBallCor
and domainBallStd
will be automatically ignored. The input specification domainBallCor
along with domainBallStd
are especially useful when covariance matrix computation is nontrivial. When passed to the sampler from within an external input sampler specification file, any missing element of domainBallCov
will be set to the appropriate default value. The default value for domainBallCor
is a ndim
byndim
Identity matrix.
Related specifications: domain, domainBallAvg, domainBallCor, domainBallCor, domainBallCov, domainBallStd.
domainBallCov
The simulation specification domainBallCov
is a positivedefinite matrix of type real
of the highest precision available in the ParaMonte Library of size (ndim, ndim)
representing the Gramian matrix of the domain of the objective function, where ndim
is the dimension of the domain, such that all states X(1 : ndim)
visited by the sampler would obey the following inequality:
where \(\mu\) represents the specification domainBallAvg
and \(\Sigma^{1}\) is the inverse of the specification domainBallCov
.
If the user provides this input simulation specification, any values set for the input simulation specifications domainBallCor
and domainBallStd
will be automatically ignored. When set from inside an external input ParaMonte specification file, any missing element of domainBallCov
will be set to the appropriate default value. To specify a ndim
dimensional spherical domain, set domainBallCov
to the identity matrix whose diagonal elements are radiussquared of the desired hypersphere (nball). The default value for domainBallCov
is a ndim
byndim
Identity matrix for simulations (such as the ParaNest integrator) that require a finite domain and a ndim
byndim
diagonal matrix whose diagonals are practically set to infinity for simulations that do not require a finite domain (such as the ParaDRAM and ParaDISE MCMC samplers).
Note: The use of
Cov
in the name of this simulation specification is theoretically incorrect as the domain of the objective function is not a distribution. Even if it is considered a hyperellipsoidal uniform distribution this specification would still not represent its covariance matrix because it represents the Gramian matrix. However, the decision was made to name this specification asCov
because of its nice fit to the rest of the relevant simulation specifications and user familiarity with keywords.
Related specifications: domain, domainBallAvg, domainBallCor, domainBallCor, domainBallCov, domainBallStd.
domainBallStd
The simulation specification domainBallStd
is a positivevalued vector of type real
of the highest precision available within the ParaMonte library, of size ndim
, where ndim
is the dimension of the domain of the objective function. It represents the square roots of the diagonal elements of the covariance matrix of the domain of the objective function, such that all states X(1 : ndim)
visited by the sampler would obey the following inequality:
where \(\mu\) represents the specification domainBallAvg
and \(\Sigma^{1}\) is the inverse of \(\Sigma\) computed as,
where \(\rho\) stands for specification domainBallCor
and \(\mathrm{eye}(V)\) stands for diagonal matrix whose diagonals are set to the specification domainBallStd
.
If the covariance matrix of the ellipsoidal/spherical domain (domainBallCov
) is missing from the input specifications to the sampler, then domainBallStd
(along with the input specification domainBallCor
) will be used to construct the covariance matrix of the domain of the objective function. However, if domainBallCov
is present among the input specifications to the sampler, then the input values for domainBallStd
and domainBallCor
will be ignored, and domainBallCov
will be used to construct the domain of the userspecified objective function. To specify a ndim
dimensional spherical domain, drop domainBallCov
and domainBallCor
from the input and set all elements of domainBallStd
to the desired radius of the hyperspherical domain. The default value for any missing elements of domainBallStd
is 1
for simulations requiring a finite domain (such as the ParaNest integrator) and +Infinity
for simulations not requiring a finite domain (such as the ParaDRAM and ParaDISE samplers).
Note: The use of
Std
in the name of this simulation specification is theoretically incorrect as the domain of the objective function is not a distribution. Even if it is considered a hyperellipsoidal uniform distribution, this specification would still not represent its vector of standard deviations. However, the decision was made to name this specification asStd
because of its nice fit to the rest of the relevant simulation specifications and user familiarity with keywords.
Related specifications: domain, domainBallAvg, domainBallCor, domainBallCor, domainBallCov, domainBallStd.
domainCubeLimitLower
The simulation specification domainCubeLimitLower
is a vector of type real
of the highest precision available within the ParaMonte library, of size ndim
where ndim
is the number of dimensions of the domain of the target density function. It contains the lower boundaries of the cubical domain of the objective function to be sampled. When domainCubeLimitLower
is specified inside an external input file supplied to the sampler, it is also possible to assign only select values of domainCubeLimitLower
and leave the rest of the components to be assigned the default value. For example, having the following inside the input file,

domainCubeLimitLower(3:5) = 100
will only set the lower limits of the third, fourth, and fifth dimensions to
100
, or, 
domainCubeLimitLower(1) = 100, domainCubeLimitLower(2) = 1.e6
will set the lower limit on the first dimension to
100
, and1.e6
on the second dimension, or, 
domainCubeLimitLower = 3*2.5e100
will only set the lower limits on the first, second, and third dimensions to
2.5*10^100
, while the remaining lower limits for the missing dimensions will be automatically set to the default value.
The default value for all elements of domainCubeLimitLower
is 0.13407807929942596E+155
.
Beware that some ParaMonte samplers, such as ParaNest, require the user to specify the domain boundaries explicitly.
Related specifications: domain, domainCubeLimitLower, domainCubeLimitUpper.
domainCubeLimitUpper
The simulation specification domainCubeLimitUpper
is a vector of type real
of the highest precision available within by the ParaMonte library, of size ndim
where ndim
is the number of dimensions of the domain of the target density function. It contains the upper boundaries of the cubical domain of the objective function to be sampled. When domainCubeLimitUpper
is specified inside an external input file supplied to the sampler, it is also possible to assign only select values of domainCubeLimitUpper
and leave the rest of the components to be assigned the default value. For example,

domainCubeLimitUpper(3:5) = 100
will only set the upper limits of the third, fourth, and fifth dimensions to 100, or,

domainCubeLimitUpper(1) = 100, domainCubeLimitUpper(2) = 1.e6
will set the upper limit on the first dimension to
100
, and 1.e6 on the second dimension, or, 
domainCubeLimitUpper = 3 * 2.5e100
will only set the upper limits on the first, second, and third dimensions to
2.5*10^100
, while the remaining upper limits for the missing dimensions will be automatically set to the default value.
The default value for all elements of domainCubeLimitUpper
is 0.13407807929942596E+155
.
Beware that some ParaMonte samplers, such as ParaNest, require the user to specify the domain boundaries explicitly.
Related specifications: domain, domainCubeLimitLower, domainCubeLimitUpper.
domainErrCount
The simulation specification domainErrCount
is a scalar of type integer
beyond which the user will be warned about the newly proposed points excessively falling outside the domain of the objective function. For every domainErrCount
consecutivelyproposed new points that fall outside the domain of the objective function, the user will be warned until domainErrCount = domainErrCountMax
, in which case the sampler returns a fatal error and the program stops globally. The counter for this warning is reset after a proposal sample from within the domain of the objective function is obtained. When outofdomain sampling happens frequently, it strongly indicates something fundamentally wrong in the simulation. It is, therefore, important to closely inspect and monitor for frequent outofdomain samplings. This can be done by setting domainErrCount
to an appropriate value determined by the user. The default value for domainErrCount
is 10000
.
Related specifications: domainErrCount, domainErrCountMax.
domainErrCountMax
The simulation specification domainErrCountMax
is a scalar of type integer
beyond which the program will stop globally with a fatal error message declaring that the maximum number of proposaloutofdomainbounds has reached. The counter for this globalstop request is reset after a proposal is accepted as a sample from within the domain of the objective function. When outofdomain sampling happens frequently, it strongly indicates something fundamentally wrong in the simulation. It is, therefore, important to closely inspect and monitor for frequent outofdomain samplings. This can be done by setting domainErrCountMax
to an appropriate value determined by the user. The default value for domainErrCountMax
is 100000
.
Related specifications: domainErrCount, domainErrCountMax.
inputFileHasPriority
The simulation specification inputFileHasPriority
is a scalar of type logical
(Boolean) of default kind. If it is set to the logical true value (e.g., .true.
, true
or .t.
from within an external input file), then, the input specifications of the simulation will be read from the userspecified input specification file and the simulation specification assignments from within the programming language environment (if any are made) will be completely ignored. If inputFileHasPriority
is set to the logical false value, then all simulation specifications that are taken from the userspecified input file will be overwritten by their corresponding userset input values from within the user programming environment (if such specifications are set). This feature is useful when, for example, some simulation specifications have to be computed and specified at runtime and, therefore, cannot be specified before the program execution. Currently, this functionality (i.e., prioritizing the input file values to inputprocedureargument values) is available only in the Fortran interface to the ParaMonte library routines. It can be set exclusively within an external input file, and its value is ignored in nonFortran programming language simulation environments. The default value for inputFileHasPriority
is FALSE
.
outputChainFileFormat
The simulation specification outputChainFileFormat
is a scalar string of maximum length 15
characters representing the sampler output chain file(s) format. If specified within an external input file, it must be singly or doubly quoted. Three values are possible:

outputChainFileFormat = 'compact'
oroutputChainFileFormat = 'ascii'
This is the ASCII (text) file format, which is humanreadable but does not preserve the full accuracy of the output values. It is also a significantly slower chain file generation mode than the binary file format (see below). If the compact format is specified, each of the repeating visited states in the simulation will be condensed into a single entry (row) in the output simulation chain file. Each entry will be then assigned a sample weight that is equal to the number of repetitions of that state in the chain. Thus, each row in the output chain file will represent a unique sample from the objective function. This will lead to a significantly smaller ASCII chain file and faster output size than the verbose chain file format (see below).

outputChainFileFormat = 'verbose'
This is the ASCII (text) file format, which is humanreadable but does not preserve the full accuracy of the output values. It is also a significantly slower chain file generation mode compared to compact and binary chain file formats (see above and below). If the verbose format is specified, all visited states will have equal sampling weights of
1
in the output simulation chain file. The verbose format can lead to much larger chain file sizes than the compact and binary file formats. This is especially true if the target objective function has a highdimensional domain. 
outputChainFileFormat = 'binary'
This is the binary file format, which is not humanreadable but preserves the exact values in the output chain file. It is also often the fastest mode of chain file generation. If the binary file format is chosen, the chain will be automatically output in the compact format (but as binary) to ensure the production of the smallest possible output chain file. Binary chain files will have the .bin file extensions. Use the binary format if you need full accuracy representation of the output values while having the smallestsize output chain file in the shortest time possible.
The default value for outputChainFileFormat
is 'compact'
, which provides a reasonable tradeoff between speed and output file size for the specified simulation task. The input values are caseINsensitive.
Related specifications: outputChainFileFormat, outputRestartFileFormat.
outputColumnWidth
The simulation specification outputColumnWidth
is a nonnegative scalar of type integer
that determines the width of the data columns in the formatted tabular files outputted by the sampler. If it is set to zero, the sampler will ensure that the width of each output element is the minimum possible value without losing the requested output precision. In other words, setting outputColumnWidth = 0
will result in the smallest size for the formatted output files in ASCII format. The default value for outputColumnWidth
is 0
.
Related specifications: outputColumnWidth, outputPrecision, outputSeparator.
outputFileName
The simulation specification outputFileName
is a scalar string of maximum length 4096
containing the path and the base of the filename for the sampler output files. If not provided by the user, the default outputFileName
is constructed from the current date and time:
sampler_yyyymmdd_hhmmss_mmm
where sampler
is replaced with the name of the ParaMonte sampler invoked, and yyyy
, mm
, dd
, hh
, mm
, ss
, and mmm
are replaced with the current year, month, day, hour, minute, second, and millisecond. In such a case, the output files’ default directory will be the sampler’s current working directory. If outputFileName
is provided but ends with a separator character ‘/’ or ‘' (as in Unix or Windows OS), then its value will be used as the directory to which the sampler output files will be written. In this case, the default output file naming convention described above will be used. The specified directory will be automatically created if it does not exist already. Note that the specified path is leftadjusted and rightpadded, erasing all trailing whitespace characters. The value of outputFileName
is always automatically suffixed with _run<i>_pid<j>_<type>.<ext>
where

<ext>
is replaced with an appropriate file extension, typically.txt
or.bin
, depending on the type of the file contents, 
<type>
is replaced with the simulation file type (e.g.,chain
,report
,sample
,restart
, etc), 
<j>
is replaced with the process (image/thread) ID (PID) that generates the current simulation file, 
<i>
is replaced with the simulation run number which depends on the existence of previous simulation files with the same file name prefix and the specified value for the simulation specificationoutputStatus
.
Related specifications: outputFileName, outputStatus.
outputPrecision
The simulation specification outputPrecision
is a scalar of type integer
representing the precision (i.e., the number of significant digits) of the real and complex numbers in the output simulation files. Any positive integer is acceptable as the input value of outputPrecision
. However, any digits of the output real numbers beyond the actual accuracy of floatingpoint numbers (e.g., ~16 digits of significance for 64bit real
) will be meaningless and random. Set this variable to the precision of the requested floating point precision in the simulation (or to larger values) if full reproducibility of the simulation is needed in the future. However, keep in mind that higher precisions result in larger output files. This variable is ignored for binary output (if any occurs during the simulation). The binary output files preserve the full precision of numbers. The default value for outputPrecision
depends on the real
precision, e.g., 18
.
Related specifications: outputColumnWidth, outputPrecision, outputSeparator.
outputReportPeriod
The simulation specification outputReportPeriod
is a positivevalued scalar of type integer
. Every outputReportPeriod
calls to the objective function, sampling progress will be reported to the progress file. The default value for outputReportPeriod
is 1000
.
outputRestartFileFormat
The simulation specification outputRestartFileFormat
is a scalar string of maximum length 15
representing the output restart file(s) format used to restart an interrupted simulation. Two values are possible:

outputRestartFileFormat = 'binary'
This is the binary file format which is not humanreadable but preserves the exact values of the specification variables required for the simulation restart. This full accuracy representation is required to exactly reproduce an interrupted simulation. The binary format is also normally the fastest mode of restart file generation. Binary restart files will have the
.bin
file extensions. 
outputRestartFileFormat = 'ascii'
This is the ASCII (text) file format, which is humanreadable but does not preserve the full accuracy of the specification variables required for the simulation restart. It is also a significantly slower mode of restart file generation, compared to the binary format. Therefore, its usage should be limited to situations where the user wants to track the dynamics of simulation specifications throughout the simulation time. ASCII restart file(s) will have the
.txt
file extensions.
The default value for outputRestartFileFormat
is 'binary'
. Note that the input values are caseINsensitive.
Related specifications: outputChainFileFormat, outputRestartFileFormat.
outputSampleSize
The simulation specification outputSampleSize
is a nonzero scalar of type integer
whose value dictates the number of (hopefully, independent and identically distributed [i.i.d.]) samples to be drawn from the userprovided objective function. Three ranges of values are possible. If

outputSampleSize < 0
,then, the absolute value of
outputSampleSize
dictates the sample size in units of the effective sample size. The effective sample is, by definition, i.i.d., free from duplicates and residual autocorrelation. The effective sample size is automatically determined by the sampler toward the end of the simulation. For example:
outputSampleSize = 1
yields the effective i.i.d. sample drawn from the objective function. 
outputSampleSize = 2
yields a (potentially noni.i.d.) sample twice as big as the effective sample.


outputSampleSize > 0
,then, the sample size is assumed to be in units of the number of points to be sampled. If outputSampleSize turns out to be less than effectiveSampleSize, the resulting sample will be i.i.d.. If outputSampleSize turns out to be larger than effectiveSampleSize, the resulting sample will be potentially noni.i.d.. The larger this difference, the more noni.i.d. the resulting final refined sample will be. For example:
outputSampleSize = 1000
yields a1000
points sample from the objective function.
The default value for outputSampleSize
is 1
.
outputSeparator
The simulation specification outputSeparator
is a scalar string of maximum length 63
containing a sequence of one or more allowed characters used to separate fields within records of tabular contents in the simulation output files. Digits, the period symbol '.'
, and the addition and subtraction operators: '+'
and ''
) are not allowed. To output in CommaSeparatedValues (CSV) format, set outputSeparator = ','
. If the input value is not provided, the default separator ','
will be used when input outputColumnWidth = 0
, and a single space character, ‘,’ will be used when input outputColumnWidth > 0
. A value of '\t'
is interpreted as the TAB character. To avoid this interpretation, use ‘\\t’ to yield ‘\t’ without being interpreted as the TAB character. The default value for outputSeparator
is ','
.
Related specifications: outputColumnWidth, outputPrecision, outputSeparator.
outputSplashMode
The simulation specification outputSplashMode
is a scalar string of maximum length 63
representing the level of information output on screen while running or postprocessing the simulation. Three values are possible:

outputSplashMode = 'normal'
Under this option, the simulation splash and progress bar will be shown on screen in addition to all postprocessing details. This is the default behavior in compiled language environments (e.g., C, C++, Fortran, …).

outputSplashMode = 'quiet'
Under this option, the splash screen will be hidden from the standard output but other information will be displayed as usual. This is the default behavior in dynamic language environments (e.g., MATLAB, Python, R, …).

outputSplashMode = 'silent'
Under this option, no information about the simulation will be shown on screen. Use this option if the simulations are expected to be short and straightforward or if the amount of text allowed for display in standard output is limited. This situation happens, for example, in online code coverage and CI platforms.
The default value for outputSplashMode
is 'normal'
in compiled programming language environments and 'quiet'
in dynamic programming language environments. Note that the input values are caseINsensitive.
outputStatus
The simulation specification outputStatus
is a scalar string with a maximum length of 15
characters, whose value describes the protocol for dealing with and handling the simulation output files concerning potentially existing past simulations. The string value must be enclosed by single or double quotation marks when provided as input in an external input file. Three values are possible:

outputStatus = 'extend'
This is the default behavior where the sampler will search for any prior simulation output files with the same userspecified file name prefix in the working directory to restart the simulation. If an old interrupted set of simulation output files exists in the working directory, the sampler will attempt to restart the simulation from the last recorded simulation state. The restart operation may fail if the user has modified or tampered with the old simulation output files. If prior simulation files exist and represent a complete simulation, a new simulation run will be performed with a new set of output files starting from the last successful run. The parameters of the new simulation are initialized based on the output of the most recent successful simulation. For MCMC simulations, this means starting from the last sampled point in the output sample file of the previous simulation and using an initial proposal covariance matrix constructed from the output sample of the previous simulation. A new simulation will start if the sampler does not find any prior simulations with the same output file names. This default behavior allows seamless restart functionality while ensuring old potentially valuable computationally expensive simulations are not inadvertently erased and replaced by the new simulation output files.

outputStatus = 'repeat'
This option is nearly identical to ‘extend’ except that the new simulation specifications are not initialized from the specifications of the last successful simulation run (if any exist). Instead, a new set of simulation files will be generated as if the last simulation run is replicated. If the simulation configuration has not changed since the last successful simulation run, then the new simulation output sample, chain, and restart files will be identical to those of the last successful simulation. This outputting is primarily useful for crossplatform or crosscompiler testing and development.

outputStatus = 'retry'
This option is nearly identical to ‘repeat’ except that the new simulation starts afresh and overwrites any potentially existing output files from the most recent simulation with the same names without ever using them. There is no restart functionality with this option. The most recent simulation files are deleted regardless of completion status. This option is effectively equivalent to deleting the set of output files from the last simulation run and rerunning the simulation with the default value ‘extend’ for the specification
outputStatus
. Use this option for quick tests or small exploratory problems where lots of quick runs must be performed.
The default value for outputStatus
is 'extend'
. The input values are caseINsensitive.
Related specifications: outputFileName, outputStatus.
parallelism
The simulation specification parallelism
is a scalar string of maximum length 63
that represents the parallelization method to be used in the simulation. The string value must be enclosed by single or double quotation marks when provided in an external input file. Two options are currently supported:

parallelism = 'multiChain'
This method uses the Perfect Parallelism scheme, in which multiple MCMC chains are generated independently of each other. In this case, multiple output MCMC chain files will also be generated. The Perfect parallelism option is available only in Coarray/MPIenabled parallel simulations (not in OpenMP or other sharedmemory). However, it can be readily emulated by running multiple independent simulations concurrently in any programming environment.

parallelism = 'singleChain'
This method uses the forkstyle parallelization scheme. In this case, a single MCMC chain file will be generated. At each MCMC step, multiple proposal steps will be checked in parallel until one proposal is accepted. This is the default for all parallelism paradigms supported by the ParaMonte library and the only option for shared memory parallelism.
Note that in serial mode, there is no parallelism. Therefore, this option does not affect nonparallel simulations and ignores its value. The serial mode is equivalent to either of the parallelism methods with only one simulation image (processor, core, or thread). The default value for parallelism
is 'singleChain'
. Note that the input values are caseINsensitive and whitespace characters are ignored.
Related specifications: parallelism, parallelismMpiFinalizeEnabled, parallelismNumThread.
parallelismMpiFinalizeEnabled
The simulation specification parallelismMpiFinalizeEnabled
is a scalar of type logical
(Boolean). In MPI parallel simulations, if parallelismMpiFinalizeEnabled
is set to the logical/Boolean true value, then a call will be made to the MPI_Finalize()
routine from inside the ParaMonte routine at the end of the simulation to finalize the MPI communications. Set this variable to the logical/Boolean if you do not want the ParaMonte library to finalize the MPI communications for you. When this specification is set within an external input file, the values F
, False
, false
, FALSE
, and .false.
all represent the logical true value, and the values T
, True
, true
, TRUE
, and .true.
all represent the logical true value. This is a lowlevel simulation specification variable relevant to MPI parallelism simulations. If you do not use MPIroutine calls in your main program, you can safely ignore this variable with its default value. If you intend the ParaMonte samplers or other MPIenabled ParaMonte routines repeatedly in one run, then you will have to parallelismMpiFinalizeEnabled
to the logical false
value to prevent early finalization of the MPIlibrary. Note that in nonMPIenabled simulations, such as serial and Coarrayenabled simulations, the value of this variable is completely ignored. The default value for parallelismMpiFinalizeEnabled
is TRUE
.
Related specifications: parallelism, parallelismMpiFinalizeEnabled, parallelismNumThread.
parallelismNumThread
The simulation specification parallelismNumThread
is a nonnegative scalar of type integer
of kind 32bit, representing the number of parallel userspecified objective function evaluations in a ForkJoin sharedmemory parallelism. Such parallelism paradigms include OpenMPenabled sharedmemory parallel simulations in C, C++, and Fortran or sharedmemory simulations in higherlevel programming language environments such as MATLAB, Python, and R. This specification is currently relevant to only OpenMPenabled parallel ParaMonte library builds or in the context of dynamic interpreted programming languages such as those mentioned above. As such, its value or presence is ignored in serial simulations or Coarray/MPIenabled parallel simulations. Specifying 0
leads to using all available CPU threads for the requested simulation. The default value for parallelismNumThread
is 0
, which implies using the maximum number of available threads in concurrent or OpenMPenabled builds of the ParaMonte library.
Related specifications: parallelism, parallelismMpiFinalizeEnabled, parallelismNumThread.
randomSeed
The simulation specification randomSeed
is a positive scalar of type integer
of kind 32bit whose value serves as the seed of the random number generator. When specified by the user, the seed of the simulation random number generator will be set in a specific deterministic manner to enable future replications of the simulation with the same configuration and input specifications. The default for randomSeed
is a processordependent random value to ensure complete simulation randomness at every run. In parallel simulations, the seed, whether default or userspecified, is uniquely set on all processors, threads, cores, or images in all circumstances to ensure simulation randomness.
targetAcceptanceRate
The simulation specification targetAcceptanceRate
is a vector of type real
of size 2
of the highest precision available within the ParaMonte library whose values (in the range [0, 1]
) determine the optimal target range for the simulation efficiency, defined as the ratio of the number of accepted objective function calls to the total number of function calls made through the simulation. The first and the second elements of targetAcceptanceRate
determine the lower and upper bounds of the desired acceptance rate, respectively. When the acceptance rate of the sampler is outside the specified limits, the simulation settings will be automatically adjusted to bring the overall acceptance rate to within the userspecified limits given by targetAcceptanceRate
. When assigned from within a dynamiclanguage programming environment (such as MATLAB, Python, or R) or within an input file, targetAcceptanceRate
can also be a scalar real number in the range [0, 1]
. In such a case, the sampler will constantly attempt (albeit with no guarantee of success) to bring the average acceptance ratio of the sampler as close to the userprovided target ratio as possible. Specifically, the success of the adaptive MCMC samplers (e.g., ParaDRAM) in keeping the average acceptance ratio close to the requested target value depends heavily on:
 the specified value of
proposalAdaptationPeriod
; the larger, the easier.  the specified value of
proposalAdaptationCount
; the larger, the easier.
Note that the acceptance ratio adjustments will only occur in every proposalAdaptationPeriod
sampling step for a total number of proposalAdaptationCount
in adaptive MCMC samplings. The default value for targetAcceptanceRate
is the range [0, 1]
.
MCMC specifications
outputChainSize
The simulation specification outputChainSize
is a positive scalar of type integer
whose value determines the number of nonrefined, potentially autocorrelated, but unique samples drawn by the MCMC sampler before stopping the sampling. For example, if outputChainSize = 10000
, then 10000
unique sample points (with no duplicates) will be drawn from the target objective function that the user has provided. The input value for outputChainSize
must be a positive integer of a minimum value ndim + 1
or larger, where ndim
is the number of dimensions of the domain of the objective function to be sampled. Note that outputChainSize
is different from and always smaller than the length of the constructed MCMC chain. The default value for outputChainSize
is 100000
.
Related specifications: outputSampleSize, outputSampleRefinementCount, outputSampleRefinementMethod.
outputSampleRefinementCount
The simulation specification outputSampleRefinementCount
is a positivevalued scalar of type integer
. When outputSampleSize < 0
, the value of outputSampleRefinementCount
dictates the maximum number of times the MCMC chain will be refined to remove the autocorrelation within the output MCMC sample. For example,

if
outputSampleRefinementCount = 0
,no refinement of the output MCMC chain will be performed. The resulting MCMC sample will correspond to the full MCMC chain in verbose format (i.e., each sampled state has a weight of one).

if
outputSampleRefinementCount = 1
,the refinement of the output MCMC chain will be done only once if needed, and no more, even though some residual autocorrelation in the output MCMC sample may still exist. In practice, only one refinement of the final output MCMC chain should be enough to remove the existing autocorrelations in the final output sample. Exceptions occur when the integrated Autocorrelation (ACT) of the output MCMC chain is comparable to or larger than the length of the chain. In such cases, neither the BatchMeans method nor any other method of ACT computation will be able to compute the ACT accurately. Consequently, the samples generated based on the computed ACT values will likely not be i.i.d. and will still be significantly autocorrelated. In such scenarios, more than one refinement of the MCMC chain will be necessary. A tiny small sample size resulting from multiple refinements of the sample could be a strong indication of the bad mixing of the MCMC chain and the lack of convergence to the target objective function.

if
outputSampleRefinementCount > 1
,the refinement of the output MCMC chain will be done for a maximum
outputSampleRefinementCount
number of times, even though some residual autocorrelation in the final output MCMC sample may still exist. 
if
outputSampleRefinementCount >> 1
(e.g., comparable to or larger than the length of the MCMC chain),the refinement of the output MCMC chain will continue until the integrated autocorrelation of the resulting final sample is less than 2, virtually implying that an independent identically distributed (i.i.d.) sample from the target objective function has finally been obtained.
Note that to obtain i.i.d. samples from a multidimensional chain, the sampler will, by default, use the maximum of integrated Autocorrelation (ACT) among all chain dimensions to refine the chain. Note that the value specified for outputSampleRefinementCount
is used only when the variable outputSampleSize < 0
; otherwise, it will be ignored. The default value for outputSampleRefinementCount
is 2147483647
.
Related specifications: outputSampleSize, outputSampleRefinementCount, outputSampleRefinementMethod.
outputSampleRefinementMethod
The simulation specification outputSampleRefinementMethod
is a scalar string of maximum length 63
representing the method of computing the (integrated) AutoCorrelation Time (ACT) to be used in the simulation for refining the final output MCMC chain and sample. If specified within an external input file, it must be either singly or doubly quoted. Methods that are currently supported include:

outputSampleRefinementMethod = 'BatchMeans'
This method of computing the integrated Autocorrelation Time is based on the approach described in
SCHMEISER, B., 1982, Batch size effects in the analysis of simulation output, Oper. Res. 30 556568.
The batch sizes in the BatchMeans method are chosen to be
int(N^(2/3))
, whereN
is the length of the MCMC chain. As long as the batch size is larger than the ACT of the chain and there are significantly more than10
batches, the BatchMeans method will provide reliable estimates of the ACT. Note that the refinement strategy involves two separate phases of sample decorrelation. At the first stage, the Markov chain is decorrelated recursively (for as long as needed) based on the ACT of its compact format, where only the uniquely visited states are kept in the (compact) chain. Once the Markov chain is refined such that its compact format is fully decorrelated, the second phase of the decorrelation begins, during which the Markov chain is decorrelated based on the ACT of the chain in its verbose (Markov) format. This process is repeated recursively for as long as residual autocorrelation exists in the refined sample. 
outputSampleRefinementMethod = 'BatchMeanscompact'
This is the same as the first case above, except that only the first phase of the sample refinement described above will be performed; that is, the (verbose) Markov chain is refined only based on the ACT computed from the compact format of the Markov chain. This will lead to a larger, final, refined sample. However, the final sample will likely not be fully decorrelated.

outputSampleRefinementMethod = 'BatchMeansverbose'
This is the same as the first case above, except that only the second phase of the sample refinement described above will be performed; that is, the (verbose) Markov chain is refined only based on the ACT computed from the verbose format of the Markov chain. While the resulting refined sample will be fully decorrelated, the size of the refined sample may be smaller than the default choice in the first case above.
Note that to obtain i.i.d. samples from a multidimensional chain, the sampler will use the average of the ACT among all dimensions of the chain to refine the chain. If the maximum, minimum, or median of IACs is preferred add 'max'
(or 'maximum'
), 'min'
(or 'minimum'
), 'med'
(or 'median'
), respectively, to the value of outputSampleRefinementMethod
. For example,
outputSampleRefinementMethod = 'BatchMeansmax'
or,
outputSampleRefinementMethod = 'BatchMeanscompactmax'
or,
outputSampleRefinementMethod = 'BatchMeansmaxcompact'
Note that the specified outputSampleRefinementCount
is used only when the condition outputSampleSize < 0
holds. Otherwise, it is ignored. The default value for outputSampleRefinementMethod
is 'BatchMeans'
. Note that the input values are caseINsensitive and whitespace characters are ignored.
Related specifications: outputSampleSize, outputSampleRefinementCount, outputSampleRefinementMethod.
proposal
The simulation specification proposal
is a scalar string of maximum length 63
containing the name of the proposal distribution for the MCMC sampler. When specified from within an external input file, it must be singly or doubly quoted. Options that are currently supported include:

proposal = 'normal'
This is equivalent to the multivariate normal distribution, which, for MCMC samplers, is the most widely used proposal model.

proposal = 'uniform'
The proposals will be drawn uniformly from within a ndimdimensional ellipsoid whose covariance matrix and scale are initialized by the user and optionally adaptively updated throughout the simulation.
The default value for proposal
is 'normal'
.
Related specifications: proposal, proposalCor, proposalCov, proposalStd.
proposalCor
The simulation specification proposalCor
is a positivedefinite square matrix of type real
of the highest precision available within the ParaMonte library matrix of size (ndim, ndim)
, where ndim
is the dimension of the sampling space. It serves as the bestguess starting correlation matrix of the proposal distribution used by the sampler. It is used (along with the input vector proposalStd
) to construct the covariance matrix of the proposal distribution when the input covariance matrix is missing in the input list of variables. If the covariance matrix is specified as input to the sampler, any input values for proposalCor
, and proposalStd
will be automatically ignored. Specifying proposalCor
along with proposalStd
is especially useful when obtaining the bestguess covariance matrix is not trivial. The default value for proposalCor
is a square Identity matrix of rank ndim
.
Related specifications: proposal, proposalCor, proposalCov, proposalStd.
proposalCov
The simulation specification proposalCov
is a square positivedefinite matrix of type real
of the highest precision available within the ParaMonte library, of shape (ndim, ndim)
, where ndim
is the number of dimensions of the sampling space. It serves as the bestguess starting covariance matrix of the proposal distribution. To bring the sampling efficiency of the sampler to within the desired requested range, the covariance matrix will be adaptively updated throughout the simulation according to the userspecified schedule. If proposalCov
is not provided by the user or it is completely missing from the input file, its value will be automatically computed via the input variables proposalCor
and proposalStd
(or via their default values, if not provided). If the simulation specification outputStatus
is set to “extend” and a successful prior simulation run exists, then proposalCov
will be set to the covariance matrix of the output sample from the most recent simulation run. In this case, the computed proposalCov
will override any userspecified value. Otherwise, the default value for proposalCov
is a square Identity matrix of rank ndim
.
Related specifications: proposal, proposalCor, proposalCov, proposalStd.
proposalScale
The simulation specification proposalScale
is a scalar string of maximum length 127
containing a positive realvalued number whose square will be multiplied with the covariance matrix of the proposal distribution of the MCMC sampler to shrink or enlarge it. In other words, the proposal distribution will be scaled in every direction by the specified numeric value of proposalScale
. It can also be given in units of the string keyword 'gelman'
(which is caseINsensitive) after the paper:
Gelman, Roberts, and Gilks (1996), Efficient Metropolis Jumping Rules.
The paper finds that the optimal scaling factor for a Multivariate Gaussian proposal distribution for the MetropolisHastings Markov Chain Monte Carlo sampling of a target Multivariate Normal Distribution of dimension ndim
is given by:
proposalScale = 2.38 / sqrt(ndim) , in the limit of ndim > Infinity.
Multiples of the Gelman scale factors are also acceptable as input and can be specified as in the following examples:

proposalScale = '1'
multiplies the ndimdimensional proposal covariance matrix by 1, essentially no change occurs to the covariance matrix.

proposalScale = "1"
same as the previous example. The doublequotation marks act the same way as singlequotation marks.

proposalScale = '2.5'
multiplies the ndimdimensional proposal covariance matrix by 2.5.

proposalScale = '2.5*Gelman'
multiplies the
ndim
dimensional proposal covariance matrix by 2.5 * 2.38/sqrt(ndim). 
proposalScale = "2.5 * gelman"
same as the previous example but with doublequotation marks. space characters are ignored.

proposalScale = "2.5 * gelman*gelman*2"
equivalent to gelmanFactorsquared multiplied by
5
.
Note, however, that the result of Gelman et al. paper applies only to multivariate normal proposal distributions in the limit of infinite dimensions. Therefore, care must be taken when using Gelman’s scaling factor with nonGaussian proposals and target objective functions. Only the product symbol *
can be parsed in the string value of proposalScale
. The presence of other mathematical symbols or multiple appearances of the product symbol will lead to a simulation crash. Also, note that the prescription of an acceptance range specified by the input variable targetAcceptanceRate
will lead to dynamic modification of the initial input value of proposalScale
throughout sampling for proposalAdaptationCount
times. The default string value for proposalScale
is "1"
(for all proposal distributions).
proposalStart
The simulation specification proposalStart
is a vector type of real
of the highest precision available within the ParaMonte library of length ndim
where ndim
is the dimension of the domain of the objective function. For every element of proposalStart
not provided as input, the default value will be the center of the sampling domain as determined by domainCubeLimitLower
and domainCubeLimitUpper
input specifications. If the condition proposalStartRandomized
is set to the logical/Boolean true value, then the missing elements of proposalStart
will be initialized to values drawn randomly from within the corresponding ranges specified by the input variables proposalStartDomainCubeLimitLower
and proposalStartDomainCubeLimitUpper
. If the simulation specification outputStatus
is set to “extend” and a prior successful simulation run exists, then proposalStart
will be set to the average of the sampled states of the most recent successful run. In this case, any userspecified value will be overridden by the computed proposalStart
.
Related specifications: proposalStart, proposalStartDomainCubeLimitLower, proposalStartDomainCubeLimitUpper, proposalStartRandomized.
proposalStartDomainCubeLimitLower
The simulation specification proposalStartDomainCubeLimitLower
is a vector of type real
of the highest precision available in the ParaMonet library of size ndim
is the number of dimensions of the domain of the objective function. It contains the lower boundaries of the cubical domain from which the starting point(s) of the MCMC chain(s) will be initialized randomly (only if requested via the input variable proposalStartRandomized
). This happens only when some or all of the input specification proposalStart
elements are missing. In such cases, every missing value of the input proposalStart
will be set to the center point between proposalStartDomainCubeLimitLower
and proposalStartDomainCubeLimitUpper
in the corresponding dimension. If proposalStartRandomized
is set to the logical/Boolean true value, then the missing elements of proposalStart
will be initialized to values drawn randomly from within the corresponding ranges whose lower limits are specified by the input proposalStartDomainCubeLimitLower
. When specified from within an external input file to the sampler, it is also possible to assign only select values of proposalStartDomainCubeLimitLower
and leave the rest of the components to be assigned the default value. For example, having the following inside the input file,

proposalStartDomainCubeLimitLower(3:5) = 100
will only set the lower limits of the third, fourth, and fifth dimensions to 100, or,

proposalStartDomainCubeLimitLower(1) = 100, proposalStartDomainCubeLimitLower(2) = 1.e6
will set the lower limit on the first dimension to 100, and 1.e6 on the second dimension, or,

proposalStartDomainCubeLimitLower = 3*2.5e100
will only set the lower limits on the first, second, and third dimensions to
2.5*10^100
, while the rest of the lower limits for the missing dimensions will be automatically set to the default value.
The default for all proposalStartDomainCubeLimitLower
elements is taken from the corresponding elements of domainCubeLimitLower
.
Related specifications: proposalStart, proposalStartDomainCubeLimitLower, proposalStartDomainCubeLimitUpper, proposalStartRandomized.
proposalStartDomainCubeLimitUpper
The simulation specification proposalStartDomainCubeLimitUpper
is a vector of type real
of the highest precision available in the ParaMonet library of size ndim
is the number of dimensions of the domain of the objective function. It contains the upper boundaries of the cubical domain from which the starting point(s) of the MCMC chain(s) will be initialized randomly (only if requested via the input variable proposalStartRandomized
). This happens only when some or all of the input specification proposalStart
elements are missing. In such cases, every missing value of the input proposalStart
will be set to the center point between proposalStartDomainCubeLimitLower
and proposalStartDomainCubeLimitUpper
in the corresponding dimension. If proposalStartRandomized
is set to the logical/Boolean true value, then the missing elements of proposalStart
will be initialized to values drawn randomly from within the corresponding ranges whose upper limits are specified by the input proposalStartDomainCubeLimitUpper
. When specified from within an external input file to the sampler, it is also possible to assign only select values of proposalStartDomainCubeLimitUpper
and leave the rest of the components to be assigned the default value. For example, having the following inside the input file,

proposalStartDomainCubeLimitUpper(3:5) = 100
will only set the upper limits of the third, fourth, and fifth dimensions to
100
, or, 
proposalStartDomainCubeLimitUpper(1) = 100, proposalStartDomainCubeLimitUpper(2) = 1.e6
will set the upper limit on the first dimension to 100, and 1.e6 on the second dimension, or,

proposalStartDomainCubeLimitUpper = 3*2.5e100
will only set the upper limits on the first, second, and third dimensions to
2.5*10**100
, while the rest of the upper limits for the missing dimensions will be automatically set to the default value.
The default values for all elements of proposalStartDomainCubeLimitUpper
are taken from the corresponding values in the input variable domainCubeLimitUpper
.
Related specifications: proposalStart, proposalStartDomainCubeLimitLower, proposalStartDomainCubeLimitUpper, proposalStartRandomized.
proposalStartRandomized
The simulation specification proposalStartRandomized
is a scalar of type logical
(Boolean). If true
(or .true.
or TRUE
or .t.
from within an external input file), then the variable proposalStart
will be initialized randomly for each MCMC chain that is to be generated by the sampler. The random values will be drawn from the specified or the default domain of proposalStart
, given by proposalStartDomainCubeLimitLower
and proposalStartDomainCubeLimitUpper
variables. Note that the value of proposalStart
, if provided, has precedence over random initialization. In other words, only uninitialized elements of proposalStart
will be randomly initialized only if proposalStartRandomized
is set to the logical true value. Note that even if proposalStart
is randomly initialized, its random value will be deterministic between different independent simulation runs if the input variable randomSeed
is specified by the user. The default value is FALSE
.
Related specifications: proposalStart, proposalStartDomainCubeLimitLower, proposalStartDomainCubeLimitUpper, proposalStartRandomized.
proposalStd
The simulation specification proposalStd
is a positivevalued vector of type real
of the highest precision available within the ParaMonte library, of size ndim
, where ndim
is the dimension of the domain of the objective function. It serves as the bestguess starting standard deviation for each component of the proposal distribution. If the initial covariance matrix (proposalCov
) is missing as an input specification to the sampler, then proposalStd
(along with the specified proposalCor
) will be used to construct the initial covariance matrix of the proposal distribution of the MCMC sampler. However, if proposalCov
is specified for the sampler, then the input proposalStd
and proposalCor
will be completely ignored, and the input value for proposalCov
will be used to construct the initial covariance matrix of the proposal distribution. The default value of proposalStd
is a vector of size ndim
of unit values (i.e., ones).
Related specifications: proposal, proposalCor, proposalCov, proposalStd.
DRAM specifications
proposalAdaptationBurnin
The simulation specification proposalAdaptationBurnin
is a scalar of type real
of the highest precision available within the ParaMonte library whose value, between 0 and 1, represents the adaptation measure threshold below which the simulated Markov chain will be used to generate the output sample. In other words, any point in the output Markov chain sampled during significant adaptation of the proposal distribution (set by proposalAdaptationBurnin
) will not be included in constructing the final MCMC output sample. This is to ensure that the generation of the output sample will be based only on the part of the simulated chain that is practically guaranteed to be Markovian and ergodic. If this variable is set to 0, then the output sample will be generated from the part of the chain where no proposal adaptation has occurred. This nonadaptive or minimallyadaptive part of the chain may not even exist if the total adaptation period of the simulation, set by proposalAdaptationCount
and proposalAdaptationPeriod
input variables, is longer than the total length of the output MCMC chain. In such cases, the resulting output sample may be zero size. Generally, when good mixing occurs (e.g., when the input variable outputChainSize
is reasonably large), then any specific value of proposalAdaptationBurnin
becomes practically irrelevant. The default value for proposalAdaptationBurnin
is 1.0000000000000000
, implying that the entire chain (excluding an initial automaticallydetermined burnin period) will be used to generate the final output sample.
proposalAdaptationCount
The simulation specification proposalAdaptationCount
is a scalar of type integer
representing the total number of adaptive updates that will be made to the parameters of the proposal distribution to increase the efficiency of the sampler, thus increasing the overall sampling efficiency of the simulation. Every proposalAdaptationPeriod
number of calls to the objective function, the parameters of the proposal distribution will be updated until either the total number of adaptive updates reaches the value of proposalAdaptationCount
. This variable must be a nonnegative integer. As a rule of thumb, it may be appropriate to ensure the condition outputChainSize >> proposalAdaptationPeriod * proposalAdaptationCount
holds to improve the ergodicity and stationarity of the MCMC sampler. If proposalAdaptationCount
is zero, then the proposal distribution parameters will be fixed to the initial input values throughout the entire MCMC sampling. The default value is 2147483647
.
Related specifications: proposalAdaptationCount, proposalAdaptationCountGreedy, proposalAdaptationPeriod.
proposalAdaptationCountGreedy
The simulation specification proposalAdaptationCountGreedy
is a positivevalued scalar of type integer
representing the count of initial “greedy” adaptive updates the sampler will apply to the proposal distribution before starting regular adaptation. Greedy adaptations are made using only the ‘unique’ accepted points in the MCMC chain. This is useful, for example, when the function to be sampled by the sampler is high dimensional, in which case, the adaptive updates to proposal distribution will less likely lead to numerical instabilities, such as a singular covariance matrix for the multivariate proposal sampler. The variable proposalAdaptationCountGreedy
must be less than the specified value for proposalAdaptationCount
. If larger, it will be automatically reset to proposalAdaptationCount
for the simulation. The default value is 0
.
Related specifications: proposalAdaptationCount, proposalAdaptationCountGreedy, proposalAdaptationPeriod.
proposalAdaptationPeriod
The simulation specification proposalAdaptationPeriod
is a positivevalued scalar of type integer
. Every proposalAdaptationPeriod
calls to the objective function, the parameters of the proposal distribution will be updated. The smaller the value of proposalAdaptationPeriod
, the easier for the sampler kernel to adapt the proposal distribution to the covariance structure of the objective function. However, this will happen at the expense of slower simulation runtime as the adaptation process can become computationally expensive, particularly for very high dimensional objective functions (ndim >> 1
). The larger the value of proposalAdaptationPeriod
, the easier it will be for the sampler kernel to keep the sampling efficiency close to the requested target acceptance rate range (if specified via the input variable targetAcceptanceRate). However, too large values for proposalAdaptationPeriod
will only delay the adaptation of the proposal distribution to the global structure of the objective function that is being sampled. If outputChainSize <= proposalAdaptationPeriod
holds, no adaptive updates to the proposal distribution will be made. The default value is 4 * ndim
, where ndim
is the dimension of the domain of the objective function to be sampled.
Related specifications: proposalAdaptationCount, proposalAdaptationCountGreedy, proposalAdaptationPeriod.
proposalDelayedRejectionCount
The simulation specification proposalAdaptationPeriod
is a nonnegativevalued scalar of type integer
representing the total number of stages for which rejections of new proposals will be tolerated by the MCMC sampler before going back to the previously accepted point (state). The condition 0 <= proposalDelayedRejectionCount <= 1000
must hold. Possible values are:

proposalDelayedRejectionCount = 0
indicating no deployment of the delayed rejection algorithm.

proposalDelayedRejectionCount > 0
which implies a maximum proposalDelayedRejectionCount number of rejections will be tolerated.
For example, setting proposalDelayedRejectionCount
to 1
means that at any point during the sampling, if a proposal is rejected, the MCMC sampler will not return to the last sampled state. Instead, it will continue to propose a new state from the last rejected proposal. If the new state is again rejected based on the rules of the MCMC sampler, then the algorithm will not tolerate further rejections because the maximum number of rejections to be tolerated has been set by the user to be proposalDelayedRejectionCount = 1
. The algorithm then returns to the original lastaccepted state and will begin proposing new states from that location. The default value is 0
.
Related specifications: proposalDelayedRejectionCount, proposalDelayedRejectionScale.
proposalDelayedRejectionScale
The simulation specification proposalDelayedRejectionScale
is a positivevalued vector of type real
of the highest precision available within the ParaMonte library, of length (1 : proposalDelayedRejectionCount)
, by which the covariance matrix of the proposal distribution of the MCMC sampler is scaled when the Delayed Rejection (DR) scheme is activated (by setting proposalDelayedRejectionCount
to a positive value). At each i
th stage of the DR process, the proposal distribution from the last stage is scaled by the factor proposalDelayedRejectionScale(i)
. Missing elements of the proposalDelayedRejectionScale
in the input external file to the sampler will be set to the default value. The default value at all stages is 0.5**(1 / ndim)
, where ndim
is the number of dimensions of the domain of the objective function. This default value effectively reduces the volume of the covariance matrix of the proposal distribution by half compared to the last DR stage.
Related specifications: proposalDelayedRejectionCount, proposalDelayedRejectionScale.