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	readChain (in self, in pattern, in sep)
	Return a list of objects of class 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.FileContentsRestartDRAM 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 class 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 sampler subclasses 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:138

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.

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:: 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:105

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 )

◆ readChain()

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

Return a list of objects of class 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 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 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.)

Returns: chainList : The output MATLAB cell array of objects of class 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);

Note: See the documentation of the sampler subclasses (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);

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

Note: See the documentation of the sampler subclasses (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 sampler subclasses (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();

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

sampler.spec.outputSeparator = ",";

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

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

sampler.spec.outputSeparator = ",";

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.FileContentsRestartDRAM 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 sampler subclasses (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_", ",");

sampler.spec.outputSeparator = ",";

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

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

sampler.spec.outputSeparator = ",";

sampler.readRestart();

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 class 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 sampler subclasses (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:140

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

Definition at line 128 of file Sampler.m.

◆ checked

Property Sampler::checked

checked : Optional 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 51 of file Sampler.m.

◆ clstype

Property Sampler::clstype

Definition at line 130 of file Sampler.m.

◆ input

Property Sampler::input

input : Optional 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 38 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 156 of file Sampler.m.

◆ libtype

Property Sampler::libtype

Definition at line 122 of file Sampler.m.

◆ matpath

Property Sampler::matpath

Definition at line 136 of file Sampler.m.

◆ memtype

Property Sampler::memtype

Definition at line 126 of file Sampler.m.

◆ method

Property Sampler::method

Definition at line 138 of file Sampler.m.

◆ mexname

Property Sampler::mexname

Definition at line 120 of file Sampler.m.

◆ mpiname

Property Sampler::mpiname

mpiname : Optional 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).

By default, you should set this argument to pm.lib.mpi.choice() to enable the right preferred choice of MPI-enabled ParaMonte libraries.
If for any reason, you want to use a non-preferred non-default MPI library, you can set the MPI library name explicitly as in the above list.
Beware that you must launch MATLAB with an mpiexec binary that comes from the same MPI library vendor specified for mpiname.
Note that the MPI-parallel ParaMonte shared libraries corresponding to the specified value for mpiname may not exist in the ParaMonte package.
For example,

On Windows, only ParaMonte library builds with Intel MPI are 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 ParaMonte library builds with Intel MPI ("impi") are guaranteed to exist, unless user builds the ParaMonte MATLAB package from GitHub source for the desired MPI library.
On Darwin (macOS), only the ParaMonte shared library builds with MPICH and OpenMPI libraries are supported, but there is no guarantee of their availability in the package. Only the ParaMonte library builds with OpenMPI ("openmpi") are guaranteed to exist, unless user builds the ParaMonte MATLAB package from GitHub source for the desired specified MPI library.

Warning: USE THIS OPTIONAL ARGUMENT ONLY IF YOU KNOW ITS RAMIFICATIONS.
This option should rarely be needed in any normal simulation.
The default value for mpiname is an empty string, implying no use of MPI-enabled ParaMonte library routines.

Definition at line 95 of file Sampler.m.

◆ name

Property Sampler::name

Definition at line 132 of file Sampler.m.

◆ ndim

Property Sampler::ndim

Definition at line 140 of file Sampler.m.

◆ nml

Property Sampler::nml

Definition at line 143 of file Sampler.m.

◆ partype

Property Sampler::partype

Definition at line 124 of file Sampler.m.

◆ silent

Property Sampler::silent

silent : Optional 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 105 of file Sampler.m.

◆ spec

Property Sampler::spec

spec : A 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 113 of file Sampler.m.

◆ weblinks

Property Sampler::weblinks

Definition at line 134 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()

◆ 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