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. More...

Inheritance diagram for Paradram:

[legend]

Collaboration diagram for Paradram:

[legend]

Public Member Functions
function	Paradram ()
	Generate and return an instance of the serial and parallel Delayed-Rejection Adaptive Metropolis-Hastings Markov Chain Monte Carlo sampler of the ParaMonte MATLAB library. More...

function	readChainMarkov (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	run (in self, in getLogFunc, in ndim)
	Run the ParaDRAM sampler and return nothing. More...

Detailed Description

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.

Note: See the documentation of the class constructor for usage interface and examples.

Final Remarks ⛓

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

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

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

Copyright: Computational Data Science Lab

Author:: Amir Shahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin

Definition at line 13 of file Paradram.m.

Constructor & Destructor Documentation

◆ Paradram()

function Paradram::Paradram ( )

Generate and return an instance of the serial and parallel Delayed-Rejection Adaptive Metropolis-Hastings Markov Chain Monte Carlo sampler of the ParaMonte MATLAB library.

This function is the constructor of the pm.sampling.Paradram sampler class.
Once you assign the desired simulation specifications to the corresponding attributes within the component spec of an object of class pm.sampling.Paradram, call the ParaDRAM sampler via the object method pm.sampling.Paradram.run().

While the constructor of this class does not take any input arguments, all ParaDRAM simulation specifications can be set after creating the object.

Returns: sampler : The output scalar object of class pm.sampling.Paradram.

Possible calling interfaces ⛓

: sampler = pm.sampling.Paradram();

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.
These situations scarcely happen.

Note: On Windows systems, when restarting an old interrupted ParaDRAM simulation, ensure your MATLAB session is also restarted before the simulation restart.
This may be needed as Windows frequently locks access to some or all simulation output files.; To unset an already-set input simulation specification, simply set the simulation attribute to empty double [] or re-instantiate an object of class pm.sampling.Paradram.run().

See also: ParaDRAM simulation specifications listing
ParaDRAM simulation restart functionality
ParaDRAM simulation output files

ParaDRAM Simulation Specifications

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

The best way to learn about individual ParaDRAM simulation attributes is to a run a minimal serial simulation as given in the above.
You can also use the sampler.spec.doc() method:

sampler = pm.sampling.Paradram();

sampler.spec.doc()

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.
Copy and paste the following code into your MATLAB session:

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.sampleLogFuncColIndex + 1 : sample.sampleLogFuncColIndex + 4, "colc", "sampleLogFunc");

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.

Running this code will generate a set of simulation output files (in the current working directory of MATLAB).
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.

Example Usage: Thread-Parallel

First, ensure the ParaMonte +pm package (i.e., folder) is available in your MATLAB paths.

Threading parallelism is possible as of ParaMonte MATLAB version 3.0.0.
However, only singleChain ParaDRAM simulations are supported.

Here is a MATLAB script main.m for a thread-parallel ParaDRAM simulation.
Copy and paste the following code and paste into your MATLAB session:

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)

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.

Running this code will generate a set of simulation output files (in the current working directory of MATLAB).
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.

Specifying 0 as the number of threads will lead to using all available CPU threads for thread-parallel ParaDRAM simulation.

Note: Benefits of thread-parallelism
Thread-parallel simulations offer a much more flexible and easier approach to benefiting from parallelism without going through the hassle of MPI-parallel simulations.
But they can still potentially offer much faster speed than serial simulations.
The actual speedup depends on a lot of factors.
Moreover, the number of threads is limited to maximum number of physical cores available on your system.
As such, thread-parallel simulations are not scalable.
If you need scalability, checkout MPI-parallelism below.

Example Usage: MPI-Parallel

First, ensure the ParaMonte +pm package (i.e., folder) is available in your MATLAB paths.

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.

Ensure you need and will get a speedup by running the an MPI-parallel simulation.
Typically, your simulation may then benefit from parallelism only if a single evaluation of the objective function takes longer than a few milliseconds.
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).
On the MATLAB command line type the following,

pm.lib.verify();

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.
Once the MPI installation is verified, copy and paste the following code into your MATLAB session:
fid = fopen("main_mpi.m", "w");

sourceCode = ...

"sampler = pm.sampling.Paradram();" + newline + ...

"sampler.mpiname = pm.lib.mpi.choice();" + 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);
This will generate a main_mpi.m MATLAB script file in the current working directory of your MATLAB session.
Now, you can execute this MATLAB script file (main_mpi.m) in parallel.
To do so, you need to call MATLAB on a command-line, out of MATLAB GUI.
1. On Windows:
  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,
  mpiexec -localonly -n 3 matlab -batch "main_mpi"
  
  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.
  This flag runs the parallel code only on one node, but in doing so, it avoids the use of Hydra service and its registration.
  If you are not on a Windows cluster, (e.g., you are using your personal device), then we recommend specifying this flag.
