The ParaDRAM simulation specifications

The variable 'description' contains general information about the specific ParaDRAM simulation 
that is going to be performed. It has no effects on the simulation and serves only as a general description 
of the simulation for future reference. The ParaDRAM parser automatically recognizes the C-style '\n' 
escape sequence as the new-line character, and '\\' as the backslash character '\' if they used in 
the description. For example, '\\n' will be converted to '\n' on the output, while '\n' translates 
to the new-line character. Other C escape sequences are neither supported nor needed. The default 
value for description is 'Nothing provided by the user.'.

A logical (boolean) variable. If TRUE (or .true. or true or .t. from within an input file), then the 
input specifications of the ParaDRAM simulation will be read from the input file provided by the user, and the 
simulation specification assignments from within the programming language environment (if any are made) 
will be completely ignored. If inputFileHasPriority is FALSE, then all simulation specifications of the 
ParaDRAM sampler that are taken from the user-specified input file will be overwritten by their 
corresponding input values that are set from within the user's programming environment (if any is provided). 
Note that this feature is useful when, for example, some simulation specifications have to 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 input-procedure-argument values) is available only in the 
Fortran-interface to the ParaDRAM sampler. The default value is FALSE.

A logical (boolean) variable. If TRUE (or .true. or true or .t. from within an input file), then 
the following contents will not be printed in the output report file of the ParaDRAM sampler:

    - The ParaMonte library interface, compiler, and platform specifications.
    - The ParaDRAM simulation specification descriptions.

Setting this variable to TRUE may break the functionality of the report-file parser methods of the 
ParaMonte library in high-level languages (e.g., MATLAB, Python, R, ...). The default value is FALSE.

domainLowerLimitVec represents the lower boundaries of the cubical domain of the objective function 
to be sampled. It is an ndim-dimensional vector of 64-bit real numbers, where ndim is the number of 
variables of the objective function. It is also possible to assign only select values of domainLowerLimitVec 
and leave the rest of the components to be assigned the default value. This is POSSIBLE ONLY when 
domainLowerLimitVec is defined inside the input file to the ParaDRAM sampler. For example, 
having the following inside the input file, 

    domainLowerLimitVec(3:5) = -100

            will only set the lower limits of the third, fourth, and the fifth dimensions to -100, 
            or,

    domainLowerLimitVec(1) = -100, domainLowerLimitVec(2) = -1.e6 

            will set the lower limit on the first dimension to -100, and 1.e6 on the second dimension, 
            or,

    domainLowerLimitVec = 3*-2.5e100

            will only set the lower limits on the first, second, and the 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 value for all elements of domainLowerLimitVec is: -1.797693134862316E+307.

domainUpperLimitVec represents the upper boundaries of the cubical domain of the objective function 
to be sampled. It is an ndim-dimensional vector of 64-bit real numbers, where ndim is the number of 
variables of the objective function. It is also possible to assign only select values of domainUpperLimitVec 
and leave the rest of the components to be assigned the default value. This is POSSIBLE ONLY when 
domainUpperLimitVec is defined inside the input file to the ParaDRAM sampler. For example,

    domainUpperLimitVec(3:5) = 100

            will only set the upper limits of the third, fourth, and the fifth dimensions to 100, or,

    domainUpperLimitVec(1) = 100, domainUpperLimitVec(2) = 1.e6 

            will set the upper limit on the first dimension to 100, and 1.e6 on the second dimension, 
            or,

    domainUpperLimitVec = 3*2.5e100

            will only set the upper limits on the first, second, and the 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 value for all elements of domainUpperLimitVec is: 1.797693134862316E+307.

variableNameList contains the names of the variables to be sampled. It is used to construct 
the header of the output sample file. Any element of variableNameList that is not set by the user 
will be automatically assigned a default name. The default value is 'SampleVariablei' where integer 
'i' is the index of the variable.

