ParaDRAM: An 'R6' 'ParaDRAM' class for paramonte package usage

In ShashankKumbhare/paramonteR: Plain Powerful Parallel Monte Carlo Library

An R6 ParaDRAM class for paramonte package usage

Description

This is the ParaDRAM class to generate instances of serial and parallel Delayed-Rejection Adaptive Metropolis-Hastings Markov Chain Monte Carlo sampler class of the paramonte library.

The ParaDRAM class is a child of the ParaMonteSampler class.

All ParaDRAM class attributes are optional and all attributes can be set after a ParaDRAM instance is returned by the class constructor.

Once you set the optional attributes to your desired values, call the ParaDRAM sampler via the object's method runSampler().

---

Example serial usage

Copy and paste the following code in your R session:

getLogFunc = function(point) {
    # return the log of a multivariate Normal
    # density function with ndim dimensions
    return( -0.5 * np.dot(point, point) )
}
pmpd = ParaDRAM$new()
pmpd$runSampler ( ndim = 4, # assume 4-dimensional objective function
                  getLogFunc = getLogFunc    # the objective function
)

where,

• ndim

  represents the number of dimensions of the domain of the user’s objective function getLogFunc(point) and,

• getLogFunc(point)

  represents the user’s objective function to be sampled, which must take a single input argument point of type vector of length ndim and must return the natural logarithm of the objective function.

testing nested indenting

Example serial usage

this should be under 2nd indentation

---

Example parallel usage

TO_DO_LATER entire section

Copy and paste the following code in your R session:

TO_DO_LATER
TO_DO_LATER
TO_DO_LATER
TO_DO_LATER

where,

• ndim

  represents the number of dimensions of the domain of the user’s objective function getLogFunc(point) and,

• getLogFunc(point)

  represents the user’s objective function to be sampled, which must take a single input argument point of type vector of length ndim and must return the natural logarithm of the objective function.

• mpiEnabled

  is a logical (boolean) indicator that, if TRUE, will cause the ParaDRAM simulation to run in parallel on the requested number of processors. The default value is FALSE.

---

Note

TO_DO_LATER entire section

---

Tips on parallel usage

TO_DO_LATER entire section

---

ParaDRAM Class Attributes

See also:

• https://www.cdslab.org/paramonte/notes/usage/paradram/specifications/

All input specifications (attributes) of a ParaDRAM simulation are optional. However, it is recommended that you provide as much information as possible about the specific ParaDRAM simulation and the objective function to be sampled via ParaDRAM simulation specifications.

The ParaDRAM simulation specifications have lengthy comprehensive descriptions that appear in full in the output report file of every ParaDRAM simulation.

The best way to learn about individual ParaDRAM simulation attributes is to a run a minimal serial simulation with the following R script,

pmpd = ParaDRAM()
pmpd$spec$outputFileName = "./test"
getLogFunc = function(point){
    return( -sum(point**2) )
}
pmpd$runSampler( ndim = 1, getLogFunc = getLogFunc )

Running this code will generate a set of simulation output files (in the current working directory of R) that begin with the prefix test_process_1. Among these, the file test_process_1_report.txt contains the full description of all input specifications of the ParaDRAM simulation as well as other information about the simulation results and statistics.

---

Parameters

None. The simulation specifications can be set once an object is instantiated. All simulation specification descriptions are collectively available at:

• https://www.cdslab.org/paramonte/notes/usage/paradram/specifications/

Note that this is the new interface. The previous ParaDRAM class interface used to optionally take all simulation specifications as input. However, overtime, this approach has become more of liability than any potential benefit. All simulation specifications have to be now to be set solely after a ParaDRAM object is instantiated, instead of setting the specifications via the ParaDRAM class constructor.

.

.

---

Super class

• paramonte::ParaMonteSampler -> ParaDRAM

• ParaMonteSampler has no super class.

..

..

---

Public fields

ParaDRAM fields

– none –

ParaMonteSampler fields

buildMode

optional string argument with the default value “release”. possible choices are:

• “debug”

  to be used for identifying sources of bug and causes of code crash.

• “release”

  to be used in all other normal scenarios for maximum runtime efficiency.

mpiEnabled

Optional logical (boolean) indicator which is FALSE by default.