2. On macOS/Linux:
  From within a Bash terminal that recognizes both MATLAB and mpiexec, type the following,
  mpiexec -n 3 matlab -batch "main_mpi"
  
  Note
  In both cases in the above, the script main_mpi.m will run on 3 processors.
  Feel free to change the number of processors to any number desired.
  But do not request more than the available number of physical cores on your system.

Warning: Do not add postprocessing codes (such as reading and plotting the output samples) in your MPI-parallel code.
There is no point in doing so, since MATLAB will run in -batch mode for parallel simulations, disabling all plotting capabilities.
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.
Only perform the sampling as described above in MPI-parallel mode.

Example usage ⛓

: 1cd(fileparts(mfilename('fullpath'))); % Change working directory to source code directory.

2addpath('../../../../'); % Add the ParaMonte library root directory to the search path.

3

4sampler = pm.sampling.Paradram();

5sampler.spec.outputStatus = "retry";

6sampler.spec.proposalStart = [-5, 5];

7sampler.spec.outputFileName = "himmelblau";

8sampler.spec.randomSeed = 28457353; % make sampling reproducible.

9sampler.spec.outputChainSize = 30000; % Use a small chain size for illustration.

10sampler.spec.parallelismNumThread = []; % Use these many parallel threads.

11sampler.spec.outputRestartFileFormat = "ascii";

12sampler.silent = true;

13sampler.run ( @(x) pm.stats.dist.himmelblau.getLogUDF(x(1), x(2)) ...

14 , 2 ...

15 );

16

17chain = sampler.readChain();

18chain = chain{1};

19p = pm.vis.PlotScatter(chain.df, "coly", "proposalAdaptation");

20p.make("axes", {"yscale", "log"});

21p.savefig("Paradram.himmelblau.proposalAdaptation.png", "-m3");

22

23p = pm.vis.PlotLineScatter(chain.df, "colx", chain.sampleLogFuncColIndex + 1, "coly", chain.sampleLogFuncColIndex + 2);

24p.make("colc", "sampleLogFunc");

25p.savefig("Paradram.himmelblau.domain.png", "-m3");

26

27p = pm.vis.TileLine(chain.df, "tileshape", [2, 1]);

28p.make("coly", chain.sampleLogFuncColIndex + [1 : 2], "colc", "sampleLogFunc");

29p.savefig("Paradram.himmelblau.traceplot.png", "-m3");

30

31restart = sampler.readRestart();

32restart = restart{1};

33

34p = pm.vis.PlotEllipse3(restart.proposalCov, restart.proposalMean, transpose(restart.uniqueStateVisitCount));

35p.make("axes", {"zscale", "log"});

36p.savefig("Paradram.himmelblau.proposalCov.png", "-m3");

parallel
function parallel()
Return a scalar MATLAB logical that is true if and only if the current installation of MATLAB contain...

root
function root()
Return a scalar MATLAB string containing the root directory of the ParaMonte library package.

Example output ⛓
1 ParaDRAM - NOTE: Setting up the MATLAB programming language environment for a ParaDRAM simulation...

2 ParaDRAM - NOTE:

3 ParaDRAM - NOTE: The user-specified internal input file for ParaDRAM specifications detected.

4 ParaDRAM - NOTE: All ParaDRAM simulation specifications will be read from the specified internal namelist file...

5

6 ParaDRAM - NOTE: Variable `outputFileName` detected among the user-supplied specifications of the ParaDRAM sampler:

7 ParaDRAM - NOTE: "himmelblau"

8 ParaDRAM - NOTE:

9 ParaDRAM - NOTE: Path to the current working directory:

10 ParaDRAM - NOTE: "/home/amir/git/paramonte/external/paramonted/doxygen/bld/linux/amd64/gnu/13.1.0/native/lib/mem/serial/matlab/checking/pkg/example/sampling/Paradram/himmelblau"

11 ParaDRAM - NOTE:

12 ParaDRAM - NOTE: Generating the requested directory for the ParaDRAM simulation output files:

13 ParaDRAM - NOTE: "/home/amir/git/paramonte/external/paramonted/doxygen/bld/linux/amd64/gnu/13.1.0/native/lib/mem/serial/matlab/checking/pkg/example/sampling/Paradram/himmelblau"

14 ParaDRAM - NOTE:

15 ParaDRAM - NOTE: 1 count of preexisting complete simulation runs with the same name prefix were detected.