parallelizationModel is a string variable that represents the parallelization method to be used in 
the ParaDRAM sampler. The string value must be enclosed by either single or double 
quotation marks when provided as input. Two options are currently supported:

    parallelizationModel = 'multiChain'

            This method uses the Perfect Parallel scheme in which multiple MCMC chains are 
            generated independently of each other. In this case, multiple output MCMC chain files 
            will also be generated.

    parallelizationModel = 'singleChain'

            This method uses the fork-style parallelization scheme. A single MCMC chain file will be 
            generated in this case. At each MCMC step multiple proposal steps will be checked in 
            parallel until one proposal is accepted.

Note that in serial mode, there is no parallelism. Therefore, this option does not affect non-parallel 
simulations and its value is ignored. The serial mode is equivalent to either of the parallelism 
methods with only one simulation image (processor, core, or thread). The default value is 
parallelizationModel = 'singleChain'. Note that the input values are case-INsensitive and white-space 
characters are ignored.

In parallel ParaDRAM simulations via MPI communication libraries, if mpiFinalizeRequested = true 
(or T, both case-INsensitive), then a call will be made to the MPI_Finalize() routine from within the ParaDRAM 
sampler at the end of the simulation to finalize the MPI communications. Set this variable to false (or f, 
both case-INsensitive) if you do not want the ParaDRAM sampler to finalize the MPI communications for you. 
This is a low-level simulation specification variable, relevant to simulations that directly involve MPI 
parallelism. If you do not have any MPI-routine calls in your main program, you can safely ignore 
this variable with its default value. Note that in non-MPI-enabled simulations, such as serial and 
Coarray-enabled simulations, the value of this variable is completely ignored. The default value is 
TRUE.

outputFileName contains the path and the base of the filename for the ParaDRAM sampler output files. If not 
provided by the user, the default outputFileName is constructed from the current date and time:

    ParaDRAM_run_yyyymmdd_hhmmss_mmm

where yyyy, mm, dd, hh, mm, ss, mmm stand respectively for the current year, month, day, hour, minute, 
second, and millisecond. In such a case, the default directory for the output files will be the current 
working directory of the ParaDRAM sampler. If outputFileName is provided, but ends with a 
separator character '/' or '\' (as in Linux or Windows OS), then its value will be used as the directory to 
which the ParaDRAM sampler output files will be written. In this case, the output file naming 
convention described above will be used. Also, the given directory will be automatically created if 
it does not exist already.

A logical (boolean) variable. If true (or .true. or TRUE or .t. from within an input file), then any 
existing old simulation files with the same name as the current simulation will be overwritten with 
the new simulation output files. Note that if overwriteRequested is set to TRUE, then the restart 
functionality is automatically turned off and any existing old simulation output files with the 
same name as the current simulation will be overwritten by the ParaDRAM sampler. 
The default value is FALSE.

targetAcceptanceRate sets an optimal target for the ratio of the number of accepted objective function 
calls to the total number of function calls by the ParaDRAM sampler. It is a real-valued array of length 2, 
whose elements determine the upper and lower bounds of the desired acceptance rate. When the acceptance 
rate of the ParaDRAM sampler is outside the specified limits, the sampler's settings will be automatically adjusted 
to bring the overall acceptance rate to within the specified limits by the input simulation specification targetAcceptanceRate. 
When assigned from within a dynamic-language programming environment, such as MATLAB or Python, or from 
within an input file, targetAcceptanceRate can also be a single real number between 0 and 1. In such case, the 
ParaDRAM sampler will constantly attempt (with no guarantee of success) to bring the average acceptance ratio 
of the sampler as close to the user-provided target ratio as possible. The success of the ParaDRAM sampler 
in keeping the average acceptance ratio close to the requested target value depends heavily on:

    1) the value of adaptiveUpdatePeriod; the larger, the easier.
    2) the value of adaptiveUpdateCount; the larger, the easier.

