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 `targetAcceptanceRate` attribute of ParaMonte samplers.
45 : !> For more information, see the description of this attribute in the body of the module.
46 : !> \author Amir Shahmoradi
47 :
48 : module SpecBase_TargetAcceptanceRate_mod
49 :
50 : use Constants_mod, only: RK
51 : implicit none
52 :
53 : character(*), parameter :: MODULE_NAME = "@SpecBase_TargetAcceptanceRate_mod"
54 :
55 : real(RK) :: TargetAcceptanceRate(2) ! namelist input
56 :
57 : type :: TargetAcceptanceRate_type
58 : logical :: scalingRequested
59 : real(RK) :: Val(2)
60 : real(RK) :: Def(2)
61 : real(RK) :: null
62 : character(:), allocatable :: desc
63 : contains
64 : procedure, pass :: set => setTargetAcceptanceRate, checkForSanity, nullifyNameListVar
65 : end type TargetAcceptanceRate_type
66 :
67 : interface TargetAcceptanceRate_type
68 : module procedure :: constructTargetAcceptanceRate
69 : end interface TargetAcceptanceRate_type
70 :
71 : private :: constructTargetAcceptanceRate, setTargetAcceptanceRate, nullifyNameListVar
72 :
73 : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
74 :
75 : contains
76 :
77 : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
78 :
79 349 : function constructTargetAcceptanceRate(methodName) result(TargetAcceptanceRateObj)
80 : #if INTEL_COMPILER_ENABLED && defined DLL_ENABLED && (OS_IS_WINDOWS || defined OS_IS_DARWIN)
81 : !DEC$ ATTRIBUTES DLLEXPORT :: constructTargetAcceptanceRate
82 : #endif
83 : use Constants_mod, only: NULL_RK
84 : use String_mod, only: num2str
85 : implicit none
86 : character(*), intent(in) :: methodName
87 : type(TargetAcceptanceRate_type) :: TargetAcceptanceRateObj
88 349 : TargetAcceptanceRateObj%scalingRequested = .true.
89 1047 : TargetAcceptanceRateObj%Def = [ 0._RK, 1._RK ]
90 349 : TargetAcceptanceRateObj%null = NULL_RK
91 : TargetAcceptanceRateObj%desc = &
92 : "targetAcceptanceRate sets an optimal target for the ratio of the number of accepted objective function calls to the &
93 : &total number of function calls by the " // methodName // " sampler. It is a real-valued array of length 2, whose elements &
94 : &determine the upper and lower bounds of the desired acceptance rate. When the acceptance rate of the sampler is outside the &
95 : &specified limits, the sampler's settings will be automatically adjusted to bring the overall acceptance rate to within the &
96 : &specified limits by the input variable targetAcceptanceRate. When assigned from within a dynamic-language programming &
97 : &environment, such as MATLAB or Python, or from within an input file, targetAcceptanceRate can also be a single real number &
98 : &between 0 and 1. In such case, the " // methodName // " sampler will constantly attempt (with no guarantee of success) &
99 : &to bring the average acceptance ratio of the sampler as close to the user-provided target ratio as possible. The success &
100 : &of " // methodName // " in keeping the average acceptance ratio close to the requested target value depends heavily on:\n\n&
101 : & 1) the value of adaptiveUpdatePeriod; the larger, the easier.\n&
102 : & 2) the value of adaptiveUpdateCount; the larger, the easier.\n\n&
103 : &Note that the acceptance ratio adjustments will only occur every adaptiveUpdatePeriod sampling steps for a total &
104 : &number of adaptiveUpdateCount. &
105 349 : &There is no default value for targetAcceptanceRate, as the acceptance ratio is not directly adjusted during sampling."
106 349 : end function constructTargetAcceptanceRate
107 :
108 : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
109 :
110 349 : subroutine nullifyNameListVar(TargetAcceptanceRateObj)
111 : #if INTEL_COMPILER_ENABLED && defined DLL_ENABLED && (OS_IS_WINDOWS || defined OS_IS_DARWIN)
112 : !DEC$ ATTRIBUTES DLLEXPORT :: nullifyNameListVar
113 : #endif
114 : implicit none
115 : class(TargetAcceptanceRate_type), intent(in) :: TargetAcceptanceRateObj
116 1047 : TargetAcceptanceRate = TargetAcceptanceRateObj%null
117 349 : end subroutine nullifyNameListVar
118 :
119 : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
120 :
121 369 : subroutine setTargetAcceptanceRate(TargetAcceptanceRateObj,targetAcceptanceRate)
122 : #if INTEL_COMPILER_ENABLED && defined DLL_ENABLED && (OS_IS_WINDOWS || defined OS_IS_DARWIN)
123 : !DEC$ ATTRIBUTES DLLEXPORT :: setTargetAcceptanceRate
124 : #endif
125 349 : use Constants_mod, only: RK
126 : implicit none
127 : class(TargetAcceptanceRate_type), intent(inout) :: TargetAcceptanceRateObj
128 : real(RK), intent(in) :: TargetAcceptanceRate(2)
129 : logical :: lowerLimitSet, upperLimitSet
130 1107 : TargetAcceptanceRateObj%Val = targetAcceptanceRate
131 369 : lowerLimitSet = TargetAcceptanceRateObj%Val(1) /= TargetAcceptanceRateObj%null
132 369 : upperLimitSet = TargetAcceptanceRateObj%Val(2) /= TargetAcceptanceRateObj%null
133 369 : if (lowerLimitSet .and. .not. upperLimitSet) TargetAcceptanceRateObj%Val(2) = TargetAcceptanceRateObj%Val(1)
134 369 : if (upperLimitSet .and. .not. lowerLimitSet) TargetAcceptanceRateObj%Val(1) = TargetAcceptanceRateObj%Val(2)
135 1043 : if (.not.(lowerLimitSet .or. upperLimitSet)) TargetAcceptanceRateObj%Val(:) = TargetAcceptanceRateObj%Def
136 1049 : TargetAcceptanceRateObj%scalingRequested = any(TargetAcceptanceRateObj%Val /= TargetAcceptanceRateObj%Def)
137 369 : end subroutine setTargetAcceptanceRate
138 :
139 : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
140 :
141 345 : subroutine checkForSanity(TargetAcceptanceRateObj,Err)
142 : #if INTEL_COMPILER_ENABLED && defined DLL_ENABLED && (OS_IS_WINDOWS || defined OS_IS_DARWIN)
143 : !DEC$ ATTRIBUTES DLLEXPORT :: checkForSanity
144 : #endif
145 369 : use Constants_mod, only: RK
146 : use Err_mod, only: Err_type
147 : use String_mod, only: num2str
148 : implicit none
149 : class(TargetAcceptanceRate_type), intent(in) :: TargetAcceptanceRateObj
150 : type(Err_type), intent(inout) :: Err
151 : character(*), parameter :: PROCEDURE_NAME = "@checkForSanity()"
152 317 : if (.not. TargetAcceptanceRateObj%scalingRequested) return
153 132 : if ( any(TargetAcceptanceRateObj%Val<0._RK) .or. any(TargetAcceptanceRateObj%Val>1._RK) ) then
154 4 : Err%occurred = .true.
155 : Err%msg = Err%msg // &
156 : MODULE_NAME // PROCEDURE_NAME // ": Error occurred. &
157 : &The target acceptance ratio limits targetAcceptanceRate [" // &
158 : num2str(TargetAcceptanceRateObj%Val(1)) // "," // num2str(TargetAcceptanceRateObj%Val(2)) // &
159 4 : "] cannot be less than 0 or larger than 1.\n\n"
160 : end if
161 36 : if ( all(TargetAcceptanceRateObj%Val==0._RK) .or. all(TargetAcceptanceRateObj%Val==1._RK) ) then
162 4 : Err%occurred = .true.
163 : Err%msg = Err%msg // &
164 : MODULE_NAME // PROCEDURE_NAME // ": Error occurred. &
165 : &The target acceptance ratio limits targetAcceptanceRate [" // &
166 : num2str(TargetAcceptanceRateObj%Val(1)) // "," // num2str(TargetAcceptanceRateObj%Val(2)) // &
167 4 : "] cannot be both 0 or both 1.\n\n"
168 : end if
169 28 : if (TargetAcceptanceRateObj%Val(2) < TargetAcceptanceRateObj%Val(1)) then
170 2 : Err%occurred = .true.
171 : Err%msg = Err%msg // &
172 : MODULE_NAME // PROCEDURE_NAME // ": Error occurred. &
173 : &The the lower limit of the input specification targetAcceptanceRate [" // &
174 : num2str(TargetAcceptanceRateObj%Val(1)) // "," // num2str(TargetAcceptanceRateObj%Val(2)) // &
175 2 : "] cannot be larger than the specified upper limit.\n\n"
176 : end if
177 345 : end subroutine checkForSanity
178 :
179 : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
180 :
181 : end module SpecBase_TargetAcceptanceRate_mod ! LCOV_EXCL_LINE
|