16 ParaDRAM - NOTE:

17 ParaDRAM - NOTE: The last complete simulation run #1 will be overwritten as requested.

18 ParaDRAM - NOTE: Starting a fresh simulation run #1...

19 ParaDRAM - NOTE:

20 ParaDRAM - NOTE: Running the simulation in serial on 1 process...

21 ParaDRAM - NOTE:

22 ParaDRAM - NOTE: Generating the new output report file:

23 ParaDRAM - NOTE:

24 ParaDRAM - NOTE: "/home/amir/git/paramonte/external/paramonted/doxygen/bld/linux/amd64/gnu/13.1.0/native/lib/mem/serial/matlab/checking/pkg/example/sampling/Paradram/himmelblau/himmelblau_run1_pid1_report.txt"

25 ParaDRAM - NOTE:

26 ParaDRAM - NOTE: Please see the output *_pid1_report.txt and *_pid1_progress.txt files for further realtime simulation details...

27

28 Accepted/Total Func. Call Dynamic/Overall Acc. Rate Elapsed/Remained Time [s]

29 ========================= ========================= =========================

30

31 356 / 1000 0.3560 / 0.3560 0.0101 / 0.8409

32 635 / 2000 0.2790 / 0.3175 0.0145 / 0.6728

33 899 / 3000 0.2640 / 0.2997 0.0188 / 0.6097

34 1167 / 4000 0.2680 / 0.2918 0.0232 / 0.5735

35 1469 / 5000 0.3020 / 0.2938 0.0276 / 0.5365

36 1796 / 6000 0.3270 / 0.2993 0.0320 / 0.5025

37 2060 / 7000 0.2640 / 0.2943 0.0361 / 0.4899

38 2308 / 8000 0.2480 / 0.2885 0.0406 / 0.4865

39 2586 / 9000 0.2780 / 0.2873 0.0448 / 0.4753

40 2859 / 10000 0.2730 / 0.2859 0.0490 / 0.4647

41 3051 / 11000 0.1920 / 0.2774 0.0533 / 0.4712

42 3338 / 12000 0.2870 / 0.2782 0.0575 / 0.4594

43 3654 / 13000 0.3160 / 0.2811 0.0619 / 0.4465

44 3900 / 14000 0.2460 / 0.2786 0.0660 / 0.4416

45 4157 / 15000 0.2570 / 0.2771 0.0708 / 0.4404

46 4422 / 16000 0.2650 / 0.2764 0.0751 / 0.4342

47 4608 / 17000 0.1860 / 0.2711 0.0790 / 0.4354

48 4859 / 18000 0.2510 / 0.2699 0.0832 / 0.4304

49 5118 / 19000 0.2590 / 0.2694 0.0904 / 0.4393

50 5395 / 20000 0.2770 / 0.2697 0.0948 / 0.4322

51 5621 / 21000 0.2260 / 0.2677 0.0990 / 0.4294

52 5826 / 22000 0.2050 / 0.2648 0.1043 / 0.4327

53 6104 / 23000 0.2780 / 0.2654 0.1085 / 0.4248

54 6346 / 24000 0.2420 / 0.2644 0.1127 / 0.4201

55 6600 / 25000 0.2540 / 0.2640 0.1170 / 0.4149

56 6799 / 26000 0.1990 / 0.2615 0.1211 / 0.4132

57 7059 / 27000 0.2600 / 0.2614 0.1254 / 0.4075

58 7346 / 28000 0.2870 / 0.2624 0.1296 / 0.3996

59 7571 / 29000 0.2250 / 0.2611 0.1338 / 0.3963

60 7869 / 30000 0.2980 / 0.2623 0.1380 / 0.3880

61 8168 / 31000 0.2990 / 0.2635 0.1422 / 0.3800

62 8421 / 32000 0.2530 / 0.2632 0.1462 / 0.3747

63 8751 / 33000 0.3300 / 0.2652 0.1506 / 0.3657

64 8970 / 34000 0.2190 / 0.2638 0.1546 / 0.3625

65 9225 / 35000 0.2550 / 0.2636 0.1586 / 0.3573

66 9403 / 36000 0.1780 / 0.2612 0.1627 / 0.3564

67 9604 / 37000 0.2010 / 0.2596 0.1668 / 0.3542

68 9799 / 38000 0.1950 / 0.2579 0.1708 / 0.3520

69 9993 / 39000 0.1940 / 0.2562 0.1747 / 0.3498

70 10186 / 40000 0.1930 / 0.2546 0.1788 / 0.3478

71 10454 / 41000 0.2680 / 0.2550 0.1829 / 0.3420