Note that the acceptance ratio adjustments will only occur every adaptiveUpdatePeriod sampling 
steps for a total number of adaptiveUpdateCount. There is no default value for targetAcceptanceRate, 
as the acceptance ratio is not directly adjusted during sampling.

The variable sampleSize is an integer that dictates the number of (hopefully, independent and 
identically distributed [i.i.d.]) samples to be drawn from the user-provided objective function. 
Three ranges of values are possible. If, 

    sampleSize < 0,

            then, the absolute value of sampleSize dictates the sample size in units of the final 
            effective sample size generated by the sampler. The effective sample is by definition 
            i.i.d., and free from duplicates. The effective sample size is automatically determined 
            by ParaDRAM toward the end of the simulation.
            For example:    

                    sampleSize = -1 yields the effective i.i.d. sample drawn from the objective 
                    function.

                    sampleSize = -2 yields a (potentially non-i.i.d.) sample twice as big as the 
                    effective sample.

    sampleSize > 0,

            then, the specified value will represent the number of points to appear in the final 
            output sample file. If sampleSize turns out to be less than the estimated effective sample 
            size, then the resulting final sample will be i.i.d.. If sampleSize turns out to be larger 
            than the effective sample size, then the resulting sample will be potentially non-i.i.d.. 
            The larger this difference, the more non-i.i.d. the resulting final refined sample will be. 
            For example, 

                    sampleSize = 1000 yields a 1000-points final sample from the objective function.

    sampleSize = 0,

            in which case, no sample file will be generated.

The default value is sampleSize = -1. 

randomSeed is a scalar 32bit integer that serves as the seed of the random number generator. When it 
is provided, the seed of the 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 value for randomSeed is an integer vector of processor-dependent size and value that will 
vary from one simulation to another. However, enough care has been taken to assign unique random seed 
values to the random number generator on each of the parallel threads (or images, processors, cores, 
...) at all circumstances.

The variable outputColumnWidth is a non-negative integer number that determines the width of the data 
columns in the formatted output files of a ParaDRAM simulation with tabular structure. If it 
is set to zero, the ParaDRAM sampler will ensure to set the width of each output element to 
the minimum possible width without losing the requested output precision. In other words, setting 
outputColumnWidth = 0 will result in the smallest-size for the formatted output files that are in ASCII 
format. The default value is 0.

outputDelimiter is a string variable, containing a sequence of one or more characters (excluding 
digits, the period symbol '.', and the addition and subtraction operators: '+' and '-'), that is used 
to specify the boundary between separate, independent information elements in the tabular output 
files of the ParaDRAM sampler. The string value must be enclosed by either single or double 
quotation marks when provided as input. To output in Comma-Separated-Values (CSV) format, set 
outputDelimiter = ','. If the input value is not provided, the default delimiter ',' 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 is ','.

The variable outputRealPrecision is a 32-bit integer number that determines the precision - that is, 
the number of significant digits - of the real numbers in the output files of a ParaDRAM simulation. 
Any positive integer is acceptable as the input value of outputRealPrecision. However, any digits of the output 
real numbers beyond the accuracy of 64-bit real numbers (approximately 16 digits of significance) 
will be meaningless and random. Set this variable to 16 (or larger) if full reproducibility of the 
simulation is needed in the future. But keep in mind that larger precisions will result in larger-size 
output files. This variable is ignored for binary output (if any occurs during the simulation). The 
default value is 8.