If it is set to TRUE, it will cause the ParaMonte simulation to run in parallel on the requested number of processors.

See the class documentation guidelines in the above for information on how to run a simulation in parallel.

inputFile

Optional string input representing the path to an external input namelist of simulation specifications.

USE THIS OPTIONAL ARGUMENT WITH CAUTION AND ONLY IF YOU KNOW WHAT YOU ARE DOING.

WARNING

Specifying an input file will cause the sampler to ignore all other simulation specifications set by the user via sampler instance's spec-component attributes.

spec

An R list containing all simulation specifications.

All simulation attributes are by default set to appropriate values at runtime. To override the default simulation specifications, set the spec attributes to some desired values of your choice.

If you need help on any of the simulation specifications, try the supplied helpme() function in this component.

If you wish to reset some specifications to the default values, simply set them to NULL.

reportEnabled

optional logical (boolean) indicator which is TRUE by default.

If it is set to TRUE, it will cause extensive guidelines to be printed on the standard output as the simulation or post-processing continues with hints on the next possible steps that could be taken in the process. If you do not need such help and information set this variable to FALSE to silence all output messages.

...

...

---

Class constructor

Method new()

Description

Instantiates a ParaDRAM class object.

Usage

ParaDRAM$new()

Arguments

– none –'

Returns

Returns a new ParaDRAM class object.

....

....

---

Methods

ParaDRAM methods

• – none –

ParaMonteSampler methods

• ParaMonteSampler$readChain()

• ParaMonteSampler$readSample()

• ParaMonteSampler$readReport()

• ParaMonteSampler$readRestart()

• ParaMonteSampler$readProgress()

• ParaMonteSampler$readMarkovChain()

.....

.....

---

Methods description

Method readChain()

Description

Return a list of the contents of a set of ParaDRAM output chain files whose names begin the user-provided input file prefix, or as specified by the input simulation specification SAMPLER$spec$outputFileName, where SAMPLER can be an instance of any one of the ParaMonte's sampler classes, such as ParaDRAM.

Note

• This method is to be only used for postprocessing of the output chain file(s) of an already finished ParaDRAM simulation.

• It is not meant to be called by all processes in parallel mode, although it is possible.

Usage

ParaMonteSampler$readChain(file, delimiter, parseContents, renabled)

Arguments

file

(optional)

A string representing the path to the chain file with the default value of ''. The path only needs to uniquely identify the name of the simulation to which the chain file belongs.

For example, specifying './mydir/mysim' as input will lead to a search for a file that begins with 'mysim' and ends with '_chain.txt' inside the directory './mydir/'.

If there are multiple files with such name, then all of them will be read and returned as a list.

If this input argument is not provided by the user, the value of the object's spec attribute outputFileName will be used instead.

If the specified path is a URL, the file will be downloaded as a temporary file to the local system and its contents will be parsed and the file will be subsequently removed.

If no input is specified via any of the possible routes, the method will search for any possible candidate file with the appropriate suffix in the current working directory.

delimiter

(optional)

Optional input string representing the delimiter used in the output chain file. If it is not provided as input argument, the value of the corresponding object's spec attribute outputDelimiter will be used instead. If none of the two are available, the default comma delimiter ',' will be assumed and used.

parseContents

(optional)

If set to TRUE, the contents of the chain file will be parsed and stored in a component of the object named contents.

The default value is TRUE.

renabled

(optional)

If set to FALSE, the contents of the file(s) will be stored as a list in a (new) component of the ParaDRAM object named chainList and NULL will be the return value of the method. If set to TRUE, the reverse will done.

The default value is FALSE.

Returns

chainList (optional)

An R list of TabularFileContents objects, each of which corresponds to the contents of a unique restart file. Each object has the following components:

• file

  The full absolute path to the output chain file.

• delimiter

  The delimiter used in the output chain file.

• ndim

  The number of dimensions of the domain of the objective function from which the output has been drawn.

• count

  The number of sampled points in the output chain file.

• plot

  An R list containing the graphics tools for the visualization of the contents of the output chain file.

• df

  The contents of the output chain file in the form of a DataFrame (hence called df).

• contents

  Corresponding to each column in the chain file, a property with the same name as the column header is also created for the object which contains the data stored in that column of the chain file. These properties are all stored in the attribute contents.

