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 `burninAdaptationMeasure` attribute of samplers of class [ParaDRAM_type](@ref paradram_mod::paradram_type).
45 : !> For more information, see the description of this attribute in the body of the module.
46 : !> \author Amir Shahmoradi
47 :
48 : module SpecDRAM_BurninAdaptationMeasure_mod
49 :
50 : use Constants_mod, only: RK
51 : implicit none
52 :
53 : character(*), parameter :: MODULE_NAME = "@SpecDRAM_BurninAdaptationMeasure_mod"
54 :
55 : real(RK) :: burninAdaptationMeasure ! namelist input
56 :
57 : type :: BurninAdaptationMeasure_type
58 : real(RK) :: val
59 : real(RK) :: def
60 : real(RK) :: null
61 : character(:), allocatable :: desc
62 : contains
63 : procedure, pass :: set => setBurninAdaptationMeasure, checkForSanity, nullifyNameListVar
64 : end type BurninAdaptationMeasure_type
65 :
66 : interface BurninAdaptationMeasure_type
67 : module procedure :: constructBurninAdaptationMeasure
68 : end interface BurninAdaptationMeasure_type
69 :
70 : private :: constructBurninAdaptationMeasure, setBurninAdaptationMeasure, nullifyNameListVar
71 :
72 : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
73 :
74 : contains
75 :
76 : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
77 :
78 1047 : function constructBurninAdaptationMeasure(methodName) result(BurninAdaptationMeasureObj)
79 : #if INTEL_COMPILER_ENABLED && defined DLL_ENABLED && (OS_IS_WINDOWS || defined OS_IS_DARWIN)
80 : !DEC$ ATTRIBUTES DLLEXPORT :: constructBurninAdaptationMeasure
81 : #endif
82 : use Constants_mod, only: NULL_RK
83 : use String_mod, only: num2str
84 : implicit none
85 : character(*), intent(in) :: methodName
86 : type(BurninAdaptationMeasure_type) :: BurninAdaptationMeasureObj
87 1047 : BurninAdaptationMeasureObj%def = 1._RK
88 1047 : BurninAdaptationMeasureObj%null = NULL_RK
89 : BurninAdaptationMeasureObj%desc = &
90 : "burninAdaptationMeasure is a 64-bit real number between 0 and 1, representing the adaptation measure threshold below &
91 : &which the simulated Markov chain will be used to generate the output " //methodName// " sample. In other words, any &
92 : &point in the output Markov Chain that has been sampled during significant adaptation of the proposal distribution (as &
93 : &determined by burninAdaptationMeasure) will not be included in the construction of the final " //methodName// " output &
94 : &sample. This is to ensure that the generation of the output sample will be based on the part of the simulated chain that &
95 : &is practically guaranteed to be Markovian and ergodic. If this variable is set to 0, then the output sample will be &
96 : &generated from the part of the chain where no proposal adaptation has occurred. This non-adaptive or &
97 : &minimally-adaptive part of the chain may not even exist if the total adaptation period of the simulation &
98 : &(as determined by adaptiveUpdateCount and adaptiveUpdatePeriod input variables) is longer than the total length &
99 : &of the output MCMC chain. In such cases, the resulting output sample may have a zero size. In general, when &
100 : &good mixing occurs (e.g., when the input variable chainSize is very large) any specific value of burninAdaptationMeasure &
101 : &becomes practically irrelevant. &
102 : &The default value for burninAdaptationMeasure is "//num2str(BurninAdaptationMeasureObj%def)//", implying that the entire &
103 1047 : &chain (with the exclusion of an initial automatically-determined burnin period) will be used to generate the final output sample."
104 1047 : end function constructBurninAdaptationMeasure
105 :
106 : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
107 :
108 1047 : subroutine nullifyNameListVar(BurninAdaptationMeasureObj)
109 : #if INTEL_COMPILER_ENABLED && defined DLL_ENABLED && (OS_IS_WINDOWS || defined OS_IS_DARWIN)
110 : !DEC$ ATTRIBUTES DLLEXPORT :: nullifyNameListVar
111 : #endif
112 : implicit none
113 : class(BurninAdaptationMeasure_type), intent(in) :: BurninAdaptationMeasureObj
114 1047 : burninAdaptationMeasure = BurninAdaptationMeasureObj%null
115 2094 : end subroutine nullifyNameListVar
116 :
117 : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
118 :
119 1065 : subroutine setBurninAdaptationMeasure(BurninAdaptationMeasureObj,burninAdaptationMeasure)
120 : #if INTEL_COMPILER_ENABLED && defined DLL_ENABLED && (OS_IS_WINDOWS || defined OS_IS_DARWIN)
121 : !DEC$ ATTRIBUTES DLLEXPORT :: setBurninAdaptationMeasure
122 : #endif
123 1047 : use Constants_mod, only: RK
124 : implicit none
125 : class(BurninAdaptationMeasure_type), intent(inout) :: BurninAdaptationMeasureObj
126 : real(RK), intent(in) :: burninAdaptationMeasure
127 1065 : BurninAdaptationMeasureObj%val = burninAdaptationMeasure
128 1041 : if (BurninAdaptationMeasureObj%val==BurninAdaptationMeasureObj%null) BurninAdaptationMeasureObj%val = BurninAdaptationMeasureObj%def
129 1065 : end subroutine setBurninAdaptationMeasure
130 :
131 : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
132 :
133 1035 : subroutine checkForSanity(BurninAdaptationMeasureObj,Err,methodName)
134 : #if INTEL_COMPILER_ENABLED && defined DLL_ENABLED && (OS_IS_WINDOWS || defined OS_IS_DARWIN)
135 : !DEC$ ATTRIBUTES DLLEXPORT :: checkForSanity
136 : #endif
137 1065 : use Constants_mod, only: RK
138 : use Err_mod, only: Err_type
139 : use String_mod, only: num2str
140 : implicit none
141 : class(BurninAdaptationMeasure_type), intent(in) :: BurninAdaptationMeasureObj
142 : type(Err_type), intent(inout) :: Err
143 : character(*), intent(in) :: methodName
144 : character(*), parameter :: PROCEDURE_NAME = "@checkForSanity()"
145 1035 : if ( BurninAdaptationMeasureObj%val<0._RK ) then
146 6 : Err%occurred = .true.
147 : Err%msg = Err%msg // &
148 : MODULE_NAME // PROCEDURE_NAME // ": Error occurred. &
149 : &The input variable burninAdaptationMeasure (" // num2str(BurninAdaptationMeasureObj%val) // &
150 : ") cannot be less than 0. If you are not sure of the appropriate value for burninAdaptationMeasure, drop it &
151 6 : &from the input list. " // methodName // " will automatically assign an appropriate value to it.\n\n"
152 : end if
153 1035 : if ( BurninAdaptationMeasureObj%val>1._RK ) then
154 6 : Err%occurred = .true.
155 : Err%msg = Err%msg // &
156 : MODULE_NAME // PROCEDURE_NAME // ": Error occurred. &
157 : &The input variable burninAdaptationMeasure (" // num2str(BurninAdaptationMeasureObj%val) // &
158 : ") cannot be larger than 1. If you are not sure of the appropriate value for burninAdaptationMeasure, drop it &
159 6 : &from the input list. " // methodName // " will automatically assign an appropriate value to it.\n\n"
160 : end if
161 2070 : end subroutine checkForSanity
162 :
163 : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
164 :
165 : end module SpecDRAM_BurninAdaptationMeasure_mod ! LCOV_EXCL_LINE
|