chainFileFormat is a string variable that represents the format of the output chain file(s) of a 
ParaDRAM simulation. The string value must be enclosed by either single or double quotation 
marks when provided as input. Three values are possible:

    chainFileFormat = 'compact'

            This is the ASCII (text) file format which is human-readable but does not preserve the 
            full accuracy of the output values. It is also a significantly slower mode of chain file 
            generation, compared to the binary file format (see below). If the compact format is 
            specified, each of the repeating MCMC states will be condensed into a single entry (row) 
            in the output MCMC chain file. Each entry will be then assigned a sample-weight that is 
            equal to the number of repetitions of that state in the MCMC 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 compared to 
            the verbose chain file format (see below).

    chainFileFormat = 'verbose'

            This is the ASCII (text) file format which is human-readable but does not preserve the 
            full accuracy of the output values. It is also a significantly slower mode of chain file 
            generation, compared to both compact and binary chain file formats (see above and below). 
            If the verbose format is specified, all MCMC states will have equal sample-weights of 1 
            in the output 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 very high-dimensional state space.

    chainFileFormat = 'binary'

            This is the binary file format which is not human-readable, but preserves the exact values 
            in the output MCMC 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 smallest-size 
            output chain file in the shortest time possible.

The default value is chainFileFormat = 'compact' as it provides a reasonable trade-off between speed 
and output file size while generating human-readable chain file contents. Note that the input values 
are case-INsensitive.

restartFileFormat is a string variable that represents the format of the output restart file(s) which 
are used to restart an interrupted ParaDRAM simulation. The string value must be enclosed by either 
single or double quotation marks when provided as input. Two values are possible:

    restartFileFormat = 'binary'

            This is the binary file format which is not human-readable, 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.

    restartFileFormat = 'ASCII'

            This is the ASCII (text) file format which is human-readable 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 is restartFileFormat = 'binary'. Note that the input values are case-INsensitive.

Every progressReportPeriod calls to the objective function, the sampling progress will be reported 
to the log file. Note that progressReportPeriod must be a positive integer. The default value is 1000.

maxNumDomainCheckToWarn is an integer number beyond which the user will be warned about the newly-proposed 
points being excessively proposed outside the domain of the objective function. For every 
maxNumDomainCheckToWarn consecutively-proposed new points that fall outside the domain of the objective 
function, the user will be warned until maxNumDomainCheckToWarn = maxNumDomainCheckToStop, in which 
case the sampler returns a fatal error and the program stops globally. The counter for this warning 
message is reset after a proposal sample from within the domain of the objective function is obtained. 
When out-of-domain sampling happens frequently, it is a strong indication of something fundamentally wrong in the 
simulation. It is, therefore, important to closely inspect and monitor for such frequent out-of-domain samplings. 
This can be done by setting maxNumDomainCheckToWarn to an appropriate value determined by the user. 
The default value is 1000.

maxNumDomainCheckToStop is an integer number beyond which the program will stop globally with a fatal 
error message declaring that the maximum number of proposal-out-of-domain-bounds has reached. The 
counter for this global-stop request is reset after a proposal point is accepted as a sample from 
within the domain of the objective function. 
When out-of-domain sampling happens frequently, it is a strong indication of something fundamentally wrong in the 
simulation. It is, therefore, important to closely inspect and monitor for such frequent out-of-domain samplings. 
This can be done by setting maxNumDomainCheckToStop to an appropriate value determined by the user. 
The default value is 10000.

chainSize determines the number of non-refined, potentially auto-correlated, but unique, samples 
drawn by the MCMC sampler before stopping ParaDRAM. For example, if you specify chainSize = 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 chainSize 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 chainSize is different from and always smaller than the length of the constructed MCMC chain. 
The default value is 100000.