If renabled = TRUE, the list of objects will be returned as the return value of the method. Otherwise, the list will be stored in a component of the ParaDRAM object named chainList.

---

Method readSample()

Description

Return a list of the contents of a set of ParaDRAM output sample files whose names begin the user-provided input file prefix, or as specified by the input simulation specification SAMPLER$spec$outputFileName, where SAMPLER can be an instance of any one of the ParaMonte's sampler classes, such as ParaDRAM.

Note

• This method is to be only used for postprocessing of the output sample file(s) of an already finished ParaDRAM simulation.

• It is not meant to be called by all processes in parallel mode, although it is possible.

Usage

ParaMonteSampler$readSample(file, delimiter, parseContents, renabled)

Arguments

file

(optional)

A string representing the path to the sample file with the default value of ''. The path only needs to uniquely identify the name of the simulation to which the sample file belongs.

For example, specifying './mydir/mysim' as input will lead to a search for a file that begins with 'mysim' and ends with '_sample.txt' inside the directory './mydir/'.

If there are multiple files with such name, then all of them will be read and returned as a list.

If this input argument is not provided by the user, the value of the object's spec attribute outputFileName will be used instead.

If the specified path is a URL, the file will be downloaded as a temporary file to the local system and its contents will be parsed and the file will be subsequently removed.

If no input is specified via any of the possible routes, the method will search for any possible candidate file with the appropriate suffix in the current working directory.

delimiter

(optional)

Optional input string representing the delimiter used in the output sample file. If it is not provided as input argument, the value of the corresponding object's spec attribute outputDelimiter will be used instead. If none of the two are available, the default comma delimiter ',' will be assumed and used.

parseContents

(optional)

If set to TRUE, the contents of the sample file will be parsed and stored in a component of the object named contents.

The default value is TRUE.

renabled

(optional)

If set to FALSE, the contents of the file(s) will be stored as a list in a (new) component of the ParaDRAM object named sampleList and NULL will be the return value of the method. If set to TRUE, the reverse will done.

The default value is FALSE.

Returns

sampleList (optional)

An R list of TabularFileContents objects, each of which corresponds to the contents of a unique restart file. Each object has the following components:

• file

  The full absolute path to the output sample file.

• delimiter

  The delimiter used in the output sample file.

• ndim

  The number of dimensions of the domain of the objective function from which the output has been drawn.

• count

  The number of sampled points in the output sample file.

• plot

  An R list containing the graphics tools for the visualization of the contents of the output sample file.

• df

  The contents of the output sample file in the form of a DataFrame (hence called df).

• contents

  Corresponding to each column in the sample file, a property with the same name as the column header is also created for the object which contains the data stored in that column of the sample file. These properties are all stored in the attribute contents.

If renabled = TRUE, the list of objects will be returned as the return value of the method. Otherwise, the list will be stored in a component of the ParaDRAM object named sampleList.

---

Method readReport()

Description

Return a list of the contents of a set of ParaDRAM output report files whose names begin the user-provided input file prefix, or as specified by the input simulation specification SAMPLER$spec$outputFileName, where SAMPLER can be an instance of any one of the ParaMonte's sampler classes, such as ParaDRAM.

Note

• This method is to be only used for postprocessing of the output report file(s) of an already finished ParaDRAM simulation.

• It is not meant to be called by all processes in parallel mode, although it is possible.

Usage

ParaMonteSampler$readSample(file, renabled)

Arguments

file

(optional)

A string representing the path to the report file with the default value of ''. The path only needs to uniquely identify the name of the simulation to which the report file belongs.

For example, specifying './mydir/mysim' as input will lead to a search for a file that begins with 'mysim' and ends with '_report.txt' inside the directory './mydir/'.

If there are multiple files with such name, then all of them will be read and returned as a list.

If this input argument is not provided by the user, the value of the object's spec attribute outputFileName will be used instead.

If the specified path is a URL, the file will be downloaded as a temporary file to the local system and its contents will be parsed and the file will be subsequently removed.

If no input is specified via any of the possible routes, the method will search for any possible candidate file with the appropriate suffix in the current working directory.

renabled

(optional)

If set to FALSE, the contents of the file(s) will be stored as a list in a (new) component of the ParaDRAM object named reportList and NULL will be the return value of the method. If set to TRUE, the reverse will done.

