|
ParaMonte MATLAB 3.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation. |
|
|
ParaMonte MATLAB 3.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation. |
This is the ParaMonte MATLAB documentation website for the MATLAB users and developers.
ParaMonte is a multi-language library of serial and parallel Monte Carlo and Machine Learning routines scientific inference, e.g., for sampling mathematical density functions of arbitrary-dimensions, with the design goal of unifying
The ParaMonte library is open-source and is permanently located and maintained on GitHub at:
https://github.com/cdslaborg/paramonte
The pre-built releases of the ParaMonte library for select configurations and compilers are available on GitHub Release page at:
https://github.com/cdslaborg/paramonte/releases
For instructions to build the ParaMonte library from source files, visit the ParaMonte library main documentation website linked below.
For information about the ParaMonte library in general and in other supported programming languages, visit:
https://www.cdslab.org/paramonte
The documentation for the latest version of the ParaMonte MATLAB library is always available on this page.
For more information on the installation, general usage, and examples, visit:
https://www.cdslab.org/paramonte/generic/latest/installation/matlab/
To get started with the library once you download it, simply add the path to the ParaMonte library +pm package to access the routines and functionalities available in the library.
The MATLAB equivalent of modules is called package. Similar to modules in other languages, MATLAB packages can be imported to the MATLAB environment or simply be used as namespace. For example,
The ParaMonte MATLAB library currently contains a myriad of MATLAB packages.
The ParaMonte MATLAB library is currently under active development to extend the library functionalities to other tasks supported by the ParaMonte Fortran library.
For a full list of all available functionalities and modules, see the files listing and class listing of this documentation website.
Perhaps the most relevant ParaMonte MATLAB modules to the end users are the ParaMonte samplers in the pm.sampling package of the library.
See for example, the documentation of the parallel Delayed-Rejection Adaptive Metropolis Markov Chain Monte Carlo sampler pm.sampling.Paradram.
By convention in this library,
Vec or Vector.Mat or Matrix.logical variables with a passive verb.logical variable name should be an English-language statement that evaluates to either true or false.parallelismMpiFinalizeEnabled is one such proposition.is can also be used to label logical objects.getCov means generate (a) covariance matrix.setMatCopy means copy the matrix into the specified buffer.get.getMatSym(mat) generates a symmetric version of the input matrix and returns it as the function result.get prefix is inconvenient or when the function returns a logical result.logical should be preferably prefixed with is or be named such that the name begins with a verb and reads as a proposition, evaluating to either .true. or .false..The following list of abbreviations is in alphabetical order to enable faster search:
avg stands for average (rarely used).cdf stands for Cumulative Distribution Function in the context of statistics. Example: getNormCDF().cho stands for Cholesky factorization. Example: setChoLow().chol stands for Cholesky factorization. Example: setMatChol().cor stands for correlation. Example: getCor().cov stands for covariance. Example: getCov().cum stands for cumulative. Example: getCumSum().coef stands for coefficient. Example: corcoef_type().def stands for default in variable names (mostly as a prefix def_ or suffix _def).def stands for definite (mostly in procedure names dealing with positive-definite matrices)den stands for density, mostly in the context of statistical procedures and objects. Example: getLogProbDen().det stands for determinant, mostly in the context of Matrix and linear algebra. Example: getMatDet().dia stands for diagonal, mostly in the context of matrix algebra, matrix packing, or Cholesky factorization. Example: dia_type().diag stands for diagonal, mostly as dummy argument in matrix algebra procedures.desc stands for description, mostly as a dummy argument in tests.diff stands for difference. Example: setDisSortedExpDiff().dist stands for distance or distribution depending on the context. Example: DistMulti_type.eff stands for effective. Example: effSamSize.exp stands for exponential or exponentiated. Example: setDisSortedExpDiff().hell stands for Hellinger in statistical distance computations. Example: getDisHellSq().herm stands for hermitian in matrix algebra.ice stands for Internal Compiler Error. It typically appears in the bug descriptions tagged via Doxygen command \bug.inv stands for inverse. Example: getMatInv().ks stands for Kolmogorov-Smirnov test. Example: getProbKS().lin stands for linear. Example: getLinSpace().low stands for lower triangle of a matrix or lower limits. Example: setChoLow().mahal stands for Mahalanobis distance. Example: getDisMahalSq().mat stands for matrix. Example: getMatInv().multi stands for multivariate mostly used in the context of statistical distributions. Example: getMultiNormRand().msn stands for Multivariate Skew-Normal mostly used in the context of the statistical MultiVariate Skew-Normal distribution.mvn stands for MultiVariate Normal mostly used in the context of the statistical MultiVariate Normal distribution.mvu stands for MultiVariate Uniform mostly used in the context of the statistical MultiVariate (ellipsoidal) Uniform distribution.norm stands for normal in the context of statistical distributions or normalization factor. Example: DistMultiNorm_type.normed stands for normalized mostly in the context of statistical samples. Example: NormedSample.pdf stands for Probability Density Function in the context of statistics. Example: getNormLogPDF().pos stands for positive. Example: getInvPosDefMat().prob stands for probability, mostly in the context of statistical applications. Example: getLogProb().proc stands for procedure, particularly, when it appears as the suffix _proc in abstract interface definitions.quan stands for quantile, mostly in the context of statistics. Example: getParetoLogQuan().rand stands for random, mostly in the context of statistics. Example: getUnifRand().ref stands for reference, mostly in the context of testings to represent the reference values for comparison. Example: mean_ref.sam stands for sample, mostly in the context of statistics. Example: effSamSize.sq stands for squared. Example: getDisMahalSq().stat stands for statistics. Example: StatDRAM_type.std stands for standard deviation. Example: StdVec.sym stands for symmetric.symm stands for symmetric.udf stands for Unnormalized Density Function in the context of statistics. Example: getEggBoxLogUDF().uni stands for univariate, mostly used in the context of statistical distributions. Example: DistUni_type.unif stands for uniform, mostly in the context of the uniform statistical distribution. Example: getUnifRand().upp stands for upper triangle of a matrix or upper limits. Example: setChoUpp().vec stands for vector. Example: stdVec.The ParaMonte MATLAB library development and guidelines are summarized in CONTRIBUTING.md.
\brief must always be the first line of the documentation of modules, types, and procedures.\details, if it exists, must always immediately follow the Doxygen tag \brief.\param, if any number of it exists, must always immediately follow the Doxygen tag \brief (or \details if it exists).\return, must be exclusively used to indicate the return value of functions.\param tags. Example: pm.sampling.Paradram.\interface must appear immediately after the Doxygen \return, \param, \details, or \brief tags in the specified order, if any exists.\warning, if any number of it exists, must immediately follow the Doxygen tag \return if it exists, otherwise \param if it exists, otherwise \details if it exists, otherwise \brief.\warning tag must be used to highlight situations that require special attention of the user, otherwise, there is a danger for the code section being documented to not behave normally as one may expect.\attention has the same functionality and usage as \warning.\warning should be preferred wherever \attention is needed.\warning also apply to the tag \attention.\remark, if any number of it exists, must immediately follow the Doxygen tag \warning if it exists, otherwise the Doxygen tag \return if it exists, otherwise \param if it exists, otherwise \details if it exists, otherwise \brief.\remark should be reserved for explaining behavior that is directly related to the code segment being documented, but its knowledge is not so critical as warrant the use of a \warning tag.\note, if it exists, must appear after all \warning and \attention and \remark tags and immediately before the ParaMonte custom command tag \see if it exists, otherwise immediately before \example for examples (if it exists).\see, if it exists, must appear after all \warning and \remark and \note tags.\see command exists, each must be written on a separate line and each line must end with the HTML line-break tag <br>. Example: See below.\see tag, otherwise after \note, \remark, \warning, \param, \details, or \brief if any exists.\example devised in the config.txt file of ParaMonte Doxygen documentation.\include command, followed immediately by the ParaMonte custom Doxygen command \compile which inserts the generic example compile commands for the example, followed optionally but immediately by the output file of the example inserted in the documentation via the \include command, followed immediately by the inclusion of any other visualization or postprocessing scripts and output.\example, otherwise, each empty line will start a new paragraph in the documentation.\test tag, if any exists, must appear immediately after the example section designated by the \example tag.\bug tag, if any exists, must appear immediately after the \test tag or any other tag immediately preceding it.\todo tag, if any exists, must appear immediately after the \todo tag or any other tag immediately preceding it.\final separated from the tags before and after by an empty line.\xrefitem authors "Author" "Authors" tag is the last command to appear in any documentation section, and it must preferably have the format exemplified in the example below.ParaMonte Doxygen custom commands.
To simplify documentation and avoid retyping certain frequently used keywords and sentences, a number of Doxygen aliases are predfined in the ParaMonte Doxygen config.txt file. These include (but are not limited to):
\warnpure Inserts a \warning about procedures that are impure when the library is built the preprocessor macro CHECK_ENABLED=1.\elemental Inserts a \remark tag indicating that the procedure of interest is elemental.\pure Inserts a \remark tag indicating that the procedure of interest is pure.\interface Starts a Possible calling interfaces paragraph where different calling interfaces of a procedure can be listed.\benchmark Starts a new Benchmark paragraph which is hyper-linked to the generic anchor #benchmark at the same location on the same page.\benchmark{xxx} Starts a new Benchmark paragraph which is hyper-linked to the specific anchor #benchmark-xxx at the same location on the same page.\benchmark{xxx, This is the benchmark title} Starts a new Benchmark paragraph which is hyper-linked to the specific anchor #benchmark-xxx at the same location on the same page with the title This is the benchmark title.\example Starts a new Example usage paragraph which is hyper-linked to the generic anchor #example at the same location on the same page.\example{xxx} Starts a new Example usage paragraph which is hyper-linked to the specific anchor #example-xxx at the same location on the same page.\compile Inserts the set of example compile commands.\output Inserts a title line for the output section of an example paragraph.\postproc Inserts a title line for the postprocessing section of an example paragraph.\abbr Inserts a \remark tag about the naming abbreviations used in the library.\naming Inserts a \remark tag about the naming conventions used in the library.\license Inserts a \remark tag about the generic licensing of the library.\final Inserts the set of final generic remarks that should appear at the end of each documentation section. For an up-to-date list of all available aliases, check the value of the Doxygen ALIASES option in config.txt in the ParaMonte MATLAB documentation repository.
Escaping the Doxygen reserved characters.
Doxygen has a set of reserved characters whose usage in the documentation must be handled properly.
\ begins a Doxygen command.\\.% requires special care in some instances.For more information, see the relevant page on Doxygen documentation website.
\warning, \remark, \note and other similar tags.///
/// \brief
/// This is the ParaDRAM class for generating instances of serial and parallel
/// Delayed-Rejection Adaptive Metropolis-Hastings Markov Chain Monte Carlo
/// sampler of the ParaMonte MATLAB library.<br>
///
/// \brief
/// Once you assign the desired simulation specifications to the corresponding
/// attributes within the component `spec` of an object of class [pm.sampling.Paradram](@ref Paradram),
/// call the ParaDRAM sampler via the object method [pm.sampling.Paradram.run()](@ref Paradram::run).<br>
///
/// While the constructor of this class does not take any input arguments,
/// all ParaDRAM simulation specifications can be set after creating the object.<br>
///
/// \return
/// ``sampler`` : The output scalar object of class [pm.sampling.Paradram](@ref Paradram).<br>
///
/// \interface{Paradram}
/// \code{.m}
///
/// sampler = pm.sampling.Paradram();
///
/// \endcode
///
/// \warning
/// When using the ParaMonte MATLAB library functionalities, particularly ParaMonte samplers in parallel,
/// it would be best to close any such aggressive software/applications as Dropbox, ZoneAlarm, ...
/// that interfere with your ParaMonte MATLAB library output files, potentially causing the tasks
/// to fail and crash before successful completion.<br>
/// These situations happen only scarcely.<br>
///
/// \note
/// On Windows systems, when restarting an old interrupted ParaDRAM simulation,
/// ensure your MATLAB session is also restarted before the simulation restart.<br>
/// This may be needed as Windows sometimes locks access to some or all of the simulation output files.<br>
///
/// \note
/// To unset an already-set input simulation specification, simply set the
/// simulation attribute to empty double `[]` or re-instantiate the object.<br>
///
/// \see
/// [ParaDRAM simulation specifications listing](\pmdoc_usage_sampling/paradram/specifications/)<br>
/// [ParaDRAM simulation restart functionality](\pmdoc_usage_sampling/paradram/restart/)<br>
/// [ParaDRAM simulation output files](\pmdoc_usage_sampling/paradram/output/)<br>
///
/// Example Usage: Serial
/// ---------------------
///
/// First, ensure the ParaMonte ``+pm`` package (i.e., folder) is available in your MATLAB paths.
///
/// Here is a MATLAB script ``main.m`` for a serial ParaDRAM simulation.<br>
/// Copy and paste the following code into your MATLAB session:<br>
///
/// \code{.m}
///
/// sampler = pm.sampling.Paradram();
/// sampler.run ( @(x) - sum(x.^2) ... getLogFunc: the natural log of the objective function.
/// , 4 ... ndim: the number of dimensions of the objective function.
/// );
/// samples = sampler.readSample();
/// sample = samples{1};
/// tile = pm.vis.TileLine(sample.df);
/// tile.make("coly", sample.slfc + 1 : sample.slfc + 4, "colc", "sampleLogFunc");
///
/// \endcode
///
/// The mathematical objective function in the above example is a
/// is a multivariate Normal distribution centered at the origin,
/// whose natural logarithm is returned by the lambda (``Anonymous``)
/// function defined as a function handle input to the ParaDRAM sampler.<br>
///
/// Running this code will generate a set of simulation output files (in the current working directory of MATLAB).<br>
/// Among these, the file suffixed with "_report.txt" contains the full description of all input specifications
/// of the ParaDRAM simulation as well as other information about the simulation results.<br>
///
/// Example Usage: Thread-Parallel
/// ------------------------------
///
/// First, ensure the ParaMonte ``+pm`` package (i.e., folder) is available in your MATLAB paths.<br>
///
/// Threading parallelism is possible as of ParaMonte MATLAB version ``3.0.0``.<br>
/// However, only ``singleChain`` ParaDRAM simulations are supported.<br>
///
/// Here is a MATLAB script ``main.m`` for a thread-parallel ParaDRAM simulation.<br>
/// Copy and paste the following code and paste into your MATLAB session:<br>
///
/// \code{.m}
///
/// sampler = pm.sampling.Paradram();
/// sampler.spec.parallelismNumThread = 0; % use all available threads.
/// sampler.run ( @(x) - sum(x.^2) ... getLogFunc: the natural log of the objective function.
/// , 4 ... ndim: the number of dimensions of the objective function.
/// );
/// samples = sampler.readSample();
/// sample = samples{1};
/// pm.vis.tile(sample.contents)
///
/// \endcode
///
/// The mathematical objective function in the above example is a
/// is a multivariate Normal distribution centered at the origin,
/// whose natural logarithm is returned by the lambda (``Anonymous``)
/// function defined as a function handle input to the ParaDRAM sampler.<br>
///
/// Running this code will generate a set of simulation output files (in the current working directory of MATLAB).<br>
/// Among these, the file suffixed with ``"_report.txt"`` contains the full description of all input specifications
/// of the ParaDRAM simulation as well as other information about the simulation results.<br>
///
/// Specifying ``0`` as the number of threads will lead to using
/// all available CPU threads for thread-parallel ParaDRAM simulation.<br>
///
/// \note
/// **Benefits of thread-parallelism**<br>
/// Thread-parallel simulations offer a much more flexible
/// and easier approach to benefiting from parallelism without
/// going through the hassle of MPI-parallel simulations.<br>
/// But they can still potentially offer much faster speed than serial simulations.<br>
/// The actual speedup depends on a lot of factors.<br>
/// Moreover, the number of threads is limited to maximum
/// number of physical cores available on your system.<br>
/// As such, thread-parallel simulations are not scalable.<br>
/// If you need scalability, checkout MPI-parallelism below.<br>
///
/// Example Usage: MPI-Parallel
/// ---------------------------
///
/// First, ensure the ParaMonte ``+pm`` package (i.e., folder) is available in your MATLAB paths.<br>
///
/// MPI-parallel simulations can be slightly more cumbersome than thread-parallel simulations
/// described above because MPI-parallel simulations cannot be performed from within a MATLAB GUI
/// session and require launching MATLAB via a compatible ``mpiexec`` launcher.<br>
///
/// <ol>
/// <li> Ensure you need and will get a speedup by running the an MPI-parallel simulation.<br>
/// Typically, your simulation may then benefit from parallelism only if a single
/// evaluation of the objective function takes longer than a few milliseconds.<br>
///
/// <li> Ensure the required MPI libraries are installed on your system
/// (You can skip this step if you know that you already have
/// a compatible MPI library installed on your system).<br>
/// On the MATLAB command line type the following,<br>
/// \code{.m}
/// pm.lib.verify();
/// \endcode
/// This will verify the existence of a valid MPI library on your system and,
/// if missing, will guide you to install the MPI library on your system.<br>
///
/// <li> Once the MPI installation is verified, copy and paste the following
/// code into your MATLAB session:
/// \code{.m}
///
/// fid = fopen("main_mpi.m", "w");
/// sourceCode = ...
/// "sampler = pm.sampling.Paradram();" + newline + ...
/// "%sampler.mpiname = ''; % set this to an explicit MPI library name if needed." + newline + ...
/// "sampler.run( @(x) - sum(x.^2) ... getLogFunc: the natural log of the objective function." + newline + ...
/// " , 4 ... ndim: the number of dimensions of the objective function" + newline + ...
/// " );";
/// fprintf(fid, "%s\n", sourceCode);
/// fclose(fid);
///
/// \endcode
///
/// <li> This will generate a ``main_mpi.m`` MATLAB script file in the current working directory of your MATLAB session.<br>
/// Now, you can execute this MATLAB script file (``main_mpi.m``) in parallel.<br>
/// To do so, you need to call MATLAB on a command-line, **out of MATLAB GUI**.<br>
/// <ol>
/// <li> **On Windows**:<br>
/// From within command prompt that recognizes both MATLAB and ``mpiexec``,
/// ideally, the Intel dedicated command-prompt that is shipped with Intel MPI library,
/// type the following,
/// \code{.m}
///
/// mpiexec -localonly -n 3 matlab -batch "main_mpi"
///
/// \endcode
///
/// \note
/// In the above MPI launcher command for Windows OS,
/// we assumed that you would be using the Intel MPI library, hence,
/// the reason for the extra flag ``-localonly``.<br>
/// This flag runs the parallel code only on one node, but in doing so,
/// it avoids the use of Hydra service and its registration.<br>
/// If you are not on a Windows cluster, (e.g., you are using your personal device),
/// then we recommend specifying this flag.<br>
///
/// <li> **On macOS/Linux**:<br>
/// From within a Bash terminal that recognizes both MATLAB and ``mpiexec``,
/// type the following,
/// \code{.m}
///
/// mpiexec -n 3 matlab -batch "main_mpi"
///
/// \endcode
///
/// \note
/// In both cases in the above, the script ``main_mpi.m`` will run on 3 processors.<br>
/// Feel free to change the number of processors to any number desired.<br>
/// But do not request more than the available number of physical cores on your system.<br>
/// </ol>
/// </ol>
///
/// \warning
/// Do not add postprocessing codes (such as reading and plotting the output samples) in your MPI-parallel code.<br>
/// There is no point in doing so, since MATLAB will run in ``-batch`` mode for parallel simulations, disabling all plotting capabilities.<br>
/// Moreover, if you read and postprocess the output files in parallel mode, the task will be done
/// by all parallel processes, potentially overwriting external IO activities of each other.<br>
/// Only perform the sampling as described above in MPI-parallel mode.<br>
///
/// ParaDRAM Simulation Specifications
/// ----------------------------------
///
/// The ParaDRAM simulation specifications have lengthy comprehensive descriptions
/// that appear in full in the output report files of every ParaDRAM simulation.<br>
///
/// The best way to learn about individual ParaDRAM simulation attributes
/// is to a run a minimal serial simulation as given in the above.<br>
/// You can also use the ``sampler.spec.doc()`` method:
///
/// \code{.m}
/// sampler = pm.sampling.Paradram();
/// sampler.spec.doc();
/// \endcode
///
/// \final{Paradram}
///
/// \author
/// \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
///
/// \example.The ParaMonte MATLAB library ships with tens of thousands of example usage that are available in the example/matlab folder in the root directory of the project repository.
These examples are also available and discussed in the documentations of individual modules and procedures of this this documentation website.
The ParaMonte MATLAB library currently does not ship with any benchmarks.
If you would like to see a relevant benchmark currently not included, discuss it here or raise an issue here for consideration or volunteer to implement it!
1.9.3