randomStartPointDomainLowerLimitVec represents 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 randomStartPointRequested. This happens only when some or all of the elements of the 
input variable StartPoint are missing. In such cases, every missing value of input StartPoint will 
be set to the center point between randomStartPointDomainLowerLimitVec and RandomStartPointDomainUpperLimit 
in the corresponding dimension. If randomStartPointRequested=TRUE (or True, true, t, all case-INsensitive), 
then the missing elements of StartPoint will be initialized to values drawn randomly from within the 
corresponding ranges specified by the input variable randomStartPointDomainLowerLimitVec. As an input 
variable, randomStartPointDomainLowerLimitVec is an ndim-dimensional vector of 64-bit real numbers, 
where ndim is the number of variables of the objective function. It is also possible to assign only 
select values of randomStartPointDomainLowerLimitVec and leave the rest of the components to be 
assigned the default value. This is POSSIBLE ONLY when randomStartPointDomainLowerLimitVec is defined 
inside the input file to ParaDRAM. For example, having the following inside the input file, 

    randomStartPointDomainLowerLimitVec(3:5) = -100

            will only set the lower limits of the third, fourth, and the fifth dimensions to -100, 
            or,

    randomStartPointDomainLowerLimitVec(1) = -100, randomStartPointDomainLowerLimitVec(2) = -1.e6 

            will set the lower limit on the first dimension to -100, and 1.e6 on the second dimension, 
            or,

    randomStartPointDomainLowerLimitVec = 3*-2.5e100

            will only set the lower limits on the first, second, and the 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 values for all elements of randomStartPointDomainLowerLimitVec are taken from the 
corresponding values in the input variable domainLowerLimitVec.

randomStartPointDomainUpperLimitVec represents 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 randomStartPointRequested. This happens only when some or all of the elements of the 
input variable StartPoint are missing. In such cases, every missing value of input StartPoint will 
be set to the center point between randomStartPointDomainUpperLimitVec and randomStartPointDomainLowerLimitVec 
in the corresponding dimension. If randomStartPointRequested=TRUE (or True, true, t, all case-INsensitive), 
then the missing elements of StartPoint will be initialized to values drawn randomly from within the 
corresponding ranges specified by the input variable randomStartPointDomainUpperLimitVec. As an input 
variable, randomStartPointDomainUpperLimitVec is an ndim-dimensional vector of 64-bit real numbers, 
where ndim is the number of variables of the objective function. It is also possible to assign only 
select values of randomStartPointDomainUpperLimitVec and leave the rest of the components to be 
assigned the default value. This is POSSIBLE ONLY when randomStartPointDomainUpperLimitVec is defined 
inside the input file to ParaDRAM. For example, having the following inside the input file, 

    randomStartPointDomainUpperLimitVec(3:5) = -100

            will only set the upper limits of the third, fourth, and the fifth dimensions to -100, 
            or,

    randomStartPointDomainUpperLimitVec(1) = -100, randomStartPointDomainUpperLimitVec(2) = -1.e6 

            will set the upper limit on the first dimension to -100, and 1.e6 on the second dimension, 
            or,

    randomStartPointDomainUpperLimitVec = 3*-2.5e100

            will only set the upper limits on the first, second, and the 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 randomStartPointDomainUpperLimitVec are taken from the 
corresponding values in the input variable domainUpperLimitVec.

startPointVec is a 64bit real-valued vector of length ndim (the dimension of the domain of the input 
objective function). For every element of startPointVec that is not provided as input, the default 
value will be the center of the domain of startPointVec as specified by domainLowerLimitVec 
and domainUpperLimitVec input variables. If the input variable randomStartPointRequested=TRUE 
(or true or t, all case-INsensitive), then the missing elements of startPointVec will be initialized 
to values drawn randomly from within the corresponding ranges specified by the input variables 
randomStartPointDomainLowerLimitVec and randomStartPointDomainUpperLimitVec.

A logical (boolean) variable. If true (or .true. or TRUE or .t. from within an input file), then the 
variable startPointVec 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 startPointVec, 
given by RandomStartPointDomain variable. Note that the value of startPointVec, if provided, has precedence 
over random initialization. In other words, for every element of startPointVec that is not provided 
as input only that element will initialized randomly if randomStartPointRequested=TRUE. Also, note 
that even if startPointVec is randomly initialized, its random value will be deterministic between 
different independent runs of ParaDRAM if the input variable randomSeed is provided by the user. The 
default value is FALSE.