72 10701 / 42000 0.2470 / 0.2548 0.1870 / 0.3372

73 10965 / 43000 0.2640 / 0.2550 0.1911 / 0.3317

74 11197 / 44000 0.2320 / 0.2545 0.1953 / 0.3280

75 11390 / 45000 0.1930 / 0.2531 0.2003 / 0.3273

76 11642 / 46000 0.2520 / 0.2531 0.2045 / 0.3224

77 11838 / 47000 0.1960 / 0.2519 0.2084 / 0.3197

78 12067 / 48000 0.2290 / 0.2514 0.2124 / 0.3157

79 12340 / 49000 0.2730 / 0.2518 0.2168 / 0.3103

80 12582 / 50000 0.2420 / 0.2516 0.2209 / 0.3058

81 12855 / 51000 0.2730 / 0.2521 0.2251 / 0.3003

82 13126 / 52000 0.2710 / 0.2524 0.2296 / 0.2951

83 13245 / 53000 0.1190 / 0.2499 0.2335 / 0.2954

84 13426 / 54000 0.1810 / 0.2486 0.2374 / 0.2930

85 13655 / 55000 0.2290 / 0.2483 0.2414 / 0.2890

86 13888 / 56000 0.2330 / 0.2480 0.2455 / 0.2848

87 14100 / 57000 0.2120 / 0.2474 0.2495 / 0.2813

88 14340 / 58000 0.2400 / 0.2472 0.2536 / 0.2769

89 14515 / 59000 0.1750 / 0.2460 0.2575 / 0.2747

90 14686 / 60000 0.1710 / 0.2448 0.2616 / 0.2727

91 15024 / 61000 0.3380 / 0.2463 0.2660 / 0.2651

92 15313 / 62000 0.2890 / 0.2470 0.2701 / 0.2591

93 15602 / 63000 0.2890 / 0.2477 0.2743 / 0.2532

94 15849 / 64000 0.2470 / 0.2476 0.2784 / 0.2486

95 16136 / 65000 0.2870 / 0.2482 0.2826 / 0.2428

96 16405 / 66000 0.2690 / 0.2486 0.2869 / 0.2377

97 16644 / 67000 0.2390 / 0.2484 0.2913 / 0.2337

98 16862 / 68000 0.2180 / 0.2480 0.2953 / 0.2301

99 17155 / 69000 0.2930 / 0.2486 0.2998 / 0.2245

100 17387 / 70000 0.2320 / 0.2484 0.3039 / 0.2204

101 17657 / 71000 0.2700 / 0.2487 0.3080 / 0.2153

102 17935 / 72000 0.2780 / 0.2491 0.3123 / 0.2101

103 18230 / 73000 0.2950 / 0.2497 0.3167 / 0.2045

104 18508 / 74000 0.2780 / 0.2501 0.3210 / 0.1993

105 18703 / 75000 0.1950 / 0.2494 0.3252 / 0.1964

106 18977 / 76000 0.2740 / 0.2497 0.3295 / 0.1914

107 19277 / 77000 0.3000 / 0.2504 0.3347 / 0.1862

108 19533 / 78000 0.2560 / 0.2504 0.3388 / 0.1815

109 19640 / 79000 0.1070 / 0.2486 0.3426 / 0.1807

110 19874 / 80000 0.2340 / 0.2484 0.3466 / 0.1766

111 20150 / 81000 0.2760 / 0.2488 0.3509 / 0.1715

112 20417 / 82000 0.2670 / 0.2490 0.3550 / 0.1666

113 20670 / 83000 0.2530 / 0.2490 0.3591 / 0.1621

114 20976 / 84000 0.3060 / 0.2497 0.3633 / 0.1563

115 21213 / 85000 0.2370 / 0.2496 0.3678 / 0.1524

116 21553 / 86000 0.3400 / 0.2506 0.3721 / 0.1458

117 21785 / 87000 0.2320 / 0.2504 0.3762 / 0.1419

118 22023 / 88000 0.2380 / 0.2503 0.3802 / 0.1377

119 22326 / 89000 0.3030 / 0.2509 0.3845 / 0.1322

120 22507 / 90000 0.1810 / 0.2501 0.3883 / 0.1293

121 22769 / 91000 0.2620 / 0.2502 0.3924 / 0.1246

122 22951 / 92000 0.1820 / 0.2495 0.3963 / 0.1217

123 23283 / 93000 0.3320 / 0.2504 0.4011 / 0.1157

124 23582 / 94000 0.2990 / 0.2509 0.4053 / 0.1103

125 23763 / 95000 0.1810 / 0.2501 0.4092 / 0.1074

126 24022 / 96000 0.2590 / 0.2502 0.4133 / 0.1029

