Line data Source code
1 : !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2 : !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3 : !!!!
4 : !!!! MIT License
5 : !!!!
6 : !!!! ParaMonte: plain powerful parallel Monte Carlo library.
7 : !!!!
8 : !!!! Copyright (C) 2012-present, The Computational Data Science Lab
9 : !!!!
10 : !!!! This file is part of the ParaMonte library.
11 : !!!!
12 : !!!! Permission is hereby granted, free of charge, to any person obtaining a
13 : !!!! copy of this software and associated documentation files (the "Software"),
14 : !!!! to deal in the Software without restriction, including without limitation
15 : !!!! the rights to use, copy, modify, merge, publish, distribute, sublicense,
16 : !!!! and/or sell copies of the Software, and to permit persons to whom the
17 : !!!! Software is furnished to do so, subject to the following conditions:
18 : !!!!
19 : !!!! The above copyright notice and this permission notice shall be
20 : !!!! included in all copies or substantial portions of the Software.
21 : !!!!
22 : !!!! THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
23 : !!!! EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
24 : !!!! MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
25 : !!!! IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
26 : !!!! DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
27 : !!!! OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
28 : !!!! OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
29 : !!!!
30 : !!!! ACKNOWLEDGMENT
31 : !!!!
32 : !!!! ParaMonte is an honor-ware and its currency is acknowledgment and citations.
33 : !!!! As per the ParaMonte library license agreement terms, if you use any parts of
34 : !!!! this library for any purposes, kindly acknowledge the use of ParaMonte in your
35 : !!!! work (education/research/industry/development/...) by citing the ParaMonte
36 : !!!! library as described on this page:
37 : !!!!
38 : !!!! https://github.com/cdslaborg/paramonte/blob/main/ACKNOWLEDGMENT.md
39 : !!!!
40 : !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
41 : !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
42 :
43 : !> \brief
44 : !> This module contains the classes and procedures for setting up the `sampleRefinementMethod` attribute of samplers of class [ParaMCMC_type](@ref paramcmc_mod::paramcmc_type).
45 : !> For more information, see the description of this attribute in the body of the module.
46 : !> \author Amir Shahmoradi
47 :
48 : module SpecMCMC_SampleRefinementMethod_mod
49 :
50 : use Constants_mod, only: IK
51 : implicit none
52 :
53 : character(*), parameter :: MODULE_NAME = "@SpecMCMC_SampleRefinementMethod_mod"
54 :
55 : character(*), parameter :: BATCH_MEANS_METHOD_NAME = "BatchMeans"
56 : character(*), parameter :: CUTOFF_AUTOCORR_METHOD_NAME = "CutOffAutoCorr"
57 : character(*), parameter :: MAX_CUMSUM_AUTOCORR_METHOD_NAME = "MaxCumSumAutoCorr"
58 : integer(IK) , parameter :: LEN_BATCH_MEANS_METHOD_NAME = len(BATCH_MEANS_METHOD_NAME)
59 : integer(IK) , parameter :: LEN_CUTOFF_AUTOCORR_METHOD_NAME = len(CUTOFF_AUTOCORR_METHOD_NAME)
60 : integer(IK) , parameter :: LEN_MAX_CUMSUM_AUTOCORR_METHOD_NAME = len(MAX_CUMSUM_AUTOCORR_METHOD_NAME)
61 : integer(IK) , parameter :: MAX_LEN_SAMPLE_REFINEMENT_METHOD = 63
62 :
63 : character(MAX_LEN_SAMPLE_REFINEMENT_METHOD) :: sampleRefinementMethod ! namelist input
64 :
65 : type :: SampleRefinementMethod_type
66 : !logical :: isMaxCumSumAutoCorr
67 : !logical :: isViaCompactChain
68 : !logical :: isBatchMeans
69 : character(:), allocatable :: def
70 : character(:), allocatable :: val
71 : character(:), allocatable :: null
72 : character(:), allocatable :: desc
73 : contains
74 : procedure, pass :: set => setSampleRefinementMethod, checkForSanity, nullifyNameListVar
75 : end type SampleRefinementMethod_type
76 :
77 : interface SampleRefinementMethod_type
78 : module procedure :: constructSampleRefinementMethod
79 : end interface SampleRefinementMethod_type
80 :
81 : private :: constructSampleRefinementMethod, setSampleRefinementMethod, checkForSanity, nullifyNameListVar
82 :
83 : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
84 :
85 : contains
86 :
87 : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
88 :
89 349 : function constructSampleRefinementMethod(methodName) result(SampleRefinementMethodObj)
90 : #if INTEL_COMPILER_ENABLED && defined DLL_ENABLED && (OS_IS_WINDOWS || defined OS_IS_DARWIN)
91 : !DEC$ ATTRIBUTES DLLEXPORT :: constructSampleRefinementMethod
92 : #endif
93 : use Constants_mod, only: NULL_SK, IK
94 : use Decoration_mod, only: TAB
95 : use String_mod, only: num2str
96 : implicit none
97 : character(*), intent(in) :: methodName
98 : type(SampleRefinementMethod_type) :: SampleRefinementMethodObj
99 :
100 : !SampleRefinementMethodObj%isMaxCumSumAutoCorr = .false.
101 : !SampleRefinementMethodObj%isViaCompactChain = .false.
102 : !SampleRefinementMethodObj%isBatchMeans = .false.
103 349 : SampleRefinementMethodObj%def = BATCH_MEANS_METHOD_NAME
104 349 : SampleRefinementMethodObj%null = repeat(NULL_SK, MAX_LEN_SAMPLE_REFINEMENT_METHOD)
105 :
106 : SampleRefinementMethodObj%desc = &
107 : "sampleRefinementMethod is a string variable that represents the method of computing the Integrated Autocorrelation Time &
108 : &(IAC) to be used in "// methodName //" for refining the final output MCMC chain and sample. &
109 : &The string value must be enclosed by either single or double quotation marks when provided as input. &
110 : &Options that are currently supported include:\n\n&
111 : & sampleRefinementMethod = '" // BATCH_MEANS_METHOD_NAME // "'\n\n&
112 : & This method of computing the Integrated Autocorrelation Time is based on the approach described in &
113 : &SCHMEISER, B., 1982, Batch size effects in the analysis of simulation output, Oper. Res. 30 556-568. The &
114 : &batch sizes in the BatchMeans method are chosen to be int(N^(2/3)) where N is the length of the MCMC chain. &
115 : &As long as the batch size is larger than the IAC of the chain and there are significantly more than 10 &
116 : &batches, the BatchMeans method will provide reliable estimates of the IAC. &
117 : &Note that the refinement strategy involves two separate phases of sample decorrelation. At the first stage, &
118 : &the Markov chain is decorrelated recursively (for as long as needed) based on the IAC of its compact format, &
119 : &where only the the uniquely-visited states are kept in the (compact) chain. Once the Markov chain is refined &
120 : &such that its compact format is fully decorrelated, the second phase of the decorrelation begins during which &
121 : &the Markov chain is decorrelated based on the IAC of the chain in its verbose (Markov) format. This process &
122 : &is repeated recursively for as long as there is any residual autocorrelation in the refined sample.\n\n&
123 : & sampleRefinementMethod = '" // BATCH_MEANS_METHOD_NAME // "-compact'\n\n&
124 : & This is the same as the first case in the above, except that only the first phase of the sample refinement &
125 : &described in the above will be performed, that is, the (verbose) Markov chain is refined only based on the &
126 : &IAC computed from the compact format of the Markov chain. This will lead to a larger final refined sample. &
127 : &However, the final sample will likely not be fully decorrelated.\n\n&
128 : & sampleRefinementMethod = '" // BATCH_MEANS_METHOD_NAME // "-verbose'\n\n&
129 : & This is the same as the first case in the above, except that only the second phase of the sample refinement &
130 : &described in the above will be performed, that is, the (verbose) Markov chain is refined only based on the &
131 : &IAC computed from the verbose format of the Markov chain. While the resulting refined sample will be fully &
132 : &decorrelated, the size of the refined sample may be smaller than the default choice in the first case in the &
133 : &above.\n\n&
134 : &Note that in order to obtain i.i.d. samples from a multidimensional chain, "//methodName//" will use the average of &
135 : &IAC among all dimensions of the chain to refine the chain. If the maximum, minimum, or the median of IACs is preferred &
136 : &add '-max' (or '-maximum'), '-min' (or '-minimum'), '-med' (or '-median'), respectively, to the value of &
137 : &sampleRefinementMethod. For example, \n\n&
138 : & sampleRefinementMethod = '" // BATCH_MEANS_METHOD_NAME // "-max'\n\n&
139 : &or, \n\n&
140 : & sampleRefinementMethod = '" // BATCH_MEANS_METHOD_NAME // "-compact-max'\n\n&
141 : &or, \n\n&
142 : & sampleRefinementMethod = '" // BATCH_MEANS_METHOD_NAME // "-max-compact'\n\n&
143 : &Also, note that the value specified for sampleRefinementCount is used only when the variable sampleSize < 0, otherwise, &
144 : &it will be ignored. The default value is sampleRefinementMethod = '" // SampleRefinementMethodObj%def // "'. &
145 349 : &Note that the input values are case-insensitive and white-space characters are ignored."
146 349 : end function constructSampleRefinementMethod
147 :
148 : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
149 :
150 349 : subroutine nullifyNameListVar(SampleRefinementMethodObj)
151 : #if INTEL_COMPILER_ENABLED && defined DLL_ENABLED && (OS_IS_WINDOWS || defined OS_IS_DARWIN)
152 : !DEC$ ATTRIBUTES DLLEXPORT :: nullifyNameListVar
153 : #endif
154 : implicit none
155 : class(SampleRefinementMethod_type), intent(in) :: SampleRefinementMethodObj
156 349 : sampleRefinementMethod = SampleRefinementMethodObj%null
157 349 : end subroutine nullifyNameListVar
158 :
159 : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
160 :
161 363 : subroutine setSampleRefinementMethod(SampleRefinementMethodObj,sampleRefinementMethod)
162 : #if INTEL_COMPILER_ENABLED && defined DLL_ENABLED && (OS_IS_WINDOWS || defined OS_IS_DARWIN)
163 : !DEC$ ATTRIBUTES DLLEXPORT :: setSampleRefinementMethod
164 : #endif
165 349 : use String_mod, only: replaceStr !, getLowerCase
166 : implicit none
167 : class(SampleRefinementMethod_type), intent(inout) :: SampleRefinementMethodObj
168 : character(*), intent(in) :: sampleRefinementMethod
169 : !character(:), allocatable :: sampleRefinementMethodLowerCase
170 : !integer :: lenSampleRefinementMethod
171 :
172 363 : SampleRefinementMethodObj%val = trim(adjustl(replaceStr(sampleRefinementMethod," ", "")))
173 363 : if ( SampleRefinementMethodObj%val==trim(adjustl(SampleRefinementMethodObj%null)) ) then
174 321 : SampleRefinementMethodObj%val = SampleRefinementMethodObj%def
175 : end if
176 :
177 : !lenSampleRefinementMethod = len(SampleRefinementMethodObj%val)
178 : !sampleRefinementMethodLowerCase = getLowerCase(SampleRefinementMethodObj%val)
179 : !if ( sampleRefinementMethodLowerCase == getLowerCase(MAX_CUMSUM_AUTOCORR_METHOD_NAME) ) then
180 : ! SampleRefinementMethodObj%isMaxCumSumAutoCorr = .true.
181 : !elseif ( sampleRefinementMethodLowerCase(1:LEN_BATCH_MEANS_METHOD_NAME) == getLowerCase(BATCH_MEANS_METHOD_NAME) ) then
182 : ! if ( sampleRefinementMethodLowerCase(LEN_BATCH_MEANS_METHOD_NAME+1:lenSampleRefinementMethod) == "compact" ) then
183 : ! SampleRefinementMethodObj%isViaCompactChain = .true.
184 : ! SampleRefinementMethodObj%isBatchMeans = .true.
185 : ! elseif( len_trim(sampleRefinementMethodLowerCase(LEN_BATCH_MEANS_METHOD_NAME+1:lenSampleRefinementMethod)) == 0 ) then
186 : ! SampleRefinementMethodObj%isBatchMeans = .true.
187 : ! end if
188 : !end if
189 :
190 726 : end subroutine setSampleRefinementMethod
191 :
192 : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
193 :
194 345 : subroutine checkForSanity(SampleRefinementMethodObj,Err,methodName)
195 : #if INTEL_COMPILER_ENABLED && defined DLL_ENABLED && (OS_IS_WINDOWS || defined OS_IS_DARWIN)
196 : !DEC$ ATTRIBUTES DLLEXPORT :: checkForSanity
197 : #endif
198 363 : use String_mod, only: getLowerCase, replaceStr
199 : use String_mod, only: num2str
200 : use Err_mod, only: Err_type
201 : implicit none
202 : class(SampleRefinementMethod_type), intent(in) :: SampleRefinementMethodObj
203 : character(*), intent(in) :: methodName
204 : type(Err_type), intent(inout) :: Err
205 : character(*), parameter :: PROCEDURE_NAME = "@checkForSanity()"
206 345 : character(:), allocatable :: sampleRefinementMethodLowerCase
207 345 : sampleRefinementMethodLowerCase = getLowerCase(SampleRefinementMethodObj%val)
208 : if (index(sampleRefinementMethodLowerCase,getLowerCase(replaceStr(BATCH_MEANS_METHOD_NAME," ","")))==0 & ! LCOV_EXCL_LINE
209 : .and. &
210 : (index(sampleRefinementMethodLowerCase,getLowerCase(CUTOFF_AUTOCORR_METHOD_NAME))==0 .and. index(sampleRefinementMethodLowerCase,"cutoff")==0) &
211 1380 : .and. &
212 : (index(sampleRefinementMethodLowerCase,getLowerCase(MAX_CUMSUM_AUTOCORR_METHOD_NAME))==0 .and. index(sampleRefinementMethodLowerCase,"cumsum")==0) &
213 : ) then
214 2 : Err%occurred = .true.
215 : Err%msg = Err%msg // &
216 : MODULE_NAME // PROCEDURE_NAME // ": Error occurred. &
217 : &The input requested method for the computation of the Integrated Autocorrelation Time (" // &
218 : SampleRefinementMethodObj%val // ") assigned to the variable sampleRefinementMethod cannot be anything other than " // &
219 : BATCH_MEANS_METHOD_NAME // &
220 : ". " // &
221 : ! " or " // MAX_CUMSUM_AUTOCORR_METHOD_NAME // ". &
222 : "If you are not sure of the appropriate value for SampleRefinementMethod, drop it from the input list. " // &
223 1382 : methodName // " will automatically assign an appropriate value to it.\n\n"
224 : end if
225 345 : end subroutine checkForSanity
226 :
227 : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
228 :
229 : end module SpecMCMC_SampleRefinementMethod_mod ! LCOV_EXCL_LINE
|