When sampleSize < 0, the integer variable sampleRefinementCount dictates the maximum number of 
times the MCMC chain will be refined to remove the autocorrelation within the output MCMC sample. 
For example,

    if sampleRefinementCount = 0,

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

    if sampleRefinementCount = 1,

            the refinement of the output MCMC chain will be done only once if needed, and no more, 
            even though there may still exist some residual autocorrelation in the output MCMC sample. 
            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 (IAC) 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 IAC computation will be able to accurately compute the IAC. Consequently, the samples 
            generated based on the computed IAC 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. Very 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 output 
            chain may not contain true i.i.d. samples from the target objective function.

    if sampleRefinementCount > 1,

            the refinement of the output MCMC chain will be done for a maximum sampleRefinementCount 
            number of times, even though there may still exist some residual autocorrelation in the 
            final output MCMC sample.

    if sampleRefinementCount >> 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 has finally been obtained.

Note that to obtain i.i.d. samples from a multidimensional chain, ParaDRAM will, by default, use the 
maximum of Integrated Autocorrelation (IAC) among all dimensions of the chain to refine the chain. Note that 
the value specified for sampleRefinementCount is used only when the variable sampleSize < 0, otherwise, 
it will be ignored. The default value is sampleRefinementCount = 1073741823.

sampleRefinementMethod is a string variable that represents the method of computing the Integrated 
Autocorrelation Time (IAC) to be used in ParaDRAM for refining the final output MCMC chain and sample. 
The string value must be enclosed by either single or double quotation marks when provided as input. 
Options that are currently supported include:

    sampleRefinementMethod = '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 556-568. The batch sizes in the BatchMeans method are chosen to be int(N^(2/3)) 
            where N is the length of the MCMC chain. As long as the batch size is larger than the 
            IAC of the chain and there are significantly more than 10 batches, the BatchMeans method 
            will provide reliable estimates of the IAC. 
            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 IAC of its compact format, 
            where only the 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 IAC of the chain in its verbose (Markov) format. This process 
            is repeated recursively for as long as there is any residual autocorrelation in the refined sample.

    sampleRefinementMethod = 'BatchMeans-compact'

            This is the same as the first case in the above, except that only the first phase of the sample refinement 
            described in the above will be performed, that is, the (verbose) Markov chain is refined only based on the 
            IAC 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. 

    sampleRefinementMethod = 'BatchMeans-verbose'

            This is the same as the first case in the above, except that only the second phase of the sample refinement 
            described in the above will be performed, that is, the (verbose) Markov chain is refined only based on the 
            IAC 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 in the 
            above.

Note that in order to obtain i.i.d. samples from a multidimensional chain, the MCMC sampler will use the average of 
IAC among all dimensions of the chain to refine the chain. If the maximum, minimum, or the median of IACs is preferred 
add '-max' (or '-maximum'), '-min' (or '-minimum'), '-med' (or '-median'), respectively, to the value of 
sampleRefinementMethod. For example, 

    sampleRefinementMethod = 'BatchMeans-max'
or, 

    sampleRefinementMethod = 'BatchMeans-compact-max'

or, 

    sampleRefinementMethod = 'BatchMeans-max-compact'

Also, note that the value specified for sampleRefinementCount is used only when the variable sampleSize < 0, 
otherwise, it will be ignored. The default value is sampleRefinementMethod = 'BatchMeans'. 
Note that the input values are case-INsensitive and white-space characters are ignored.

scaleFactor is a real-valued positive number (which must be given as string), by the square of which 
the covariance matrix of the proposal distribution of MCMC sampler is scaled. In other words, the 
proposal distribution will be scaled in every direction by the value of scaleFactor. It can also be 
given in units of the string keyword 'gelman' (which is case-INsensitive) 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 Metropolis-Hastings Markov Chain Monte Carlo sampling of a target Multivariate Normal 
Distribution of dimension ndim is given by:

    scaleFactor = 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 like the 