127 24271 / 97000 0.2490 / 0.2502 0.4177 / 0.0986

128 24485 / 98000 0.2140 / 0.2498 0.4218 / 0.0950

129 24679 / 99000 0.1940 / 0.2493 0.4257 / 0.0918

130 24989 / 100000 0.3100 / 0.2499 0.4310 / 0.0864

131 25203 / 101000 0.2140 / 0.2495 0.4354 / 0.0829

132 25435 / 102000 0.2320 / 0.2494 0.4394 / 0.0789

133 25665 / 103000 0.2300 / 0.2492 0.4435 / 0.0749

134 25880 / 104000 0.2150 / 0.2488 0.4475 / 0.0712

135 26120 / 105000 0.2400 / 0.2488 0.4515 / 0.0671

136 26397 / 106000 0.2770 / 0.2490 0.4556 / 0.0622

137 26720 / 107000 0.3230 / 0.2497 0.4598 / 0.0564

138 27034 / 108000 0.3140 / 0.2503 0.4643 / 0.0509

139 27269 / 109000 0.2350 / 0.2502 0.4686 / 0.0469

140 27541 / 110000 0.2720 / 0.2504 0.4727 / 0.0422

141 27819 / 111000 0.2780 / 0.2506 0.4771 / 0.0374

142 28077 / 112000 0.2580 / 0.2507 0.4820 / 0.0330

143 28297 / 113000 0.2200 / 0.2504 0.4860 / 0.0292

144 28539 / 114000 0.2420 / 0.2503 0.4900 / 0.0251

145 28800 / 115000 0.2610 / 0.2504 0.4946 / 0.0206

146 29039 / 116000 0.2390 / 0.2503 0.4986 / 0.0165

147 29196 / 117000 0.1570 / 0.2495 0.5025 / 0.0138

148 29427 / 118000 0.2310 / 0.2494 0.5065 / 0.0099

149 29683 / 119000 0.2560 / 0.2494 0.5108 / 0.0055

150 29993 / 120000 0.3100 / 0.2499 0.5150 / 0.0001

151 30000 / 120048 0.0070 / 0.2499 0.5153 / 0.0000

152

153

154 ParaDRAM - NOTE: Computing the statistical properties of the Markov chain...

155

156 ParaDRAM - NOTE: Computing the final refined i.i.d. sample size...

157

158 ParaDRAM - NOTE: Generating the output sample file:

159 ParaDRAM - NOTE: /home/amir/git/paramonte/external/paramonted/doxygen/bld/linux/amd64/gnu/13.1.0/native/lib/mem/serial/matlab/checking/pkg/example/sampling/Paradram/himmelblau/himmelblau_run1_pid1_sample.txt

160

161 ParaDRAM - NOTE: Computing the statistical properties of the final output sample...

162

163

164 ParaDRAM - NOTE: Mission Accomplished.

165

166| 50% ␈␈␈␈␈␈␈| 100% done in 0.053642 seconds.

name
function name(in vendor)
Return the MPI library name as used in naming the ParaMonte MATLAB shared libraries.

Paradram
This is the ParaDRAM class for generating instances of serial and parallel Delayed-Rejection Adaptive...
Definition: Paradram.m:14

Paradram::run
function run(in self, in getLogFunc, in ndim)
Run the ParaDRAM sampler and return nothing.

home
function home()
Return a MATLAB string containing the absolute path to the system home directory.

lib
function lib()
Return a scalar MATLAB string containing the path to the lib directory of the ParaMonte library packa...

Visualization of the example output ⛓

Final Remarks ⛓

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

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

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

Copyright: Computational Data Science Lab

Author:: Amir Shahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin

Member Function Documentation

◆ readChainMarkov()

