The ParaMonte Documentation Website
Current view: top level - kernel - SpecBase_TargetAcceptanceRate_mod.f90 (source / functions) Hit Total Coverage
Test: ParaMonte 1.5.1 :: MPI Parallel Kernel - Code Coverage Report Lines: 32 32 100.0 %
Date: 2021-01-08 13:07:16 Functions: 4 4 100.0 %
Legend: Lines: hit not hit

          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        1047 :     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        1047 :         TargetAcceptanceRateObj%scalingRequested = .true.
      89        3141 :         TargetAcceptanceRateObj%Def = [ 0._RK, 1._RK ]
      90        1047 :         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        1047 :         &There is no default value for targetAcceptanceRate, as the acceptance ratio is not directly adjusted during sampling."
     106        1047 :     end function constructTargetAcceptanceRate
     107             : 
     108             : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     109             : 
     110        1047 :     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        3141 :         TargetAcceptanceRate = TargetAcceptanceRateObj%null
     117        1047 :     end subroutine nullifyNameListVar
     118             : 
     119             : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     120             : 
     121        1107 :     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        1047 :         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        3321 :         TargetAcceptanceRateObj%Val = targetAcceptanceRate
     131        1107 :         lowerLimitSet = TargetAcceptanceRateObj%Val(1) /= TargetAcceptanceRateObj%null
     132        1107 :         upperLimitSet = TargetAcceptanceRateObj%Val(2) /= TargetAcceptanceRateObj%null
     133        1107 :         if (lowerLimitSet .and. .not. upperLimitSet) TargetAcceptanceRateObj%Val(2) = TargetAcceptanceRateObj%Val(1)
     134        1107 :         if (upperLimitSet .and. .not. lowerLimitSet) TargetAcceptanceRateObj%Val(1) = TargetAcceptanceRateObj%Val(2)
     135        3129 :         if (.not.(lowerLimitSet .or. upperLimitSet)) TargetAcceptanceRateObj%Val(:) = TargetAcceptanceRateObj%Def
     136        3147 :         TargetAcceptanceRateObj%scalingRequested = any(TargetAcceptanceRateObj%Val /= TargetAcceptanceRateObj%Def)
     137        1107 :     end subroutine setTargetAcceptanceRate
     138             : 
     139             : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     140             : 
     141        1035 :     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        1107 :         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         951 :         if (.not. TargetAcceptanceRateObj%scalingRequested) return
     153         396 :         if ( any(TargetAcceptanceRateObj%Val<0._RK) .or. any(TargetAcceptanceRateObj%Val>1._RK) ) then
     154          12 :             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          12 :                         "] cannot be less than 0 or larger than 1.\n\n"
     160             :         end if
     161         108 :         if ( all(TargetAcceptanceRateObj%Val==0._RK) .or. all(TargetAcceptanceRateObj%Val==1._RK) ) then
     162          12 :             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          12 :                         "] cannot be both 0 or both 1.\n\n"
     168             :         end if
     169          84 :         if (TargetAcceptanceRateObj%Val(2) < TargetAcceptanceRateObj%Val(1)) then
     170           6 :             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           6 :                         "] cannot be larger than the specified upper limit.\n\n"
     176             :         end if
     177        1035 :     end subroutine checkForSanity
     178             : 
     179             : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     180             : 
     181             : end module SpecBase_TargetAcceptanceRate_mod ! LCOV_EXCL_LINE

ParaMonte: Plain Powerful Parallel Monte Carlo Library 
The Computational Data Science Lab
© Copyright 2012 - 2021