The default value is FALSE.

Returns

reportList (optional)

An R list of ReportFileContents objects, each of which corresponds to the contents of a unique restart file. Each object has the following components:

• file

  The full absolute path to the output report file.

• contents

  Corresponding to each column in the report file, a property with the same name as the column header is also created for the object which contains the data stored in that column of the report file. These properties are all stored in the attribute contents.

If renabled = TRUE, the list of objects will be returned as the return value of the method. Otherwise, the list will be stored in a component of the ParaDRAM object named reportList.

---

Method readRestart()

Description

Return a list of the contents of a set of ParaDRAM output restart files whose names begin the user-provided input file prefix, or as specified by the input simulation specification SAMPLER$spec$outputFileName, where SAMPLER can be an instance of any one of the ParaMonte's sampler classes, such as ParaDRAM.

Note

• This method is to be only used for postprocessing of the output restart file(s) of an already finished ParaDRAM simulation.

• It is not meant to be called by all processes in parallel mode, although it is possible.

Usage

ParaMonteSampler$readRestart(file, renabled)

Arguments

file

(optional)

A string representing the path to the restart file with the default value of ''. The path only needs to uniquely identify the name of the simulation to which the restart file belongs.

For example, specifying './mydir/mysim' as input will lead to a search for a file that begins with 'mysim' and ends with '_restart.txt' inside the directory './mydir/'.

If there are multiple files with such name, then all of them will be read and returned as a list.

If this input argument is not provided by the user, the value of the object's spec attribute outputFileName will be used instead.

If the specified path is a URL, the file will be downloaded as a temporary file to the local system and its contents will be parsed and the file will be subsequently removed.

If no input is specified via any of the possible routes, the method will search for any possible candidate file with the appropriate suffix in the current working directory.

renabled

(optional)

If set to FALSE, the contents of the file(s) will be stored as a list in a (new) component of the ParaDRAM object named restartList and NULL will be the return value of the method. If set to TRUE, the reverse will done.

The default value is FALSE.

Returns

restartList (optional)

An R list of RestartFileContents objects, each of which corresponds to the contents of a unique restart file. Each object has the following components:

• file

  The full absolute path to the output restart file.

• ndim

  The number of dimensions of the domain of the objective function from which the output has been drawn.

• count

  The number of sampled points in the output restart file.

• plot

  An R list containing the graphics tools for the visualization of the contents of the output restart file.

• df

  The contents of the output restart file in the form of a DataFrame (hence called df).

• contents

  Corresponding to each column in the restart file, a property with the same name as the column header is also created for the object which contains the data stored in that column of the restart file. These properties are all stored in the attribute contents.

• propNameList

  A list of entities names parsed from the , restart file.

If renabled = TRUE, the list of objects will be returned as the return value of the method. Otherwise, the list will be stored in a component of the ParaDRAM object named restartList.

---

Method readProgress()

Description

Return a list of the contents of a set of ParaDRAM output progress files whose names begin the user-provided input file prefix, or as specified by the input simulation specification SAMPLER$spec$outputFileName, where SAMPLER can be an instance of any one of the ParaMonte's sampler classes, such as ParaDRAM.

Note

• This method is to be only used for postprocessing of the output progress file(s) of an already finished ParaDRAM simulation.

• It is not meant to be called by all processes in parallel mode, although it is possible.

Usage

ParaMonteSampler$readChain(file, delimiter, parseContents, renabled)

Arguments

file

(optional)

A string representing the path to the progress file with the default value of ''. The path only needs to uniquely identify the name of the simulation to which the progress file belongs.

For example, specifying './mydir/mysim' as input will lead to a search for a file that begins with 'mysim' and ends with '_progress.txt' inside the directory './mydir/'.

If there are multiple files with such name, then all of them will be read and returned as a list.

If this input argument is not provided by the user, the value of the object's spec attribute outputFileName will be used instead.

If the specified path is a URL, the file will be downloaded as a temporary file to the local system and its contents will be parsed and the file will be subsequently removed.

If no input is specified via any of the possible routes, the method will search for any possible candidate file with the appropriate suffix in the current working directory.

delimiter

(optional)