following examples:

    scaleFactor = '1'

            multiplies the ndim-dimensional proposal covariance matrix by 1, essentially no change 
            occurs to the covariance matrix.

    scaleFactor = "1"

            same as the previous example. The double-quotation marks act the same way as single-quotation 
            marks.

    scaleFactor = '2.5'

            multiplies the ndim-dimensional proposal covariance matrix by 2.5.

    scaleFactor = '2.5*Gelman'

            multiplies the ndim-dimensional proposal covariance matrix by 2.5 * 2.38/sqrt(ndim).

    scaleFactor = "2.5 * gelman"

            same as the previous example, but with double-quotation marks. space characters are 
            ignored.

    scaleFactor = "2.5 * gelman*gelman*2"

            equivalent to gelmanFactor-squared 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 non-Gaussian proposals and target objective functions. Note that only the product 
symbol (*) can be parsed in the string value of scaleFactor. 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 
the dynamic modification of the initial input value of scaleFactor throughout sampling for 
adaptiveUpdateCount times. The default scaleFactor string-value is 'gelman' (for all proposals), 
which is subsequently converted to 2.38/sqrt(ndim).

proposalModel is a string variable containing the name of the proposal distribution for the MCMC 
sampler. The string value must be enclosed by either single or double quotation marks when provided 
as input. Options that are currently supported include:

    proposalModel = 'normal'

            This is equivalent to the multivariate normal distribution, which is the most widely-used 
            proposal model along with MCMC samplers.

    proposalModel = 'uniform'

            The proposals will be drawn uniformly from within a ndim-dimensional ellipsoid whose 
            covariance matrix and scale are initialized by the user and optionally adaptively updated 
            throughout the simulation.

The default value is 'normal'.

proposalStartCovMat is a real-valued positive-definite matrix of size (ndim,ndim), where ndim is the 
dimension of the sampling space. It serves as the best-guess starting covariance matrix of the proposal 
distribution. To bring the sampling efficiency of ParaDRAM to within the desired requested range, 
the covariance matrix will be adaptively updated throughout the simulation, according to the user's 
requested schedule. If proposalStartCovMat 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 proposalStartCorMat 
and proposalStartStdVec (or via their default values, if not provided). 
The default value of proposalStartCovMat is an ndim-by-ndim Identity matrix.

proposalStartCorMat is a real-valued positive-definite matrix of size (ndim,ndim), where ndim is the 
dimension of the sampling space. It serves as the best-guess starting correlation matrix of the 
proposal distribution used by ParaDRAM. It is used (along with the input vector proposalStartStdVec) 
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 given as input to ParaDRAM, any 
input values for proposalStartCorMat, as well as proposalStartStdVec, will be automatically ignored 
by ParaDRAM. As input to ParaDRAM, the variable proposalStartCorMat along with proposalStartStdVec 
is especially useful in situations where obtaining the best-guess covariance matrix is not trivial. 
The default value of proposalStartCorMat is an ndim-by-ndim Identity matrix.

proposalStartStdVec is a real-valued positive vector of length ndim, where ndim is the dimension of 
the sampling space. It serves as the best-guess starting Standard Deviation of each of the components 
of the proposal distribution. If the initial covariance matrix (proposalStartCovMat) is missing as 
an input variable to ParaDRAM, then proposalStartStdVec (along with the input variable proposalStartCorMat) 
will be used to construct the initial covariance matrix of the proposal distribution of the MCMC 
sampler. However, if proposalStartCovMat is present as an input argument to ParaDRAM, then the input 
proposalStartStdVec along with the input proposalStartCorMat will be completely ignored and the input 
value for proposalStartCovMat will be used to construct the initial covariance matrix of the proposal 
distribution of ParaDRAM. The default value of proposalStartStdVec is a vector of unit values (i.e., 
ones) of length ndim.

