MIT License
ParaMonte: plain powerful parallel Monte Carlo library.
Copyright (C) 2012-present, The Computational Data Science Lab
https://github.com/cdslaborg/paramonte
References

Sampling a 4-dimensional MultiVariate Normal distribution (MVN) via the ParaMonte library's ParaDRAM routine

NOTE
If you are viewing an HTML version of this MATLAB live script on the web, you can download the corresponding MATLAB live script *.mlx file to this HTML page at,
https://github.com/cdslaborg/paramontex/raw/main/MATLAB/mlx/sampling_multivariate_normal_distribution_via_paradram/sampling_multivariate_normal_distribution_via_paradram.mlx
This code, along with other MATLAB live scripts, is located at,
https://github.com/cdslaborg/paramontex/tree/main/MATLAB/mlx
Once you download the file, open it in MATLAB to view and interact with its contents, which is the same as what you see on this page.
NOTE
This ParaDRAM sampler example is also available in Python language as a Jupyter Notebook, on this page,
https://nbviewer.jupyter.org/github/cdslaborg/paramontex/blob/main/Python/Jupyter/sampling_multivariate_normal_distribution_via_paradram/sampling_multivariate_normal_distribution_via_paradram.ipynb
This Jupyter Notebook, along with other Python Jupyter Notebooks, is located at,
https://github.com/cdslaborg/paramontex/tree/main/Python/Jupyter
IMPORTANT - macOS users
If you are a macOS (Darwin) user and you have downloaded the prebuilt ParaMonte libraries from the GitHub release page to use on your macOS system, read this troubleshooting page before continuing.

The logic of Monte Carlo sampling is very simple

==========================================================
Suppose we have a mathematical objective function defined on an ndim-dimensional domain. Typically, this domain is defined on the space of real numbers. In general, understanding and visualizing the structure of such objective functions is an extremely difficult task, if not impossible. As a better alternative, you employ Monte Carlo techniques that can randomly explore the structure of the objective function and find the function's extrema.
In the following example, one of the simplest such objective functions, the Multivariate Normal Distribution (MVN), is constructed and sampled using the ParaMonte library samplers, here, the ParaDRAM sampler (Delayed-Rejection Adaptive Metropolis-Hastings Markov Chain Monte Carlo sampler).
Suppose we want to sample random points from a MultiVariate Normal (MVN) Probability Density Function (PDF). The PDF equation of MVN is the following,

Setting up the path to the ParaMonte::MATLAB library

================================================================
First, we will clean up the MATLAB environment and make sure the path to the ParaMonte library is in MATLAB's path list.
clc;
clear all;
close all;
format compact; format long;
%%%%%%%%%%%% IMPORTANT %%%%%%%%%%%%%
% Set the path to the ParaMonte library:
% Change the following path to the ParaMonte library root directory,
% otherwise, make sure the path to the ParaMonte library is already added
% to MATLAB's path list.
pmlibRootDir = './';
addpath(genpath(pmlibRootDir),"-begin");
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% change MATLAB's working directory to the folder containing this script
% if MATLAB Live Scripts did not create a temporary folder, we would not
% have all of these problems!
try
setwdFilePath = websave("setwd.m","https://github.com/cdslaborg/paramontex/raw/main/MATLAB/mlx/setwd.m");
run(setwdFilePath); % This is a MATLAB script that you can download from the same GitHub location given in the above.
catch % alas, we will have to run the simulations in MATLAB Live Script's temporary folder
filePath = mfilename('fullpath');
[currentDir,fileName,fileExt] = fileparts(filePath); cd(currentDir);
cd(fileparts(mfilename('fullpath'))); % Change working directory to source code directory.
end

Constructing the objective function