Optional input string representing the delimiter used in the output progress file. If it is not provided as input argument, the value of the corresponding object's spec attribute outputDelimiter will be used instead. If none of the two are available, the default comma delimiter ',' will be assumed and used.

parseContents

(optional)

If set to TRUE, the contents of the progress file will be parsed and stored in a component of the object named contents.

The default value is TRUE.

renabled

(optional)

If set to FALSE, the contents of the file(s) will be stored as a list in a (new) component of the ParaDRAM object named progressList and NULL will be the return value of the method. If set to TRUE, the reverse will done.

The default value is FALSE.

Returns

progressList (optional)

An R list of TabularFileContents objects, each of which corresponds to the contents of a unique restart file. Each object has the following components:

• file

  The full absolute path to the output progress file.

• delimiter

  The delimiter used in the output progress file.

• ncol

  The number of columns of the progress file.

• plot

  An R list containing the graphics tools for the visualization of the contents of the output progress file.

• df

  The contents of the output progress file in the form of a DataFrame (hence called df).

• contents

  Corresponding to each column in the progress file, a property with the same name as the column header is also created for the object which contains the data stored in that column of the progress file. These properties are all stored in the attribute contents.

If renabled = TRUE, the list of objects will be returned as the return value of the method. Otherwise, the list will be stored in a component of the ParaDRAM object named progressList.

---

Method readMarkovChain()

Description

Return a list of the unweighted verbose (Markov-chain) contents of a set of ParaDRAM output markovChain files whose names begin the user-provided input file prefix, or as specified by the input simulation specification SAMPLER$spec$outputFileName, where SAMPLER can be an instance of any one of the ParaMonte's sampler classes, such as ParaDRAM.

Note

• This method is to be only used for postprocessing of the output markovChain file(s) of an already finished ParaDRAM simulation.

• It is not meant to be called by all processes in parallel mode, although it is possible.

Usage

ParaMonteSampler$readMarkovChain(file, delimiter, parseContents, renabled)

Arguments

file

(optional)

A string representing the path to the markovChain file with the default value of ''. The path only needs to uniquely identify the name of the simulation to which the markovChain file belongs.

For example, specifying './mydir/mysim' as input will lead to a search for a file that begins with 'mysim' and ends with '_markovChain.txt' inside the directory './mydir/'.

If there are multiple files with such name, then all of them will be read and returned as a list.

If this input argument is not provided by the user, the value of the object's spec attribute outputFileName will be used instead.

If the specified path is a URL, the file will be downloaded as a temporary file to the local system and its contents will be parsed and the file will be subsequently removed.

If no input is specified via any of the possible routes, the method will search for any possible candidate file with the appropriate suffix in the current working directory.

delimiter

(optional)

Optional input string representing the delimiter used in the output markovChain file. If it is not provided as input argument, the value of the corresponding object's spec attribute outputDelimiter will be used instead. If none of the two are available, the default comma delimiter ',' will be assumed and used.

parseContents

(optional)

If set to TRUE, the contents of the markovChain file will be parsed and stored in a component of the object named contents.

The default value is TRUE.

renabled

(optional)

If set to FALSE, the contents of the file(s) will be stored as a list in a (new) component of the ParaDRAM object named markovChainList and NULL will be the return value of the method. If set to TRUE, the reverse will done.

The default value is FALSE.

Returns

markovChainList (optional)

An R list of TabularFileContents objects, each of which corresponds to the contents of a unique restart file. Each object has the following components:

• file

  The full absolute path to the output markovChain file.

• delimiter

  The delimiter used in the output markovChain file.

• ndim

  The number of dimensions of the domain of the objective function from which the output has been drawn.

• count

  The number of sampled points in the output markovChain file.

• plot

  An R list containing the graphics tools for the visualization of the contents of the output markovChain file.

• df

  The contents of the output markovChain file in the form of a DataFrame (hence called df).

• contents

  Corresponding to each column in the markovChain file, a property with the same name as the column header is also created for the object which contains the data stored in that column of the markovChain file. These properties are all stored in the attribute contents.

If renabled = TRUE, the list of objects will be returned as the return value of the method. Otherwise, the list will be stored in a component of the ParaDRAM object named markovChainList.

---

ShashankKumbhare/paramonteR documentation built on April 25, 2022, 12:08 a.m.