Every adaptiveUpdatePeriod calls to the objective function, the parameters of the proposal distribution 
will be updated. The variable adaptiveUpdatePeriod must be a positive non-zero integer. The smaller the 
value of adaptiveUpdatePeriod, the easier it will be for the ParaDRAM 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, 
in particular, for very high dimensional objective functions (ndim >> 1). The larger the value of 
adaptiveUpdatePeriod, the easier it will be for the ParaDRAM 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 adaptiveUpdatePeriod will only delay the adaptation 
of the proposal distribution to the global structure of the objective function that is being sampled. 
If adaptiveUpdatePeriod >= chainSize, then 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.

adaptiveUpdateCount represents 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 sampling 
efficiency of ParaDRAM. Every adaptiveUpdatePeriod 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 adaptiveUpdateCount. This variable must be a non-negative integer. As 
a rule of thumb, it may be appropriate to set the input variable chainSize > 2 * adaptiveUpdatePeriod 
* adaptiveUpdateCount, to ensure ergodicity and stationarity of the MCMC sampler. If adaptiveUpdateCount=0, 
then the proposal distribution parameters will be fixed to the initial input values throughout the 
entire MCMC sampling. The default value is 1073741823.

If greedyAdaptationCount is set to a positive integer then the first greedyAdaptationCount number of 
the adaptive updates of the sampler will be made using only the 'unique' accepted points in the MCMC 
chain. This is useful, for example, when the function to be sampled by ParaDRAM is high dimensional, in 
which case, the adaptive updates to ParaDRAM's sampler distribution will less likely lead to numerical 
instabilities, for example, a singular covariance matrix for the multivariate proposal sampler. The 
variable greedyAdaptationCount must be a non-negative integer, and not larger than the value of 
adaptiveUpdateCount. If it is larger, it will be automatically set to adaptiveUpdateCount for the 
simulation. The default value is 0.

burninAdaptationMeasure is a 64-bit real number between 0 and 1, representing the adaptation measure 
threshold below which the simulated Markov chain will be used to generate the output ParaDRAM sample. 
In other words, any point in the output Markov Chain that has been sampled during significant adaptation 
of the proposal distribution (as determined by burninAdaptationMeasure) will not be included in the 
construction of the final ParaDRAM output sample. This is to ensure that the generation of the output 
sample will be based 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 non-adaptive or minimally-adaptive part of 
the chain may not even exist if the total adaptation period of the simulation (as determined by 
adaptiveUpdateCount and adaptiveUpdatePeriod input variables) is longer than the total length of the 
output MCMC chain. In such cases, the resulting output sample may have a zero size. In general, when 
good mixing occurs (e.g., when the input variable chainSize is very large) any specific value of 
burninAdaptationMeasure becomes practically irrelevant. The default value for burninAdaptationMeasure 
is 1.00000000000000, implying that the entire chain (with the exclusion of an initial automatically-determined 
burnin period) will be used to generate the final output sample.

0 <= delayedRejectionCount <= 1000 is an integer that represents the total number of stages for which 
rejections of new proposals will be tolerated by ParaDRAM before going back to the previously accepted 
point (state). Possible values are:

    delayedRejectionCount = 0

            indicating no deployment of the delayed rejection algorithm.

    delayedRejectionCount > 0

            which implies a maximum delayedRejectionCount number of rejections will be tolerated.

For example, delayedRejectionCount = 1, means that at any point during the sampling, if a proposal 
is rejected, ParaDRAM will not go back 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 
ParaDRAM, 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 delayedRejectionCount = 1. The algorithm 
then goes back to the original last-accepted state and will begin proposing new states from that 
location. The default value is delayedRejectionCount = 0.

delayedRejectionScaleFactorVec is a real-valued positive vector of length (1:delayedRejectionCount) 
by which the covariance matrix of the proposal distribution of ParaDRAM sampler is scaled when the 
Delayed Rejection (DR) scheme is activated (by setting delayedRejectionCount>0). At each ith stage 
of the DR process, the proposal distribution from the last stage is scaled by the factor 
delayedRejectionScaleFactorVec(i). Missing elements of the delayedRejectionScaleFactorVec in the 
input to ParaDRAM 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.