function Paradram::readChainMarkov	(	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.

Parameters

[in]	self	: The input/output parent object of class pm.sampling.Paradram which is implicitly passed to this dynamic method (not by the user).
[in]	pattern	: See the documentation of the corresponding argument of the constructor of the method pm.sampling.Sampler.readChain. (optional, The default is set by pm.sampling.Sampler.readChain)
[in]	sep	: See the documentation of the corresponding argument of the constructor of the method pm.sampling.Sampler.readChain. (optional, The default is set by pm.sampling.Sampler.readChain)

Returns: chainMarkovList : The output cell array of objects of class pm.sampling.FileContentsChain, each of which corresponds to the contents of a unique chain file.
Try doc pm.sampling.FileContentsChain to see the documentation of the contents of the objects of the output list.

Possible calling interfaces ⛓

: sampler = pm.sampling.Paradram();

chainMarkovList = sampler.readChainMarkov();

chainMarkovList = sampler.readChainMarkov([]);

chainMarkovList = sampler.readChainMarkov(file);

chainMarkovList = sampler.readChainMarkov([], []);

chainMarkovList = sampler.readChainMarkov(file, []);

chainMarkovList = sampler.readChainMarkov(file, sep);

Warning: Avoid using this routine for very large compact chains.
Reading the full Markov chain of large-scale simulation problems can be extremely memory-intensive without any potential benefits.; This method is to be only used for post-processing of the output chain file(s) of an already finished simulation. It is NOT meant to be called by all processes in parallel mode, although it is possible.

Note: This routine is identical to pm.sampling.Sampler.readChain method, except for the fact that upon reading the output chain files, it will also convert the chain contents from the default efficient compact format stored in the file to the full verbose Markov chain format.

Example usage ⛓

: 1cd(fileparts(mfilename('fullpath'))); % Change working directory to source code directory.

2addpath('../../../../'); % Add the ParaMonte library root directory to the search path.

3

4sampler = pm.sampling.Paradram();

5sampler.spec.outputFileName = "./out/run";

6sampler.spec.outputChainSize = 3000;

7sampler.run ( @(x) -sum((x - [-5; 5]).^2) ...

8 , 2 ...

9 );

10chain = sampler.readChainMarkov();

11chain = chain{1};

12head(chain.df)

13

14p = pm.vis.PlotScatter(chain.df, "coly", "proposalAdaptation");

15p.make("axes", {"yscale", "log"});

16p.savefig("readChainMarkov.proposalAdaptation.png", "-m3");

17

18p = pm.vis.PlotLineScatter(chain.df, "colx", chain.sampleLogFuncColIndex + 1, "coly", chain.sampleLogFuncColIndex + 2);

19p.make("colc", "sampleLogFunc");

20p.savefig("readChainMarkov.domain.png", "-m3");

21

22p = pm.vis.TileLine(chain.df, "tileshape", [2, 1]);

23p.make("coly", chain.sampleLogFuncColIndex + [1 : 2], "colc", "sampleLogFunc");

24p.savefig("readChainMarkov.traceplot.png", "-m3");

PlotScatter
This is the PlotScatter class for generating instances of 2-dimensional Scatter Plot visualizations b...
Definition: PlotScatter.m:30

1 ParaDRAM - NOTE: Setting up the MATLAB programming language environment for a ParaDRAM simulation...

2 ParaDRAM - NOTE:

3 ParaDRAM - NOTE: The user-specified internal input file for ParaDRAM specifications detected.

4 ParaDRAM - NOTE: All ParaDRAM simulation specifications will be read from the specified internal namelist file...

5

6 ParaDRAM - NOTE: Variable `outputFileName` detected among the user-supplied specifications of the ParaDRAM sampler:

7 ParaDRAM - NOTE: "./out/run"

8 ParaDRAM - NOTE:

9 ParaDRAM - NOTE: Path to the current working directory:

10 ParaDRAM - NOTE: "/home/amir/git/paramonte/external/paramonted/doxygen/bld/linux/amd64/gnu/13.1.0/native/lib/mem/serial/matlab/checking/pkg/example/sampling/Paradram/readChainMarkov"

11 ParaDRAM - NOTE:

12 ParaDRAM - NOTE: Generating the requested directory for the ParaDRAM simulation output files:

13 ParaDRAM - NOTE: "/home/amir/git/paramonte/external/paramonted/doxygen/bld/linux/amd64/gnu/13.1.0/native/lib/mem/serial/matlab/checking/pkg/example/sampling/Paradram/readChainMarkov/./out/"

14 ParaDRAM - NOTE:

15 ParaDRAM - NOTE: 5 counts of preexisting complete simulation runs with the same name prefix were detected.

16 ParaDRAM - NOTE:

17 ParaDRAM - NOTE: Checking for simulation restart possibility...

18 ParaDRAM - NOTE:

19 ParaDRAM - NOTE: Starting a fresh simulation run #6 from the most recent completed simulation...

20 ParaDRAM - NOTE:

21 ParaDRAM - NOTE: Running the simulation in serial on 1 process...

22 ParaDRAM - NOTE:

23 ParaDRAM - NOTE: Generating the new output report file:

24 ParaDRAM - NOTE:

25 ParaDRAM - NOTE: "/home/amir/git/paramonte/external/paramonted/doxygen/bld/linux/amd64/gnu/13.1.0/native/lib/mem/serial/matlab/checking/pkg/example/sampling/Paradram/readChainMarkov/./out/run_run6_pid1_report.txt"

26 ParaDRAM - NOTE:

27 ParaDRAM - NOTE: Please see the output *_pid1_report.txt and *_pid1_progress.txt files for further realtime simulation details...

28

29 Accepted/Total Func. Call Dynamic/Overall Acc. Rate Elapsed/Remained Time [s]

30 ========================= ========================= =========================

31

32 587 / 1000 0.5870 / 0.5870 0.0066 / 0.0272

33 1137 / 2000 0.5500 / 0.5685 0.0122 / 0.0200

34 1688 / 3000 0.5510 / 0.5627 0.0187 / 0.0146

35 2258 / 4000 0.5700 / 0.5645 0.0238 / 0.0078

36 2844 / 5000 0.5860 / 0.5688 0.0287 / 0.0016

37 3000 / 5260 0.1560 / 0.5703 0.0301 / 0.0000

38

39

40 ParaDRAM - NOTE: Computing the statistical properties of the Markov chain...

41

42 ParaDRAM - NOTE: Computing the final refined i.i.d. sample size...

43

44 ParaDRAM - NOTE: Generating the output sample file:

45 ParaDRAM - NOTE: /home/amir/git/paramonte/external/paramonted/doxygen/bld/linux/amd64/gnu/13.1.0/native/lib/mem/serial/matlab/checking/pkg/example/sampling/Paradram/readChainMarkov/./out/run_run6_pid1_sample.txt

46

47 ParaDRAM - NOTE: Computing the statistical properties of the final output sample...

48

49

50 ParaDRAM - NOTE: Mission Accomplished.

51

52

53Use the following object methods to read the generated basic output files:

54

55 sampler.readChain() % Return a list of the contents of the output chain file(s).

56 sampler.readSample() % Return a list of i.i.d. sample(s) from the output sample file(s).

57 sampler.readReport() % Return a list of summary report(s) from the output report file(s).

58 sampler.readRestart() % Return a list of the contents of the ASCII output restart file(s).

59 sampler.readProgress() % Return a list of the contents of the output progress file(s).

60

61For more information and examples on the usage, visit:

62

63 https://www.cdslab.org/paramonte

64

65

666 files were detected matching pattern: "./out/run"

67processing file: "/home/amir/git/paramonte/external/paramonted/doxygen/bld/linux/amd64/gnu/13.1.0/native/lib/mem/serial/matlab/checking/pkg/example/sampling/Paradram/readChainMarkov/out/run_run6_pid1_chain.txt"

68reading file: "/home/amir/git/paramonte/external/paramonted/doxygen/bld/linux/amd64/gnu/13.1.0/native/lib/mem/serial/matlab/checking/pkg/example/sampling/Paradram/readChainMarkov/out/run_run6_pid1_chain.txt"

69done in 0.024813 seconds.

70ncol = 9, nrow = 3000

71computing the sample correlation matrix...done in 0.027394 seconds.

72computing the sample covariance matrix...done in 0.022383 seconds.

73computing the sample autocorrelation...done in 0.022069 seconds.

74processing file: "/home/amir/git/paramonte/external/paramonted/doxygen/bld/linux/amd64/gnu/13.1.0/native/lib/mem/serial/matlab/checking/pkg/example/sampling/Paradram/readChainMarkov/out/run_run5_pid1_chain.txt"

75reading file: "/home/amir/git/paramonte/external/paramonted/doxygen/bld/linux/amd64/gnu/13.1.0/native/lib/mem/serial/matlab/checking/pkg/example/sampling/Paradram/readChainMarkov/out/run_run5_pid1_chain.txt"

76done in 0.026491 seconds.

77ncol = 9, nrow = 3000

78computing the sample correlation matrix...done in 0.010261 seconds.

79computing the sample covariance matrix...done in 0.003882 seconds.

80computing the sample autocorrelation...done in 0.005354 seconds.

81processing file: "/home/amir/git/paramonte/external/paramonted/doxygen/bld/linux/amd64/gnu/13.1.0/native/lib/mem/serial/matlab/checking/pkg/example/sampling/Paradram/readChainMarkov/out/run_run4_pid1_chain.txt"

82reading file: "/home/amir/git/paramonte/external/paramonted/doxygen/bld/linux/amd64/gnu/13.1.0/native/lib/mem/serial/matlab/checking/pkg/example/sampling/Paradram/readChainMarkov/out/run_run4_pid1_chain.txt"

83done in 0.018551 seconds.

84ncol = 9, nrow = 3000

85computing the sample correlation matrix...done in 0.004817 seconds.

86computing the sample covariance matrix...done in 0.002877 seconds.

87computing the sample autocorrelation...done in 0.003919 seconds.

88processing file: "/home/amir/git/paramonte/external/paramonted/doxygen/bld/linux/amd64/gnu/13.1.0/native/lib/mem/serial/matlab/checking/pkg/example/sampling/Paradram/readChainMarkov/out/run_run3_pid1_chain.txt"

89reading file: "/home/amir/git/paramonte/external/paramonted/doxygen/bld/linux/amd64/gnu/13.1.0/native/lib/mem/serial/matlab/checking/pkg/example/sampling/Paradram/readChainMarkov/out/run_run3_pid1_chain.txt"

90done in 0.042109 seconds.

91ncol = 9, nrow = 3000

92computing the sample correlation matrix...done in 0.008767 seconds.

93computing the sample covariance matrix...done in 0.002847 seconds.

94computing the sample autocorrelation...done in 0.002603 seconds.

95processing file: "/home/amir/git/paramonte/external/paramonted/doxygen/bld/linux/amd64/gnu/13.1.0/native/lib/mem/serial/matlab/checking/pkg/example/sampling/Paradram/readChainMarkov/out/run_run2_pid1_chain.txt"

96reading file: "/home/amir/git/paramonte/external/paramonted/doxygen/bld/linux/amd64/gnu/13.1.0/native/lib/mem/serial/matlab/checking/pkg/example/sampling/Paradram/readChainMarkov/out/run_run2_pid1_chain.txt"

97done in 0.015290 seconds.

98ncol = 9, nrow = 3000

99computing the sample correlation matrix...done in 0.008356 seconds.

100computing the sample covariance matrix...done in 0.005123 seconds.

101computing the sample autocorrelation...done in 0.006538 seconds.

102processing file: "/home/amir/git/paramonte/external/paramonted/doxygen/bld/linux/amd64/gnu/13.1.0/native/lib/mem/serial/matlab/checking/pkg/example/sampling/Paradram/readChainMarkov/out/run_run1_pid1_chain.txt"

103reading file: "/home/amir/git/paramonte/external/paramonted/doxygen/bld/linux/amd64/gnu/13.1.0/native/lib/mem/serial/matlab/checking/pkg/example/sampling/Paradram/readChainMarkov/out/run_run1_pid1_chain.txt"

104done in 0.013988 seconds.

105ncol = 9, nrow = 3000

106computing the sample correlation matrix...done in 0.002568 seconds.

107computing the sample covariance matrix...done in 0.000991 seconds.

108computing the sample autocorrelation...done in 0.001976 seconds.

109 processID delayedRejectionStage meanAcceptanceRate proposalAdaptation burninLocation sampleWeight sampleLogFunc sampleState1 sampleState2

110 _________ _____________________ __________________ __________________ ______________ ____________ _________________ ____________________ ___________________

111 1 0 0.250000009666267 0 1 1 -50 0 0

112 1 0 0.250000009666267 0 1 1 -50 0 0

113 1 0 0.250000009666267 0 1 1 -50 0 0

114 1 0 0.250000009666267 0 1 1 -50 0 0

115 1 0 0.342882473898846 0 1 1 -50.3362949891696 -0.32141397210834 -0.333584889057882

116 1 0 0.42093111931257 0.967499438460934 1 1 -50.2156223903078 -0.00626487809246379 -0.0277462070529085

117 1 0 0.42093111931257 0.967499438460934 1 1 -50.2156223903078 -0.00626487809246379 -0.0277462070529085

118 1 0 0.42093111931257 0.967499438460934 1 1 -50.2156223903078 -0.00626487809246379 -0.0277462070529085

119| 50% ␈␈␈␈␈␈␈| 100% done in 0.046262 seconds.

list
function list()
Return a list of MATLAB strings containing the names of OS platforms supported by the ParaMonte MATLA...

Paradram::readChainMarkov
function readChainMarkov(in self, in pattern, in sep)
Return a list of objects of class pm.sampling.FileContentsChain containing the content(s) of the Para...

Visualization of the example output ⛓

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:06 AM, University of Texas at Arlington
Amir Shahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin

◆ run()

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

Run the ParaDRAM sampler and return nothing.

For example usage, see the documentation of the parent class of this method pm.sampler.Paradram.

Parameters

[in,out]	self	: The input/output parent object of class pm.sampling.Paradram 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 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.Paradram();

sampler.run(getLogFunc, ndim);

Final Remarks ⛓

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

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

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

Copyright: Computational Data Science Lab

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

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

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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Paradram()

ParaDRAM Simulation Specifications

Example Usage: Serial

Example Usage: Thread-Parallel

Example Usage: MPI-Parallel

Member Function Documentation

◆ readChainMarkov()

◆ run()