==========================================
The following MATLAB function getLogFunc() returns the natural logarithm of the Probability Density Function (PDF) of the MultiVariate Normal (MVN) distribution,
NDIM = 4; % the number of dimensions of the domain of the objective function
MEAN = [-10; 15.; 20.; 0.0]; % This is the mean of the multivariate normal (MVN) distribution. THIS IS A COLUMN VECTOR.
COVMAT = [ 1.0,.45,-.3,0.0 ...
; .45,1.0,0.3,-.2 ...
; -.3,0.3,1.0,0.6 ...
; 0.0,-.2,0.6,1.0 ...
]; % This is the covariance matrix of the MVN distribution.
INVCOV = inv(COVMAT); % This is the inverse of the covariance matrix of the MVN distribution.
MVN_COEF = NDIM * log( 1. / sqrt(2.*pi) ) + log( sqrt(det(INVCOV)) ); % This is the log of the coefficient used in the definition of the MVN.
getLogFunc = @(point) MVN_COEF - 0.5 * dot( (MEAN-point)' , INVCOV*(MEAN-point) ); % return the logarithm of the objective function: log(MVN)
NOTE
Since the mathematical objective functions (e.g., probability density functions) can take extremely small or large values, we often work with their natural logarithms instead. This is the reason behind the naming convention used in the ParaMonte library for the user's objective functions: getLogFunc, implying that the user must provide a function that returns the natural logarithm of the target objective function.
See MATLAB Live Script for an in-depth discussion of why we need to work with the logarithm of mathematical objective functions in optimization and sampling problems.
IMPORTANT
Note that in MATLAB all vectors and arrays are, by default, column-major, and so is the input value, point, to getLogFunc(). This means that the size of point is (ndim,1). Thus, all other vectors that interact with point, for example, the mean vector, must be also of the same size as point: (ndim,1).

Running a ParaDRAM simulation on a single processor

==================================================================
We will sample random points from this objective function by calling the ParaDRAM sampler (Parallel Delayed-Rejection Adaptive Metropolis-Hastings Markov Chain Monte Carlo sampler) of the ParaMonte library.
Note: To run the ParaMonte samplers in parallel, visit the ParaMonte library's documentation website.
We will first create an instance of the paramonte class,
pm = paramonte();

Checking the ParaMonte library's version

==========================================
Before runnnig any simulations, it is good to check which version of the ParaMonte library you have and are working with,
pm.version.interface.get() % get the ParaMonte::MATLAB (interface) version
ans = "ParaMonte MATLAB Interface Version 2.3.0"
pm.version.interface.dump()
ans = "2.3.0"
pm.version.kernel.get() % the ParaMonte::Kernel version (the version of the ParaDRAM sampler)
ans = "ParaMonte MATLAB Kernel Version 1.5.0"
pm.version.kernel.dump()
ans = "1.5.0"
We can also verify the existence of the essential components of the current installation of the ParaMonte library on the system,
pm.verify();
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: :::: :::: _/_/_/_/ _/_/ _/_/ _/ _/ _/_/_/_/_/ _/ _/ _/ _/_/_/_/ _/ /_/_/ _/_/_/_/ _/ _/ _/ _/_/ _/_/_/ _/_/_/ _/_/_/ _/_/_/ _/ _/ _/_/ _/ _/ _/ _/ _/ _/ _/ _/ _/ _/_/_/_/ _/ _/ _/ _/ _/ _/ _/ _/ _/ _/ _/ _/ _/ _/ _/_/_/ _/_/_/_/ _/ _/_/_/_/ _/_/_/ _/_/_/ _/_/ _/ _/ _/_/ _/_/_/ ParaMonte plain powerful parallel Monte Carlo library Version 2.3.0 :::: :::: ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ParaMonte - NOTE: Intel MPI library for 64-bit architecture detected at: ParaMonte - NOTE: ParaMonte - NOTE: "C:\Program Files (x86)\IntelSWTools\compilers_and_libraries_2020.1.216\windows\mpi\intel64\bin" ParaMonte - NOTE: ParaMonte - NOTE: To perform ParaMonte simulations in parallel on a single node, run the ParaMonte - NOTE: following two commands, in the form and order specified, on a MATLAB-aware ParaMonte - NOTE: mpiexec-aware command-line interface, such as the Intel Parallel Studio's command-prompt: ParaMonte - NOTE: ParaMonte - NOTE: "C:\Program Files (x86)\IntelSWTools\compilers_and_libraries_2020.1.216\windows\mpi\intel64\bin\mpivars.bat" ParaMonte - NOTE: ParaMonte - NOTE: mpiexec -localonly -n 3 matlab -batch "main_mpi" ParaMonte - NOTE: ParaMonte - NOTE: where, ParaMonte - NOTE: ParaMonte - NOTE: 0. the first command defines the essential environment variables and, ParaMonte - NOTE: the second command runs in the simulation in parallel, in which, ParaMonte - NOTE: 1. you should replace the default number 3 with the number of ParaMonte - NOTE: processors you wish to assign to your simulation task, ParaMonte - NOTE: 2. main_mpi.m is the MATLAB file which serves as the entry point to ParaMonte - NOTE: your simulation, where you call the ParaMonte sampler routines. ParaMonte - NOTE: ATTN: Notice the MATLAB filename must appear without the file extension. ParaMonte - NOTE: ATTN: Notice the MATLAB filename must be enclosed with quotation marks. ParaMonte - NOTE: 3. -localonly indicates a parallel simulation on only a single node (this ParaMonte - NOTE: flag will obviate the need for MPI library credentials registration). ParaMonte - NOTE: For more information, visit: ParaMonte - NOTE: ParaMonte - NOTE: https://software.intel.com/en-us/get-started-with-mpi-for-windows ParaMonte - NOTE: ParaMonte - NOTE: Note that the above two commands must be executed on a command-line that recognizes ParaMonte - NOTE: both MATLAB and mpiexec applications, such as the Intel Parallel Studio's command-prompt. ParaMonte - NOTE: For more information, in particular, on how to register to run Hydra services ParaMonte - NOTE: for multi-node simulations on Windows servers, visit: ParaMonte - NOTE: ParaMonte - NOTE: https://www.cdslab.org/paramonte ParaMonte - NOTE: To check for the ParaMonte or the MPI library installations status or, ParaMonte - NOTE: to display the above messages in the future, use the following ParaMonte - NOTE: commands on the MATLAB command-line: ParaMonte - NOTE: ParaMonte - NOTE: pm = paramonte(); ParaMonte - NOTE: pm.verify();

Setting up the ParaDRAM simulation specifications

====================================================
Now, we create an instance of the ParaDRAM sampler class,
pmpd = pm.ParaDRAM();
The simplest scenario is to run the simulation with the default specifications that are appropriately determined by the ParaDRAM sampler. However, for the purpose of clarity reproducibility, we will specify a few simulation specs,
For a complete list of all ParaDRAM simulation specifications, visit the ParaDRAM simulation specifications webpage.

The simulation output file names and storage path

We will store all output files in a directory with the same name as this MATLAB Live Script's name.
By default, all ParaDRAM simulation output files are named properly (see this page for a review of ParaDRAM simulation output files). In general, it is a good habit to specify an output file prefix for any ParaDRAM simulation. This way, the restart of an incomplete simulation, if it happens for some reason, would be seamless and doable by just rerunning the simulation, without any change of any sort to any parts of the codes or the simulation.
We will prefix all simulation output files the same as the filename of this script,
pmpd.spec.outputFileName = "./out/mvn_serial";
The above outputFileName will result in the generation of a folder named ./out/, which will keep the simulation output files, all of which are prefixed with mvn_serial.
NOTE
If the specified prefix ends with a forward slash / on Linux/macOS or with a backslash \ on Windows, then the prefix provided will serve as the directory in which the output files will be stored.

Ensuring the reproducibility of the results

We will also initialize the random seed to a fixed number to ensure the reproducibility of the simulation results in the future,
pmpd.spec.randomSeed = 3751;
For the sake of illustration, let's also ask for a modest refinement (decorrelation) of the final sample,
pmpd.spec.sampleRefinementCount = 1;

Setting the output sample size to a non-default value

Not so important, but we will also specify a chainSize here, 50000, the number of unique points to be sampled from the objective function. This number is smaller than the default 100,000 unique sample points of the sampler.
pmpd.spec.chainSize = 50000;

Requesting an ASCII-formatted output restart file (for illustration purposes)

For the sake of illustration, we will also request an ASCII-format restart output file,
pmpd.spec.restartFileFormat = "ascii";
Note, however, that you do not want to request an ACSII-formatted output restart file in your real production simulation as it will slow down your simulation. Just do not set this property and it will be automatically taken care of.

The default domain of the objective function

The default starting point of the sampler for exploring the objective function is the center of the domain of the objective function. The default domain of the objective function chosen by the sampler is along each dimension of the objective function. This is a fine default assumption for this particular simulation and in most other scenarios. If needed, you can change them via the following attributes,
pmpd.spec.domainLowerLimitVec = -1.e300 * ones(NDIM,1); % set the lower limits of the domain of the objective function to negative infinity (This is the default value)
pmpd.spec.domainUpperLimitVec = +1.e300 * ones(NDIM,1); % set the upper limits of the domain of the objective function to negative infinity (This is the default value)
The ParaDRAM sampler guarantees to not sample any points outside the hypercube defined by the above limits.

Calling the ParaDRAM sampler

===============================
Note that none of the above specification settings were necessary, but is in general a good habit to define them prior to the simulation.
We now call the ParaDRAM sampler routine to run the sampling simulation. For the same of this simulation, we will also make the output files overwritable (before doing, The ParaDRAM sampler method takes only two arguments. We can call it like the following,
pmpd.spec.overwriteRequested = true; % overwrite the simulation output files if they already exist
pmpd.runSampler ( NDIM ... This is the number of dimensions of the objective function
, getLogFunc ... This is the objective function
);
ParaDRAM - NOTE: Running the ParaDRAM sampler in serial mode... ParaDRAM - NOTE: To run the ParaDRAM sampler in parallel mode visit: cdslab.org/pm ************************************************************************************************************************************ ************************************************************************************************************************************ **** **** **** **** **** ParaMonte **** **** Plain Powerful Parallel **** **** Monte Carlo Library **** **** **** **** Version 1.5.0 **** **** **** **** Build: Thu Dec 17 06:20:11 2020 **** **** **** **** Department of Physics **** **** Computational & Data Science Lab **** **** Data Science Program, College of Science **** **** The University of Texas at Arlington **** **** **** **** originally developed at **** **** **** **** Multiscale Modeling Group **** **** Center for Computational Oncology (CCO) **** **** Oden Institute for Computational Engineering and Sciences **** **** Department of Aerospace Engineering and Engineering Mechanics **** **** Department of Neurology, Dell-Seton Medical School **** **** Department of Biomedical Engineering **** **** The University of Texas at Austin **** **** **** **** For questions and further information, please contact: **** **** **** **** Amir Shahmoradi **** **** **** **** shahmoradi@utexas.edu **** **** amir.shahmoradi@uta.edu **** **** ashahmoradi@gmail.com **** **** **** **** cdslab.org/pm **** **** **** **** https://www.cdslab.org/paramonte/ **** **** **** **** **** ************************************************************************************************************************************ ************************************************************************************************************************************ ************************************************************************************************************************************ **** **** **** Setting up the ParaDRAM simulation environment **** **** **** ************************************************************************************************************************************ ParaDRAM - NOTE: Interfacing MATLAB with ParaDRAM... ParaDRAM - NOTE: Variable outputFileName detected among the input variables to ParaDRAM: ParaDRAM - NOTE: ./out/mvn_serial ParaDRAM - NOTE: ParaDRAM - NOTE: Absolute path to the current working directory: ParaDRAM - NOTE: D:\temp\libparamonte_MATLAB ParaDRAM - NOTE: ParaDRAM - NOTE: Generating the requested directory for the ParaDRAM output files: ParaDRAM - NOTE: .\out\ ParaDRAM - NOTE: ParaDRAM - NOTE: ParaDRAM output files will be prefixed with: ParaDRAM - NOTE: .\out\mvn_serial ParaDRAM - NOTE: Searching for previous runs of ParaDRAM... ParaDRAM - NOTE: No pre-existing ParaDRAM run detected. ParaDRAM - NOTE: Starting a fresh ParaDRAM run... ParaDRAM - NOTE: Generating the output report file: ParaDRAM - NOTE: .\out\mvn_serial_process_1_report.txt ParaDRAM - NOTE: Running the simulation in serial on 1 process. ParaDRAM - NOTE: Please see the output report and progress files for further realtime simulation details. Accepted/Total Func. Call Dynamic/Overall Acc. Rate Elapsed/Remained Time [s] ========================= ========================= ========================= 89 / 999 0.0884 / 0.0885 0.0860 / 48.2286 228 / 1999 0.1338 / 0.1112 0.1270 / 27.7239 394 / 2999 0.1618 / 0.1281 0.1740 / 21.9072 574 / 3999 0.1800 / 0.1410 0.2190 / 18.8577 784 / 4999 0.2134 / 0.1555 0.2610 / 16.3844 979 / 5999 0.2019 / 0.1633 0.3040 / 15.2221 1226 / 6999 0.2412 / 0.1744 0.3500 / 13.9241 1442 / 7999 0.2191 / 0.1800 0.3880 / 13.0655 1671 / 8999 0.2320 / 0.1858 0.4320 / 12.4944 1909 / 9999 0.2509 / 0.1923 0.4750 / 11.9661 2170 / 10999 0.2605 / 0.1985 0.5180 / 11.4175 2423 / 11999 0.2614 / 0.2037 0.5600 / 10.9959 2690 / 12999 0.2685 / 0.2087 0.6100 / 10.7283 2989 / 13999 0.2834 / 0.2140 0.6570 / 10.3333 3284 / 14999 0.2977 / 0.2196 0.7000 / 9.9577 3571 / 15999 0.2643 / 0.2224 0.7470 / 9.7123 3850 / 16999 0.2796 / 0.2258 0.7850 / 9.4098 4120 / 17999 0.2704 / 0.2283 0.8220 / 9.1537 4429 / 18999 0.3000 / 0.2320 0.8660 / 8.9105 4719 / 19999 0.2847 / 0.2347 0.9080 / 8.7127 5012 / 20999 0.2906 / 0.2373 0.9470 / 8.5003 5276 / 21999 0.2793 / 0.2392 1.0000 / 8.4769 5570 / 22999 0.2888 / 0.2414 1.0370 / 8.2718 5850 / 23999 0.2890 / 0.2434 1.0770 / 8.1281 6119 / 24999 0.2757 / 0.2447 1.1250 / 8.0677 6384 / 25999 0.2788 / 0.2460 1.1700 / 7.9935 6693 / 26999 0.3042 / 0.2481 1.2170 / 7.8746 6993 / 27999 0.2936 / 0.2498 1.2560 / 7.7244 7296 / 28999 0.2939 / 0.2513 1.2940 / 7.5739 7629 / 29999 0.3288 / 0.2539 1.3340 / 7.4090 7940 / 30999 0.3063 / 0.2556 1.3820 / 7.3208 8276 / 31999 0.3233 / 0.2577 1.4200 / 7.1590 8549 / 32999 0.2812 / 0.2584 1.4610 / 7.0839 8845 / 33999 0.2956 / 0.2595 1.5050 / 7.0026 9166 / 34999 0.3070 / 0.2608 1.5520 / 6.9141 9477 / 35999 0.3025 / 0.2620 1.5940 / 6.8158 9783 / 36999 0.3006 / 0.2630 1.6360 / 6.7254 10068 / 37999 0.3002 / 0.2640 1.6800 / 6.6633 10341 / 38999 0.2832 / 0.2645 1.7210 / 6.6002 10635 / 39999 0.3040 / 0.2655 1.7690 / 6.5479 10908 / 40999 0.2756 / 0.2657 1.8110 / 6.4902 11218 / 41999 0.3037 / 0.2666 1.8550 / 6.4130 11542 / 42999 0.3219 / 0.2679 1.8920 / 6.3042 11836 / 43999 0.2979 / 0.2686 1.9340 / 6.2360 12136 / 44999 0.3044 / 0.2694 1.9800 / 6.1775 12459 / 45999 0.3108 / 0.2703 2.0240 / 6.0986 12753 / 46999 0.3004 / 0.2709 2.0670 / 6.0370 13042 / 47999 0.3020 / 0.2716 2.1120 / 5.9849 13312 / 48999 0.2794 / 0.2718 2.1520 / 5.9309 13634 / 49999 0.3156 / 0.2726 2.1910 / 5.8441 13959 / 50999 0.3196 / 0.2735 2.2370 / 5.7758 14273 / 51999 0.3088 / 0.2742 2.2940 / 5.7422 14569 / 52999 0.2964 / 0.2746 2.3450 / 5.7029 14850 / 53999 0.2922 / 0.2750 2.3940 / 5.6666 15148 / 54999 0.3050 / 0.2755 2.4430 / 5.6208 15432 / 55999 0.2925 / 0.2758 2.4860 / 5.5687 15719 / 56999 0.2989 / 0.2762 2.5320 / 5.5219 16010 / 57999 0.3099 / 0.2768 2.5780 / 5.4732 16335 / 58999 0.3139 / 0.2774 2.6280 / 5.4161 16641 / 59999 0.3047 / 0.2779 2.6740 / 5.3604 16968 / 60999 0.3319 / 0.2788 2.7210 / 5.2970 17313 / 61999 0.3274 / 0.2796 2.7650 / 5.2203 17627 / 62999 0.3119 / 0.2801 2.8090 / 5.1589 17938 / 63999 0.3251 / 0.2808 2.8490 / 5.0922 18246 / 64999 0.3112 / 0.2812 2.8930 / 5.0348 18556 / 65999 0.3141 / 0.2817 2.9360 / 4.9752 18900 / 66999 0.3404 / 0.2826 2.9750 / 4.8954 19189 / 67999 0.2948 / 0.2828 3.0180 / 4.8459 19520 / 68999 0.3317 / 0.2835 3.0620 / 4.7812 19856 / 69999 0.3245 / 0.2841 3.1130 / 4.7259 20174 / 70999 0.3123 / 0.2845 3.1570 / 4.6674 20494 / 71999 0.3184 / 0.2850 3.2070 / 4.6172 20828 / 72999 0.3271 / 0.2855 3.2490 / 4.5506 21124 / 73999 0.3090 / 0.2859 3.2910 / 4.4987 21445 / 74999 0.3237 / 0.2864 3.3400 / 4.4474 21777 / 75999 0.3241 / 0.2869 3.3880 / 4.3908 22082 / 76999 0.3144 / 0.2872 3.4300 / 4.3365 22387 / 77999 0.3166 / 0.2876 3.4760 / 4.2874 22704 / 78999 0.3140 / 0.2879 3.5310 / 4.2452 23036 / 79999 0.3218 / 0.2883 3.5800 / 4.1904 23370 / 80999 0.3169 / 0.2887 3.6350 / 4.1421 23693 / 81999 0.3343 / 0.2893 3.6940 / 4.1016 24007 / 82999 0.3237 / 0.2897 3.7450 / 4.0548 24335 / 83999 0.3297 / 0.2901 3.7980 / 4.0056 24645 / 84999 0.3102 / 0.2904 3.8420 / 3.9527 24953 / 85999 0.3093 / 0.2906 3.8930 / 3.9077 25259 / 86999 0.3136 / 0.2909 3.9430 / 3.8621 25600 / 87999 0.3275 / 0.2913 4.0020 / 3.8144 25910 / 88999 0.3196 / 0.2916 4.0540 / 3.7692 26232 / 89999 0.3266 / 0.2920 4.1160 / 3.7294 26546 / 90999 0.3154 / 0.2922 4.1770 / 3.6905 26869 / 91999 0.3183 / 0.2925 4.2270 / 3.6389 27207 / 92999 0.3277 / 0.2929 4.2860 / 3.5906 27521 / 93999 0.3204 / 0.2932 4.3370 / 3.5424 27851 / 94999 0.3233 / 0.2935 4.3800 / 3.4833 28139 / 95999 0.2973 / 0.2936 4.4260 / 3.4385 28451 / 96999 0.3091 / 0.2937 4.4790 / 3.3924 28756 / 97999 0.3100 / 0.2939 4.5280 / 3.3451 29087 / 98999 0.3239 / 0.2942 4.5760 / 3.2901 29403 / 99999 0.3102 / 0.2943 4.6170 / 3.2342 29714 / 100999 0.3184 / 0.2946 4.6660 / 3.1855 30025 / 101999 0.3164 / 0.2948 4.7160 / 3.1375 30353 / 102999 0.3249 / 0.2951 4.7650 / 3.0843 30642 / 103999 0.3024 / 0.2952 4.8100 / 3.0387 30934 / 104999 0.3111 / 0.2953 4.8580 / 2.9942 31266 / 105999 0.3280 / 0.2956 4.9040 / 2.9384 31580 / 106999 0.3158 / 0.2958 4.9490 / 2.8867 31902 / 107999 0.3237 / 0.2961 4.9940 / 2.8331 32222 / 108999 0.3166 / 0.2963 5.0440 / 2.7830 32529 / 109999 0.3150 / 0.2964 5.0880 / 2.7327 32840 / 110999 0.3173 / 0.2966 5.1440 / 2.6879 33158 / 111999 0.3247 / 0.2969 5.1950 / 2.6387 33474 / 112999 0.3135 / 0.2970 5.2440 / 2.5889 33804 / 113999 0.3257 / 0.2973 5.2880 / 2.5336 34140 / 114999 0.3229 / 0.2975 5.3440 / 2.4826 34446 / 115999 0.3026 / 0.2975 5.3900 / 2.4338 34763 / 116999 0.3155 / 0.2977 5.4460 / 2.3870 35078 / 117999 0.3191 / 0.2979 5.4940 / 2.3371 35373 / 118999 0.3063 / 0.2979 5.5400 / 2.2908 35671 / 119999 0.3178 / 0.2981 5.5840 / 2.2431 35972 / 120999 0.3108 / 0.2982 5.6300 / 2.1955 36296 / 121999 0.3306 / 0.2985 5.6740 / 2.1423 36634 / 122999 0.3364 / 0.2988 5.7230 / 2.0880 36964 / 123999 0.3287 / 0.2990 5.7700 / 2.0349 37290 / 124999 0.3171 / 0.2992 5.8220 / 1.9844 37614 / 125999 0.3224 / 0.2994 5.8680 / 1.9323 37958 / 126999 0.3330 / 0.2996 5.9130 / 1.8759 38281 / 127999 0.3181 / 0.2998 5.9530 / 1.8224 38610 / 128999 0.3199 / 0.2999 5.9990 / 1.7697 38919 / 129999 0.3154 / 0.3000 6.0560 / 1.7243 39241 / 130999 0.3194 / 0.3002 6.1040 / 1.6736 39567 / 131999 0.3313 / 0.3004 6.1590 / 1.6240 39885 / 132999 0.3142 / 0.3005 6.2060 / 1.5739 40219 / 133999 0.3438 / 0.3008 6.2510 / 1.5202 40540 / 134999 0.3181 / 0.3010 6.3090 / 1.4722 40870 / 135999 0.3321 / 0.3012 6.3570 / 1.4201 41168 / 136999 0.3027 / 0.3012 6.4060 / 1.3743 41538 / 137999 0.3561 / 0.3016 6.4530 / 1.3146 41845 / 138999 0.3079 / 0.3017 6.4990 / 1.2666 42168 / 139999 0.3206 / 0.3018 6.5480 / 1.2162 42520 / 140999 0.3426 / 0.3021 6.6010 / 1.1612 42846 / 141999 0.3167 / 0.3022 6.6490 / 1.1102 43157 / 142999 0.3188 / 0.3023 6.7010 / 1.0625 43480 / 143999 0.3307 / 0.3025 6.7510 / 1.0123 43841 / 144999 0.3586 / 0.3029 6.8060 / 0.9561 44161 / 145999 0.3184 / 0.3030 6.8590 / 0.9069 44474 / 146999 0.3216 / 0.3031 6.9000 / 0.8573 44810 / 147999 0.3200 / 0.3032 6.9360 / 0.8033 45155 / 148999 0.3375 / 0.3035 6.9870 / 0.7497 45474 / 149999 0.3181 / 0.3036 7.0300 / 0.6997 45787 / 150999 0.3207 / 0.3037 7.0770 / 0.6512 46110 / 151999 0.3200 / 0.3038 7.1260 / 0.6012 46436 / 152999 0.3216 / 0.3039 7.1750 / 0.5507 46757 / 153999 0.3122 / 0.3040 7.2230 / 0.5010 47098 / 154999 0.3348 / 0.3042 7.2670 / 0.4478 47425 / 155999 0.3192 / 0.3042 7.3150 / 0.3972 47726 / 156999 0.3108 / 0.3043 7.3620 / 0.3508 48072 / 157999 0.3364 / 0.3045 7.4060 / 0.2970 48388 / 158999 0.3253 / 0.3046 7.4580 / 0.2485 48724 / 159999 0.3258 / 0.3048 7.5020 / 0.1965 49045 / 160999 0.3076 / 0.3048 7.5530 / 0.1471 49383 / 161999 0.3339 / 0.3050 7.5990 / 0.0949 49693 / 162999 0.3125 / 0.3050 7.6490 / 0.0473 50000 / 163943 0.3236 / 0.3051 7.6920 / 0.0000 ParaDRAM - NOTE: Computing the statistical properties of the Markov chain... ParaDRAM - NOTE: Computing the final decorrelated sample size... ParaDRAM - NOTE: Generating the output sample file: ParaDRAM - NOTE: .\out\mvn_serial_process_1_sample.txt ParaDRAM - NOTE: Computing the statistical properties of the final refined sample... ParaDRAM - NOTE: Mission Accomplished. ParaDRAM - NOTE: To read the generated output files, try the following: ParaDRAM - NOTE: ParaDRAM - NOTE: pmpd.readReport() % to read the summary report from the output report file. ParaDRAM - NOTE: pmpd.readSample() % to read the final i.i.d. sample from the output sample file. ParaDRAM - NOTE: pmpd.readChain() % to read the uniquely-accepted points from the output chain file. ParaDRAM - NOTE: pmpd.readMarkovChain() % to read the Markov Chain. NOT recommended for extremely-large chains. ParaDRAM - NOTE: pmpd.readRestart() % to read the contents of an ASCII-format output restart file. ParaDRAM - NOTE: pmpd.readProgress() % to read the contents of an output progress file. ParaDRAM - NOTE: ParaDRAM - NOTE: For more information and examples on the usage, visit: ParaDRAM - NOTE: ParaDRAM - NOTE: https://www.cdslab.org/paramonte

The simulation output files

================================
Once the simulation is finished, the ParaDRAM routine generates 5 output files, each of which contains information about certain aspects of the simulation,
outPath = fullfile(currentDir,"out");
outFileList = ["mvn_serial_process_1_report.txt", "mvn_serial_process_1_progress.txt", "mvn_serial_process_1_sample.txt", "mvn_serial_process_1_chain.txt", "mvn_serial_process_1_restart.txt"];
for file = outFileList(end:-1:1)
open(fullfile(outPath,file))
end

General Guidelines on the ParaMonte visualization tools

===================================================================
In the following sections, we will discuss some of the postprocessing and visualization tools that automatically ship with the ParaMonte library. However, this is just the tip of the iceberg. For more detailed instructions on how to use the individual visualization tools of the ParaMonte library, visist the following MATLAB live scripts,
line / scatter plots
density plots
other plots

Reading the simulation output sample file

==================================================
You may have noticed that, upon finishing the simulation, the sampler provides hints on how to postprocess the results. We can read the generated output sample, contained in the file suffixed with *_sample.txt via,
pmpd.readSample();
ParaDRAM - WARNING: The ParaDRAM input simulation specification `pmpd.spec.outputDelimiter` is not set. ParaDRAM - WARNING: This information is essential for successful reading of the requested sample file(s). ParaDRAM - WARNING: Proceeding with the default assumption of comma-delimited sample file contents... ParaDRAM - NOTE: 1 files detected matching the pattern: "D:\temp\libparamonte_MATLAB\out\mvn_serial*" ParaDRAM - NOTE: processing file: "D:\temp\libparamonte_MATLAB\out\mvn_serial_process_1_sample.txt" ParaDRAM - NOTE: reading the file contents... ParaDRAM - NOTE: done in 1.645700 seconds. ParaDRAM - NOTE: ndim = 4, count = 11869 ParaDRAM - NOTE: computing the sample correlation matrix... ParaDRAM - NOTE: creating the heatmap plot object from scratch... ParaDRAM - NOTE: done in 1.126500 seconds. ParaDRAM - NOTE: computing the sample covariance matrix... ParaDRAM - NOTE: creating the heatmap plot object from scratch... ParaDRAM - NOTE: done in 0.219380 seconds. ParaDRAM - NOTE: computing the sample autocorrelation... ParaDRAM - NOTE: creating the line plot object from scratch... ParaDRAM - NOTE: creating the scatter plot object from scratch... ParaDRAM - NOTE: creating the lineScatter plot object from scratch... ParaDRAM - NOTE: done in 1.283500 seconds. ParaDRAM - NOTE: adding the graphics tools... ParaDRAM - NOTE: creating the line plot object from scratch... ParaDRAM - NOTE: creating the scatter plot object from scratch... ParaDRAM - NOTE: creating the lineScatter plot object from scratch... ParaDRAM - NOTE: creating the line3 plot object from scratch... ParaDRAM - NOTE: creating the scatter3 plot object from scratch... ParaDRAM - NOTE: creating the lineScatter3 plot object from scratch... ParaDRAM - NOTE: creating the histogram plot object from scratch... ParaDRAM - NOTE: creating the histogram2 plot object from scratch... ParaDRAM - NOTE: creating the histfit plot object from scratch... ParaDRAM - NOTE: creating the contour plot object from scratch... ParaDRAM - NOTE: creating the contourf plot object from scratch... ParaDRAM - NOTE: creating the contour3 plot object from scratch... ParaDRAM - NOTE: creating the grid plot object from scratch... ParaDRAM - NOTE: The processed sample files are now stored in the newly-created component "pmpd.sampleList" of the ParaDRAM - NOTE: ParaDRAM object as a cell array. For example, to access the contents of the first (or the only) sample ParaDRAM - NOTE: file, try: ParaDRAM - NOTE: ParaDRAM - NOTE: pmpd.sampleList{1}.df ParaDRAM - NOTE: ParaDRAM - NOTE: To access the plotting tools, try: ParaDRAM - NOTE: ParaDRAM - NOTE: pmpd.sampleList{1}.plot.<PRESS TAB TO SEE THE LIST OF PLOTS> ParaDRAM - NOTE: ParaDRAM - NOTE: For example, ParaDRAM - NOTE: ParaDRAM - NOTE: pmpd.sampleList{1}.plot.line.make() % to make 2D line plots. ParaDRAM - NOTE: pmpd.sampleList{1}.plot.scatter.make() % to make 2D scatter plots. ParaDRAM - NOTE: pmpd.sampleList{1}.plot.lineScatter.make() % to make 2D line-scatter plots. ParaDRAM - NOTE: pmpd.sampleList{1}.plot.line3.make() % to make 3D line plots. ParaDRAM - NOTE: pmpd.sampleList{1}.plot.scatter3.make() % to make 3D scatter plots. ParaDRAM - NOTE: pmpd.sampleList{1}.plot.lineScatter3.make() % to make 3D line-scatter plots. ParaDRAM - NOTE: pmpd.sampleList{1}.plot.contour3.make() % to make 3D kernel-density contour plots. ParaDRAM - NOTE: pmpd.sampleList{1}.plot.contourf.make() % to make 2D kernel-density filled-contour plots. ParaDRAM - NOTE: pmpd.sampleList{1}.plot.contour.make() % to make 2D kernel-density plots. ParaDRAM - NOTE: pmpd.sampleList{1}.plot.histogram2.make() % to make 2D histograms. ParaDRAM - NOTE: pmpd.sampleList{1}.plot.histogram.make() % to make 1D histograms. ParaDRAM - NOTE: pmpd.sampleList{1}.plot.grid.make() % to make GridPlot ParaDRAM - NOTE: ParaDRAM - NOTE: To plot or inspect the variable autocorrelations or the correlation/covariance matrices, try: ParaDRAM - NOTE: ParaDRAM - NOTE: pmpd.sampleList{1}.stats.<PRESS TAB TO SEE THE LIST OF COMPONENTS> ParaDRAM - NOTE: ParaDRAM - NOTE: For more information and examples on the usage, visit: ParaDRAM - NOTE: ParaDRAM - NOTE: https://www.cdslab.org/paramonte
sample = pmpd.sampleList{1};
By default, the ParaDRAM sampler generates a highly refined decorrelated final sample, essentially refining the Markov chain for as long as there is any residual auto-correlation in any of the individual variables of the Markov chain that has been sampled. This is an extremely strong and conservative refinement strategy (and it is so for a good reason: to ensure independent and identically distributed (i.i.d.) samples from the objective function). However, this extreme refinement can be mitigated and controlled by the setting the following ParaDRAM simulation specification variable prior to the simulation run,
pmpd.spec.sampleRefinementCount = 1; % refine each of the compact and verbose (Markov) chains only once.
Rerun the simulation with this specification set and you will notice an increase in the final sample size by a few factors. Note that the above specification has to be set before running the simulation in the above, if you really want to use it.

Visualizing the refined sample

To quickly visualize the generated sample as a histogram, try,
sample.plot.histogram.make()
To plot all of the sampled variables, try,
sample.plot.histogram.reset(); % reset the plot properties to the default
ParaDRAM - NOTE: resetting the properties of the histogram plot...
sample.df.Properties.VariableNames
ans = 1×5 cell array {'SampleLogFunc'} {'SampleVariable1'} {'SampleVariable2'} {'SampleVariable3'} {'SampleVariable4'}
sample.plot.histogram
ans =
DensityPlot with properties: xcolumns: "SampleVariable1" dfref: [11869×5 table] figure: [1×1 struct] currentFig: [1×1 struct] rows: {} axes: [1×1 struct] histogram: [1×1 struct] target: [1×1 Target_class] legend: [1×1 struct]
sample.plot.histogram.xcolumns = sample.df.Properties.VariableNames(2:end);
sample.plot.histogram.legend.kws.location = "northeast";
sample.plot.histogram.legend.enabled = true;
sample.plot.histogram.make();
Or, we could also used the column indices of the variabels, instead of the column names,
sample.plot.histogram.reset() % reset the plot properties to the default
ParaDRAM - NOTE: resetting the properties of the histogram plot...
sample.plot.histogram.legend.enabled = false; % let's also remove the legends
sample.plot.histogram.make("xcolumns",[2,3,4,5]); % the column indices of all sampled variables in the output sample file.
We can also rebuild the histogram object from scratch, which includes reading again the input data used in the plotting from the dataFrame, by specifying the input parameter "hard",
sample.plot.histogram.reset("hard")
ParaDRAM - NOTE: creating the histogram plot object from scratch...
Make a trace plot of the refined sample,
sample.plot.line.reset();
ParaDRAM - NOTE: resetting the properties of the line plot...
sample.plot.line.colormap.values = "autumn"; % let's request autumn color-mapping
sample.plot.line.make();
We can simply take the axis logarithmic scale,
sample.plot.line.axes.kws.xscale = "log";
sample.plot.line.make();
or, we could do it via,
set(gca,'xscale','log','yscale','linear');
We can also include more variables in a single trace plot, for example, the the first, second, and the fourth dimensions of the objective function,
sample.plot.line.reset(); % reset all settings including colormap to the default values.
ParaDRAM - NOTE: resetting the properties of the line plot...
sample.plot.line.make("ycolumns",[2,3,5]); % these are the column numbers in the dataFrame sample.df
set(gca,'xscale','log','yscale','linear');
By default, the color of the line in the trace-plot will represent the value returned by getLogFunc() at the given sampled point.
sample.plot.line.ccolumns
ans = "SampleLogFunc"
To turn the color mapping off, you can instead try,
sample.plot.line.reset(); % reset to the default settings
ParaDRAM - NOTE: resetting the properties of the line plot...
sample.plot.line.colormap.enabled = false; % disable varying-color lines
sample.plot.line.legend.enabled = true; % display legend
sample.plot.line.legend.kws.location = "best";
sample.plot.line.make("ycolumns",3:5); % these are the column numbers in the dataFrame sample.df
set(gca,'xscale','log','yscale','linear');
We can also change the properties of the lines as we wish,
sample.plot.line.reset();
ParaDRAM - NOTE: resetting the properties of the line plot...
sample.plot.line.colormap.enabled = false;
sample.plot.line.legend.enabled = true; % display legend
sample.plot.line.plot.kws.linewidth = 1.0;
sample.plot.line.plot.kws.linestyle = ":"; % we can add any new proprty to plot_kws, that is an input argument to MATLAB's plot().
sample.plot.line.make("ycolumns",["SampleLogFunc",3:5]); % we can mix column names with column numbers
set(gca,'xscale','log','yscale','linear');
To make a scatter trace-plot of the sampled points, try,
sample.plot.scatter.make();