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        1047 :     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        1047 :         SampleRefinementMethodObj%def = BATCH_MEANS_METHOD_NAME
     104        1047 :         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        1047 :         &Note that the input values are case-insensitive and white-space characters are ignored."
     146        1047 :     end function constructSampleRefinementMethod
     147             : 
     148             : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     149             : 
     150        1047 :     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        1047 :         sampleRefinementMethod = SampleRefinementMethodObj%null
     157        1047 :     end subroutine nullifyNameListVar
     158             : 
     159             : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     160             : 
     161        1089 :     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        1047 :         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        1089 :         SampleRefinementMethodObj%val = trim(adjustl(replaceStr(sampleRefinementMethod," ", "")))
     173        1089 :         if ( SampleRefinementMethodObj%val==trim(adjustl(SampleRefinementMethodObj%null)) ) then
     174         963 :             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        2178 :     end subroutine setSampleRefinementMethod
     191             : 
     192             : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     193             : 
     194        1035 :     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        1089 :         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        1035 :         character(:), allocatable                       :: sampleRefinementMethodLowerCase
     207        1035 :         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        4140 :             .and. &
     212             :             (index(sampleRefinementMethodLowerCase,getLowerCase(MAX_CUMSUM_AUTOCORR_METHOD_NAME))==0 .and. index(sampleRefinementMethodLowerCase,"cumsum")==0) &
     213             :             ) then
     214           6 :             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        4146 :                         methodName // " will automatically assign an appropriate value to it.\n\n"
     224             :         end if
     225        1035 :     end subroutine checkForSanity
     226             : 
     227             : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     228             : 
     229             : end module SpecMCMC_SampleRefinementMethod_mod ! LCOV_EXCL_LINE