This is the base class for the ParaMonte sampler routines. More...

Inheritance diagram for Sampler:

Collaboration diagram for Sampler:

Public Member Functions
function	Sampler (in method)
	Return a scalar object of class [pm.sampling.Sampler``. More...

function	finalize (in self)
	Finalize the ParaMonte MATLAB sampler simulation run and return nothing. More...

function	findfile (in self, in ftype, in pattern)
	Return a vector of MATLAB strings containing the fully-resolved paths matching the input `pattern`. More...

function	getppm (in self)
	Generate and return the relevant Post-Processing Message (ppm) for the current ParaMonte sampler to be displayed on the MATLAB command line after the sampling is complete. More...

function	readChain (in self, in pattern, in sep, in varargin)
	Return a list of objects of superclass pm.sampling.FileContentsChain containing the content(s) of the ParaMonte simulation output chain file(s) whose path(s) match the specified input `pattern` or the simulation specification `sampler.spec.outputFileName`. More...

function	readProgress (in self, in pattern, in sep)
	Return a list of objects of class pm.sampling.FileContentsProgress containing the content(s) of the ParaMonte simulation output progress file(s) whose path(s) match the specified input `pattern` or the simulation specification `sampler.spec.outputFileName`. More...

function	readReport (in self, in pattern)
	Return a list of objects of class pm.sampling.FileContentsReport containing the content(s) of the ParaMonte simulation output report file(s) whose path(s) match the specified input `pattern` or the simulation specification `sampler.spec.outputFileName`. More...

function	readRestart (in self, in pattern)
	Return a list of objects of class pm.sampling.FileContentsRestart containing the content(s) of the ParaMonte simulation output restart file(s) whose path(s) match the specified input `pattern` or the simulation specification `sampler.spec.outputFileName`. More...

function	readSample (in self, in pattern, in sep)
	Return a list of objects of superclass pm.sampling.FileContentsSample containing the content(s) of the ParaMonte simulation output sample file(s) whose path(s) match the specified input `pattern` or the simulation specification `sampler.spec.outputFileName`. More...

function	run (in self, in getLogFunc, in ndim)
	Perform the basic runtime checks for the sampler and return nothing. More...

function	getLogFuncWrapped (in state)

function	getLogFuncConcurrent (in state)

Data Fields
Property	input

Property	checked

Property	mpiname

Property	silent

Property	spec

Property	mexname

Property	libtype

Property	partype

Property	memtype

Property	bldtype

Property	clstype

Property	name

Property	weblinks

Property	matpath

Property	method

Property	ndim

Property	nml

Property	libspec

Detailed Description

This is the base class for the ParaMonte sampler routines.

Note: See below for information on the attributes (properties).; See below for information on the methods.; Given the basic primitive nature of this class, it does not have a custom constructor.
Users should always use the subclasses of this base class.

Final Remarks ⛓

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright: Computational Data Science Lab

Author:: Joshua Alexander Osborne, May 21 2024, 12:43 AM, University of Texas at Arlington
Fatemeh Bagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.
Amir Shahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin

Definition at line 20 of file Sampler.m.

Constructor & Destructor Documentation

◆ Sampler()

function Sampler::Sampler ( in method )

Return a scalar object of class [pm.sampling.Sampler``.

This is the constructor of the class pm.sampling.Sampler.
This class is not meant to be accessed by the end users.
It merely serves as the blueprint for the subclasses of pm.sampling.Sampler accessible to the end users.

Parameters

[in] method : The input scalar MATLAB string containing the name of the target ParaMonte sampler.

Returns: self : The output scalar object of class pm.sampling.Sampler.

Possible calling interfaces ⛓

: sampler = pm.sampling.Sampler();

sampler = pm.sampling.Sampler([]);

sampler = pm.sampling.Sampler(method);

Sampler::method
Property method
Definition: Sampler.m:241

Final Remarks ⛓

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright: Computational Data Science Lab

Author:: Joshua Alexander Osborne, May 21 2024, 12:52 AM, University of Texas at Arlington
Fatemeh Bagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.
Amir Shahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin

Member Function Documentation

◆ finalize()

function Sampler::finalize ( in self )

Finalize the ParaMonte MATLAB sampler simulation run and return nothing.

This is a private and Hidden dynamic method of the class pm.sampling.Sampler.

Parameters

[in] self : The input parent object of class pm.sampling.Sampler which is implicitly passed to this dynamic method (not by the user).

Final Remarks ⛓

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright: Computational Data Science Lab

Author:: Joshua Alexander Osborne, May 21 2024, 12:10 AM, University of Texas at Arlington
Amir Shahmoradi, September 1, 2012, 12:00 AM, National Institute for Fusion Studies, The University of Texas at Austin%>

◆ findfile()

function Sampler::findfile	(	in	self,
		in	ftype,
		in	pattern
	)

Return a vector of MATLAB strings containing the fully-resolved paths matching the input pattern.

This is a Hidden method of the class pm.sampling.Sampler.

Parameters

[in]	self	: The input parent object of class pm.sampling.Sampler which is implicitly passed to this dynamic method (not by the user).
[in]	ftype	: The input scalar MATLAB string containing the sampler file type, which can be one of the following: `"chain"` `"sample"` `"report"` `"restart"` `"progress"`
[in]	pattern	: The input scalar MATLAB string containing either: a pattern to search for paths on the current system. Wildcards may be used for basenames and for the directory parts. If pattern contains directory parts, then these will be included in the output `fileList`. Following wildcards can be used within the specified `pattern`: `` : match zero or more characters. a full weblink to download and save locally on the system temporary folder. (optional*, default = `pwd()`)

Returns: fileList : The output vector of MATLAB strings containing the fully-resolved paths matching the input pattern.

Possible calling interfaces ⛓

: sampler = pm.sampling.Sampler();

fileList = sampler.findfile(ftype)

fileList = sampler.findfile(ftype, [], [])

fileList = sampler.findfile(ftype, [], silent)

fileList = sampler.findfile(ftype, pattern, [])

fileList = sampler.findfile(ftype, pattern, silent)

Sampler::silent
Property silent
Definition: Sampler.m:119

Final Remarks ⛓

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright: Computational Data Science Lab

Author:: Joshua Alexander Osborne, May 21 2024, 12:14 AM, University of Texas at Arlington
Fatemeh Bagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.
Amir Shahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin

◆ getLogFuncConcurrent()

function Sampler::getLogFuncConcurrent ( in state )

◆ getLogFuncWrapped()

function Sampler::getLogFuncWrapped ( in state )

◆ getppm()

function Sampler::getppm ( in self )

Generate and return the relevant Post-Processing Message (ppm) for the current ParaMonte sampler to be displayed on the MATLAB command line after the sampling is complete.

This is a private dynamic method of the pm.sampling.Paradram sampler class.
This method is not meant to be used or accessed by the end users.

Parameters

[in] self : The input parent object of class pm.sampling.Sampler which is implicitly passed to this dynamic method (not by the user).

Note: This is an internal method of the class pm.sampling.Sampler.

Final Remarks ⛓

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright: Computational Data Science Lab

Author:: Amir Shahmoradi, September 1, 2012, 12:00 AM, National Institute for Fusion Studies, The University of Texas at Austin%>

◆ readChain()

function Sampler::readChain	(	in	self,
		in	pattern,
		in	sep,
		in	varargin
	)

Return a list of objects of superclass pm.sampling.FileContentsChain containing the content(s) of the ParaMonte simulation output chain file(s) whose path(s) match the specified input pattern or the simulation specification sampler.spec.outputFileName.

Warning: This method is to be only used for post-processing of the output chain file(s) of an already finished simulation.
Although possible, this method is NOT meant to be called by all processes in MPI-parallel simulations.

Parameters

[in]	self	: The input parent object of superclass pm.sampling.Sampler which is implicitly passed to this dynamic method (not by the user).
[in]	pattern	: The input scalar MATLAB string containing the pattern matching the desired chain file(s) whose contents is to be read. The specified `pattern` only needs to partially 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 file(s) beginning with "mysim" and ending with `"_chain.txt"` inside the directory `"./mydir/"`. If there are multiple files matching in the input `pattern`, then all such files will be read and returned as elements of a list. If the specified pattern is a valid existing URL, the file will be downloaded as a temporary file to the local system, its contents shall be parsed and the file will be subsequently removed. If the input `pattern` is empty, then the method will search for any possible candidate files with the appropriate suffix in the current working directory. (optional, default = `sampler.spec.outputFileName` or `"./"`)
[in]	sep	: The input MATLAB string containing the field separator used in the file(s). (optional, default = `sampler.spec.outputSeparator` or automatically inferred.)
[in]	varargin	: Any set of arguments that must be directly passed to the relevant file contents parser class. (optional. default is empty, corresponding to no extra input arguments.)

Returns: chainList : The output MATLAB cell array of objects of superclass pm.sampling.FileContentsChain, each of which corresponds to the contents of a unique chain file.

Possible calling interfaces ⛓

: sampler = pm.sampling.Sampler();

chainList = sampler.readChain();

chainList = sampler.readChain([]);

chainList = sampler.readChain([], []);

chainList = sampler.readChain(pattern);

chainList = sampler.readChain([], sep);

chainList = sampler.readChain(pattern, sep, varargin);

Note: See the documentation of the subclasses of pm.sampling.Sampler (e.g., pm.sampling.Paradram) for example usage in action.

Example usage ⛓

: sampler.readChain("./out/test_run_");

sampler.spec.outputFileName = "./out/test_run_";

sampler.readChain();

sampler.readChain("./out/test_run_", ",");

sampler.spec.outputSeparator = ",";

sampler.readChain("./out/test_run_");

sampler.spec.outputFileName = "./out/test_run_";

sampler.spec.outputSeparator = ",";

sampler.readChain();

Final Remarks ⛓

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright: Computational Data Science Lab

Author:: Joshua Alexander Osborne, May 21 2024, 12:18 AM, University of Texas at Arlington
Fatemeh Bagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.
Amir Shahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin

◆ readProgress()

function Sampler::readProgress	(	in	self,
		in	pattern,
		in	sep
	)

Return a list of objects of class pm.sampling.FileContentsProgress containing the content(s) of the ParaMonte simulation output progress file(s) whose path(s) match the specified input pattern or the simulation specification sampler.spec.outputFileName.

Warning: This method is to be only used for post-processing of the output progress file(s) of an already finished simulation. Although possible, this method is NOT meant to be called by all processes in MPI-parallel simulations.

Parameters

[in]	self	: The input parent object of class pm.sampling.Sampler which is implicitly passed to this dynamic method (not by the user).
[in]	pattern	: The input scalar MATLAB string containing the pattern matching the desired progress file(s) whose contents is to be read. The specified `pattern` only needs to partially 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 file(s) beginning with "mysim" and ending with `"_progress.txt"` inside the directory `"./mydir/"`. If there are multiple files matching in the input `pattern`, then all such files will be read and returned as elements of a list. If the specified pattern is a valid existing URL, the file will be downloaded as a temporary file to the local system, its contents shall be parsed and the file will be subsequently removed. If the input `pattern` is empty, then the method will search for any possible candidate files with the appropriate suffix in the current working directory. (optional, default = `sampler.spec.outputFileName` or `"./"`)
[in]	sep	: The input MATLAB string containing the field separator used in the file(s). (optional, default = `sampler.spec.outputSeparator` or automatically inferred.)

Returns: progressList : The output MATLAB cell array of objects of class pm.sampling.FileContentsProgress, each of which corresponds to the contents of a unique progress file.

Possible calling interfaces ⛓

: sampler = pm.sampling.Sampler();

progressList = sampler.readProgress();

progressList = sampler.readProgress([]);

progressList = sampler.readProgress([], []);

progressList = sampler.readProgress(pattern);

progressList = sampler.readProgress([], sep);

progressList = sampler.readProgress(pattern, sep);

Note: See the documentation of the subclasses of pm.sampling.Sampler (e.g., pm.sampling.Paradram) for example usage in action.

Example usage ⛓

: sampler.readProgress("./out/test_run_");

sampler.spec.outputFileName = "./out/test_run_";

sampler.readProgress();

sampler.readProgress("./out/test_run_", ",");

sampler.spec.outputSeparator = ",";

sampler.readProgress("./out/test_run_");

sampler.spec.outputFileName = "./out/test_run_";

sampler.spec.outputSeparator = ",";

sampler.readProgress();

Final Remarks ⛓

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright: Computational Data Science Lab

Author:: Joshua Alexander Osborne, May 21 2024, 12:25 AM, University of Texas at Arlington
Fatemeh Bagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.
Amir Shahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin

◆ readReport()

function Sampler::readReport	(	in	self,
		in	pattern
	)

Return a list of objects of class pm.sampling.FileContentsReport containing the content(s) of the ParaMonte simulation output report file(s) whose path(s) match the specified input pattern or the simulation specification sampler.spec.outputFileName.

Warning: This method is to be only used for post-processing of the output report file(s) of an already finished simulation. Although possible, this method is NOT meant to be called by all processes in MPI-parallel simulations.

Parameters

[in]	self	: The input parent object of class pm.sampling.Sampler which is implicitly passed to this dynamic method (not by the user).
[in]	pattern	: The input scalar MATLAB string containing the pattern matching the desired report file(s) whose contents is to be read. The specified `pattern` only needs to partially 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 file(s) beginning with "mysim" and ending with `"_report.txt"` inside the directory `"./mydir/"`. If there are multiple files matching in the input `pattern`, then all such files will be read and returned as elements of a list. If the specified pattern is a valid existing URL, the file will be downloaded as a temporary file to the local system, its contents shall be parsed and the file will be subsequently removed. If the input `pattern` is empty, then the method will search for any possible candidate files with the appropriate suffix in the current working directory. (optional, default = `sampler.spec.outputFileName` or `"./"`)

Returns: reportList : The output MATLAB cell array of objects of class pm.sampling.FileContentsReport, each of which corresponds to the contents of a unique report file.

Possible calling interfaces ⛓

: sampler = pm.sampling.Sampler();

reportList = sampler.readReport();

reportList = sampler.readReport([]);

reportList = sampler.readReport(pattern);

Note: See the documentation of the subclasses of pm.sampling.Sampler (e.g., pm.sampling.Paradram) for example usage in action.

Example usage ⛓

: sampler.readReport("./out/test_run_");

sampler.spec.outputFileName = "./out/test_run_";

sampler.readReport();

Final Remarks ⛓

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright: Computational Data Science Lab

Author:: Joshua Alexander Osborne, May 21 2024, 12:30 AM, University of Texas at Arlington
Fatemeh Bagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.
Amir Shahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin

◆ readRestart()

function Sampler::readRestart	(	in	self,
		in	pattern
	)

Return a list of objects of class pm.sampling.FileContentsRestart containing the content(s) of the ParaMonte simulation output restart file(s) whose path(s) match the specified input pattern or the simulation specification sampler.spec.outputFileName.

Warning: This method is to be only used for post-processing of the output restart file(s) of an already finished simulation.
Although possible, this method is NOT meant to be called by all processes in MPI-parallel simulations.; Currently, only the restart output files in ASCII format can be read via this method.
The binary restart files are not meant to be parsed via this method.
To request for ASCII restart output files in simulations, set the input simulation specification,

sampler.spec.restartFileFormat = "ascii"

where sampler can be an instance of any one of the ParaMonte sampler classes, such as pm.sampling.Paradram.

Warning: Avoid using this routine for very large long simulations.
Reading the full restart file of a large-scale simulation problem can be extremely memory-intensive.

Parameters

[in]	self	: The input parent object of class pm.sampling.Sampler which is implicitly passed to this dynamic method (not by the user).
[in]	pattern	: The input scalar MATLAB string containing the pattern matching the desired restart file(s) whose contents is to be read. The specified `pattern` only needs to partially 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 file(s) beginning with "mysim" and ending with `"_restart.txt"` inside the directory `"./mydir/"`. If there are multiple files matching in the input `pattern`, then all such files will be read and returned as elements of a list. If the specified pattern is a valid existing URL, the file will be downloaded as a temporary file to the local system, its contents shall be parsed and the file will be subsequently removed. If the input `pattern` is empty, then the method will search for any possible candidate files with the appropriate suffix in the current working directory. (optional, default = `sampler.spec.outputFileName` or `"./"`)

Returns: restartList : The output MATLAB cell array of objects of class pm.sampling.FileContentsRestart, each of which corresponds to the contents of a unique restart file.

Possible calling interfaces ⛓

: sampler = pm.sampling.Sampler();

restartList = sampler.readRestart();

restartList = sampler.readRestart([]);

restartList = sampler.readRestart(pattern);

Note: See the documentation of the subclasses of pm.sampling.Sampler (e.g., pm.sampling.Paradram) for example usage in action.

Example usage ⛓

: sampler.readRestart("./out/test_run_");

sampler.spec.outputFileName = "./out/test_run_";

sampler.readRestart();

sampler.readRestart("./out/test_run_", ",");

Final Remarks ⛓

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright: Computational Data Science Lab

Author:: Joshua Alexander Osborne, May 21 2024, 12:35 AM, University of Texas at Arlington
Fatemeh Bagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.
Amir Shahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin

◆ readSample()

function Sampler::readSample	(	in	self,
		in	pattern,
		in	sep
	)

Return a list of objects of superclass pm.sampling.FileContentsSample containing the content(s) of the ParaMonte simulation output sample file(s) whose path(s) match the specified input pattern or the simulation specification sampler.spec.outputFileName.

Warning: This method is to be only used for post-processing of the output sample file(s) of an already finished simulation.
Although possible, this method is NOT meant to be called by all processes in MPI-parallel simulations.

Parameters

[in]	self	: The input parent object of class pm.sampling.Sampler which is implicitly passed to this dynamic method (not by the user).
[in]	pattern	: The input scalar MATLAB string containing the pattern matching the desired sample file(s) whose contents is to be read. The specified `pattern` only needs to partially 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 file(s) beginning with "mysim" and ending with `"_sample.txt"` inside the directory `"./mydir/"`. If there are multiple files matching in the input `pattern`, then all such files will be read and returned as elements of a list. If the specified pattern is a valid existing URL, the file will be downloaded as a temporary file to the local system, its contents shall be parsed and the file will be subsequently removed. If the input `pattern` is empty, then the method will search for any possible candidate files with the appropriate suffix in the current working directory. (optional, default = `sampler.spec.outputFileName` or `"./"`)
[in]	sep	: The input MATLAB string containing the field separator used in the file(s). (optional, default = `sampler.spec.outputSeparator` or automatically inferred.)

Returns: sampleList : The output MATLAB cell array of objects of class pm.sampling.FileContentsSample, each of which corresponds to the contents of a unique sample file.

Possible calling interfaces ⛓

: sampler = pm.sampling.Sampler();

sampleList = sampler.readSample();

sampleList = sampler.readSample([]);

sampleList = sampler.readSample([], []);

sampleList = sampler.readSample(pattern);

sampleList = sampler.readSample([], sep);

sampleList = sampler.readSample(pattern, sep);

Note: See the documentation of the subclasses of pm.sampling.Sampler (e.g., pm.sampling.Paradram) for example usage in action.

Example usage ⛓

: sampler.readSample("./out/test_run_");

sampler.spec.outputFileName = "./out/test_run_";

sampler.readSample();

sampler.readSample("./out/test_run_", ",");

sampler.spec.outputSeparator = ",";

sampler.readSample("./out/test_run_");

sampler.spec.outputFileName = "./out/test_run_";

sampler.spec.outputSeparator = ",";

sampler.readSample();

Final Remarks ⛓

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright: Computational Data Science Lab

Author:: Joshua Alexander Osborne, May 21 2024, 12:38 AM, University of Texas at Arlington
Fatemeh Bagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.
Amir Shahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin

◆ run()

function Sampler::run	(	in	self,
		in	getLogFunc,
		in	ndim
	)

Perform the basic runtime checks for the sampler and return nothing.

Parameters

[in,out]	self	: The input/output parent object of class pm.sampling.Sampler which is implicitly passed to this dynamic method (not by the user).
[in]	getLogFunc	: The input MATLAB function handle or anonymous (lambda) function containing the implementation of the objective function to be sampled. This user-specified function must have the following interface, function logFunc = getLogFunc(state) ... end<br> getLogFunc function getLogFunc(in point) where, the input argument `state` is a vector of type MATLAB `double` of size `ndim` representing a single point from within the `ndim` dimensional domain of the mathematical object function to be explored. the output argument `logFunc` is a scalar of the same type as the input `state` containing the natural logarithm of the objective function at the specified input `state` within its domain.
[in]	ndim	: The input scalar positive-valued whole-number representing the number of dimensions of the domain of the user-specified objective function in the input `getLogFunc()`.

Possible calling interfaces ⛓

: sampler = pm.sampling.Sampler();

sampleList = sampler.run(getLogFunc, ndim);

Sampler::ndim
Property ndim
Definition: Sampler.m:252

Final Remarks ⛓

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright: Computational Data Science Lab

Author:: Joshua Alexander Osborne, May 21 2024, 12:38 AM, University of Texas at Arlington
Fatemeh Bagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.
Amir Shahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin

Field Documentation

◆ bldtype

Property Sampler::bldtype

bldtype

A Hidden scalar MATLAB string containing the build type of the ParaMonte Fortran library that is to be called.
The value of this component is determined at runtime depending on the availability of the ParaMonte Fortran library.
The runtime value is among the values returned by the ParaMonte MATLAB library function pm.lib.bldtypes().

Warning: This Hidden class component must not be accessed by the end users of the library.

Definition at line 189 of file Sampler.m.

◆ checked

Property Sampler::checked

checked

The public scalar MATLAB logical.
If set to true, then the checked (verified) versions of the ParaMonte MATLAB shared libraries will be used for simulations.
This means that most function calls and computations will be checked at runtime to ensure correctness, at the cost of noticeably slower runtime simulation speeds.
Set this option to true only for diagnostics, testing, and development.
If set to empty, the sampler will first search for the non-checked version and if none found, will search for a checked version of the library.

Definition at line 55 of file Sampler.m.

◆ clstype

Property Sampler::clstype

clstype

A Hidden scalar MATLAB string containing the type of the ParaMonte Fortran library parallelization that is to be called.
Although the default value is serial, the class methods will internally set this component to the right parallelization type at runtime.

Warning: This Hidden class component must not be accessed by the end users of the library.

Definition at line 200 of file Sampler.m.

◆ input

Property Sampler::input

input

The public scalar MATLAB string representing the path to an external input file that contains the simulation specification namelist(s).

Warning: Use this optional argument only if you know what you are doing.
Specifying an input simulation file will force the ParaMonte sampler to ignore all other simulation specifications set by the user via the spec component of the sampler instance.

Definition at line 40 of file Sampler.m.

◆ libspec

Property Sampler::libspec

libspec

Optional scalar MATLAB string containing a list of colon-(:)-separated configurations of the kernel shared library to be used for the sampling task.
The most important of all is the compiler suite with which the library is built.

Warning: Use this optional argument only if you know what you are doing.
The specified value for libspec is parsed internally to match a corresponding library path name within the ParaMonte library.
The simulations will fail if no such directory can be found.

Definition at line 277 of file Sampler.m.

◆ libtype

Property Sampler::libtype

libtype

A Hidden scalar MATLAB string containing the type of the ParaMonte Fortran library that is to be called.
Although both static and shared may be possible, this value must always remain as shared.

Warning: This Hidden class component must not be accessed by the end users of the library.

Definition at line 155 of file Sampler.m.

◆ matpath

Property Sampler::matpath

matpath

A Hidden scalar MATLAB string containing the contents of the MATLAB path variable at runtime.

Warning: This Hidden class component must not be accessed by the end users of the library.

Definition at line 231 of file Sampler.m.

◆ memtype

Property Sampler::memtype

memtype

A Hidden scalar MATLAB string containing the memory usage type of the ParaMonte Fortran library that is to be called.
Although both heap and stack may be possible, this value must always remain as heap.

Warning: This Hidden class component must not be accessed by the end users of the library.

Definition at line 177 of file Sampler.m.

◆ method

Property Sampler::method

method

A Hidden scalar MATLAB string containing the name of the ParaMonte sampler subclass that the user has instantiated at runtime.

Warning: This Hidden class component must not be accessed by the end users of the library.

Definition at line 241 of file Sampler.m.

◆ mexname

Property Sampler::mexname

mexname

A Hidden scalar MATLAB string containing the name of the MEX file containing all ParaMonte sampler interfaces.

Warning: This Hidden class component must not be accessed by the end users of the library.

Definition at line 144 of file Sampler.m.

◆ mpiname

Property Sampler::mpiname

mpiname

The public scalar MATLAB string representing the (vendor) name of the MPI runtime library. The following three library names are supported:

"impi" : The Intel MPI runtime library (Windows/Linux).
"mpich" : The MPICH MPI runtime library (Linux/macOS).
"openmpi" : The OpenMPI runtime library (Linux/macOS).

These names are normally one of the possible values returned by pm.lib.mpi.choices().
By default, the ParaMonte samplers should be capable of detecting the right MPI runtime libraries and the ParaMonte library files.
If the automated MPI detection fails or for any reason, or you want to use a non-preferred non-default MPI library, you can set this argument explicitly to one of the values returned by pm.lib.mpi.choices() to enable your preferred choice of MPI-enabled ParaMonte libraries.

Beware that you must launch MATLAB with an mpiexec binary that comes with the same MPI library vendor string specified for mpiname.

The simulation task will mostly likely fail if the MPI-parallel ParaMonte shared libraries corresponding to the specified value for mpiname do not exist in the ParaMonte package.
For example,

On Windows, only ParaMonte library builds with Intel MPI are generally supported.
On Linux, the ParaMonte library builds with all MPI libraries listed above are supported, but there is no guarantee of their availability in the package. Only the MPI-parallel ParaMonte library names returned by pm.lib.mpi.choices() are guaranteed to exist.
On Darwin (macOS), the ParaMonte shared library builds with MPICH and OpenMPI libraries are generally supported, but there is no guarantee of the availability of all of them in the ParaMonte package, unless the corresponding name is among the names returned by pm.lib.mpi.choices().

Warning: Use this optional argument only if you know its ramifications.
This option should rarely be needed in any normal MPI simulation.
The default value for mpiname is an empty string, implying no specific use of MPI-enabled ParaMonte library routines, unless the mpiexec launcher with more than one process is detected at runtime.

Definition at line 107 of file Sampler.m.

◆ name

Property Sampler::name

name

A Hidden scalar MATLAB string containing the name of the user-created object of superclass pm.sampling.Sampler.
This name is determined at runtime via the MATLAB intrinsic function inputname().

Warning: This Hidden class component must not be accessed by the end users of the library.

Definition at line 211 of file Sampler.m.

◆ ndim

Property Sampler::ndim

ndim

A Hidden scalar MATLAB whole-number containing the user-specified value for the number of dimensions of the mathematical density function to be sampled.

Warning: This Hidden class component must not be accessed by the end users of the library.

Definition at line 252 of file Sampler.m.

◆ nml

Property Sampler::nml

nml

A Hidden scalar MATLAB string containing all the sampler specifications to be passed to the sampler as a Fortran namelist.

Warning: This Hidden class component must not be accessed by the end users of the library.

Definition at line 262 of file Sampler.m.

◆ partype

Property Sampler::partype

partype

A Hidden scalar MATLAB string containing the parallelization type of the ParaMonte Fortran library that is to be called.
Although the default value is serial, the class methods will internally set this component to the right parallelization type at runtime.

Warning: This Hidden class component must not be accessed by the end users of the library.

Definition at line 166 of file Sampler.m.

◆ silent

Property Sampler::silent

silent

The public scalar MATLAB logical (Boolean) indicator which is false by default.
If it is set to true, it will silence all output postprocessing messages.

Note: Setting mpiname to a non-empty string will automatically set silent to true.

Definition at line 119 of file Sampler.m.

◆ spec

Property Sampler::spec

spec

The public MATLAB structure containing all simulation specifications.
All specifications are set to appropriate default values at runtime.
Set the spec attributes to the desired values of your choice to override the default simulation specifications.

Definition at line 129 of file Sampler.m.

◆ weblinks

Property Sampler::weblinks

weblinks

A Hidden scalar MATLAB object of class pm.lib.weblinks containing the relevant ParaMonte library web links.

Warning: This Hidden class component must not be accessed by the end users of the library.

Definition at line 221 of file Sampler.m.

The documentation for this class was generated from the following file:

src/matlab/main/+pm/+sampling/@Sampler/Sampler.m

Public Member Functions

Data Fields

Detailed Description

Constructor & Destructor Documentation

◆ Sampler()

Member Function Documentation

◆ finalize()

◆ findfile()

◆ getLogFuncConcurrent()

◆ getLogFuncWrapped()

◆ getppm()

◆ readChain()

◆ readProgress()

◆ readReport()

◆ readRestart()

◆ readSample()

◆ run()

Field Documentation

◆ bldtype

◆ checked

◆ clstype

◆ input

◆ libspec

◆ libtype

◆ matpath

◆ memtype

◆ method

◆ mexname

◆ mpiname

◆ name

◆ ndim

◆ nml

◆ partype

◆ silent

◆ spec

◆ weblinks