The ParaMonte Documentation Website
Current view: top level - kernel - SpecBase_SampleSize_mod.f90 (source / functions) Hit Total Coverage
Test: ParaMonte 1.5.1 :: Serial Kernel - Code Coverage Report Lines: 16 16 100.0 %
Date: 2021-01-08 13:03:42 Functions: 3 3 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 `sampleSize` 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_SampleSize_mod
      49             : 
      50             :     use Constants_mod, only: IK
      51             :     implicit none
      52             : 
      53             :     integer(IK)                     :: sampleSize ! namelist input
      54             : 
      55             :     character(*), parameter         :: MODULE_NAME = "@SpecBase_SampleSize_mod"
      56             : 
      57             :     type                            :: SampleSize_type
      58             :         integer(IK)                 :: val
      59             :         integer(IK)                 :: abs
      60             :         integer(IK)                 :: def
      61             :         integer(IK)                 :: null
      62             :         character(:), allocatable   :: str
      63             :         character(:), allocatable   :: desc
      64             :     contains
      65             :         procedure, pass             :: set => setSampleSize, nullifyNameListVar ! , checkForSanity
      66             :     end type SampleSize_type
      67             : 
      68             :     interface SampleSize_type
      69             :         module procedure            :: constructSampleSize
      70             :     end interface SampleSize_type
      71             : 
      72             :     private :: constructSampleSize, setSampleSize, nullifyNameListVar
      73             : 
      74             : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      75             : 
      76             : contains
      77             : 
      78             : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      79             : 
      80         349 :     function constructSampleSize(methodName) result(SampleSizeObj)
      81             : #if INTEL_COMPILER_ENABLED && defined DLL_ENABLED && (OS_IS_WINDOWS || defined OS_IS_DARWIN)
      82             :         !DEC$ ATTRIBUTES DLLEXPORT :: constructSampleSize
      83             : #endif
      84             :         use Constants_mod, only: IK, NULL_IK
      85             :         use String_mod, only: num2str
      86             :         implicit none
      87             :         character(*), intent(in)    :: methodName
      88             :         type(SampleSize_type)       :: SampleSizeObj
      89         349 :         SampleSizeObj%def  = -1
      90         349 :         SampleSizeObj%null = NULL_IK
      91             :         SampleSizeObj%desc = &
      92             :         "The variable sampleSize is an integer that dictates the number of (hopefully, independent and identically distributed &
      93             :         &[i.i.d.]) samples to be drawn from the user-provided objective function. Three ranges of values are possible. If\n\n&
      94             :         &    sampleSize < 0,\n\n&
      95             :         &            then, the absolute value of sampleSize dictates the sample size in units of the effective sample size. &
      96             :                      &The effective sample is by definition i.i.d., and free from duplicates and residual autocorrelation. The &
      97             :                      &effective sample size is automatically determined by " // methodName // " toward the end of the simulation. &
      98             :                      &For example:\n\n&
      99             :         &                    sampleSize = -1 yields the effective i.i.d. sample drawn from the objective function.\n\n&
     100             :         &                    sampleSize = -2 yields a (potentially non-i.i.d.) sample twice as big as the effective &
     101             :                              &sample.\n\n&
     102             :         &    sampleSize > 0,\n\n&
     103             :         &            then, the sample size is assumed to be in units of the number of points to be sampled. &
     104             :                      &If sampleSize turns out to be less than effectiveSampleSize, the resulting sample will be i.i.d.. &
     105             :                      &If sampleSize turns out to be larger than effectiveSampleSize, the resulting sample will be &
     106             :                      &potentially non-i.i.d.. The larger this difference, the more non-i.i.d. the resulting &
     107             :                      &final refined sample will be. For example:\n\n&
     108             :         &                    sampleSize = 1000 yields a 1000-points sample from the objective function.\n\n&
     109             :         &    sampleSize = 0,\n\n&
     110             :         &            then, no sample file will be generated.\n\n&
     111         349 :         &The default value is sampleSize = "// num2str(SampleSizeObj%def) //"."
     112         349 :     end function constructSampleSize
     113             : 
     114             : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     115             : 
     116         349 :     subroutine nullifyNameListVar(SampleSizeObj)
     117             : #if INTEL_COMPILER_ENABLED && defined DLL_ENABLED && (OS_IS_WINDOWS || defined OS_IS_DARWIN)
     118             :         !DEC$ ATTRIBUTES DLLEXPORT :: nullifyNameListVar
     119             : #endif
     120             :         implicit none
     121             :         class(SampleSize_type), intent(in)  :: SampleSizeObj
     122         349 :         sampleSize = SampleSizeObj%null
     123         349 :     end subroutine nullifyNameListVar
     124             : 
     125             : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     126             : 
     127         410 :     subroutine setSampleSize(SampleSizeObj,sampleSize)
     128             : #if INTEL_COMPILER_ENABLED && defined DLL_ENABLED && (OS_IS_WINDOWS || defined OS_IS_DARWIN)
     129             :         !DEC$ ATTRIBUTES DLLEXPORT :: setSampleSize
     130             : #endif
     131         349 :         use String_mod, only: num2str
     132             :         use Constants_mod, only: IK
     133             :         implicit none
     134             :         class(SampleSize_type), intent(inout)   :: SampleSizeObj
     135             :         integer(IK), intent(in)                 :: sampleSize
     136         410 :         SampleSizeObj%val = sampleSize
     137         410 :         if (SampleSizeObj%val==SampleSizeObj%null) then
     138         347 :             SampleSizeObj%val = SampleSizeObj%def
     139             :         end if
     140         410 :         SampleSizeObj%str = num2str(SampleSizeObj%val)
     141         410 :         SampleSizeObj%abs = abs(SampleSizeObj%val)
     142         410 :     end subroutine setSampleSize
     143             : 
     144             : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     145             : 
     146             : !    subroutine checkForSanity(SampleSizeObj,Err,methodName)
     147             : !#if INTEL_COMPILER_ENABLED && defined DLL_ENABLED && (OS_IS_WINDOWS || defined OS_IS_DARWIN)
     148             : !        !DEC$ ATTRIBUTES DLLEXPORT :: checkForSanity
     149             : !#endif
     150             : !        use Err_mod, only: Err_type
     151             : !        use String_mod, only: num2str
     152             : !        implicit none
     153             : !        class(SampleSize_type), intent(in) :: SampleSizeObj
     154             : !        character(*), intent(in)           :: methodName
     155             : !        type(Err_type), intent(inout)      :: Err
     156             : !        character(*), parameter            :: PROCEDURE_NAME = "@checkForSanity()"
     157             : !        if ( SampleSizeObj%val<1 ) then
     158             : !            Err%occurred = .true.
     159             : !            Err%msg =   Err%msg // &
     160             : !                        MODULE_NAME // PROCEDURE_NAME // ": Error occurred. &
     161             : !                        &The input value for variable sampleSize must be a positive integer. If you are not sure about the &
     162             : !                        &appropriate value for this variable, simply drop it from the input. " // methodName // &
     163             : !                        " will automatically assign an appropriate value to it.\n\n"
     164             : !        end if
     165             : !    end subroutine checkForSanity
     166             : 
     167             : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     168             : 
     169             : end module SpecBase_SampleSize_mod ! LCOV_EXCL_LINE

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