The ParaMonte Documentation Website
Current view: top level - kernel - SpecBase_ChainFileFormat_mod.f90 (source / functions) Hit Total Coverage
Test: ParaMonte 1.5.1 :: Serial Kernel - Code Coverage Report Lines: 31 31 100.0 %
Date: 2021-01-08 13:03:42 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 `chainFileFormat` 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_ChainFileFormat_mod
      49             : 
      50             :     use Constants_mod, only: IK
      51             :     implicit none
      52             : 
      53             :     character(*), parameter         :: MODULE_NAME = "@SpecBase_ChainFileFormat_mod"
      54             : 
      55             :     integer(IK), parameter          :: MAX_LEN_CHAIN_FILE_FORMAT = 63_IK
      56             : 
      57             :     character(MAX_LEN_CHAIN_FILE_FORMAT) :: chainFileFormat
      58             : 
      59             :     type                            :: ChainFileFormat_type
      60             :         logical                     :: isCompact
      61             :         logical                     :: isVerbose
      62             :         logical                     :: isBinary
      63             :         character(7)                :: compact
      64             :         character(7)                :: verbose
      65             :         character(6)                :: binary
      66             :         character(:), allocatable   :: def
      67             :         character(:), allocatable   :: val
      68             :         character(:), allocatable   :: null
      69             :         character(:), allocatable   :: desc
      70             :     contains
      71             :         procedure, pass             :: set => setChainFileFormat, checkForSanity, nullifyNameListVar
      72             :     end type ChainFileFormat_type
      73             : 
      74             :     interface ChainFileFormat_type
      75             :         module procedure            :: constructChainFileFormat
      76             :     end interface ChainFileFormat_type
      77             : 
      78             :     private :: constructChainFileFormat, setChainFileFormat, checkForSanity, nullifyNameListVar
      79             : 
      80             : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      81             : 
      82             : contains
      83             : 
      84             : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      85             : 
      86         349 :     function constructChainFileFormat(methodName) result(ChainFileFormatObj)
      87             : #if INTEL_COMPILER_ENABLED && defined DLL_ENABLED && (OS_IS_WINDOWS || defined OS_IS_DARWIN)
      88             :         !DEC$ ATTRIBUTES DLLEXPORT :: constructChainFileFormat
      89             : #endif
      90             :         use Constants_mod, only: NULL_SK, FILE_EXT, FILE_TYPE
      91             :         use String_mod, only: num2str
      92             :         implicit none
      93             :         character(*), intent(in)    :: methodName
      94             :         type(ChainFileFormat_type)  :: ChainFileFormatObj
      95             : 
      96         349 :         ChainFileFormatObj%isCompact = .false.
      97         349 :         ChainFileFormatObj%isVerbose = .false.
      98         349 :         ChainFileFormatObj%isBinary  = .false.
      99         349 :         ChainFileFormatObj%compact = "compact"
     100         349 :         ChainFileFormatObj%verbose = "verbose"
     101         349 :         ChainFileFormatObj%binary = FILE_TYPE%binary
     102         349 :         ChainFileFormatObj%def = ChainFileFormatObj%compact
     103             : 
     104         349 :         ChainFileFormatObj%null = repeat(NULL_SK, MAX_LEN_CHAIN_FILE_FORMAT)
     105             : 
     106             :         ChainFileFormatObj%desc = &
     107             :         "chainFileFormat is a string variable that represents the format of the output chain file(s) of "// methodName // &
     108             :         " simulation. The string value must be enclosed by either single or double quotation marks when provided as input. &
     109             :         &Three values are possible:\n\n&
     110             :         &    chainFileFormat = 'compact'\n\n&
     111             :         &            This is the ASCII (text) file format which is human-readable but does not preserve the full accuracy of the &
     112             :                     &output values. It is also a significantly slower mode of chain file generation, compared to the binary file format (see below). &
     113             :                     &If the compact format is specified, each of the repeating MCMC states will be condensed into a single entry (row) in &
     114             :                     &the output MCMC chain file. Each entry will be then assigned a sample-weight that is equal to the number of repetitions of &
     115             :                     &that state in the MCMC chain. Thus, each row in the output chain file will represent a unique sample from the objective function. &
     116             :                     &This will lead to a significantly smaller ASCII chain file and faster output size compared to the verbose chain file format (see below).\n\n&
     117             :         &    chainFileFormat = 'verbose'\n\n&
     118             :         &            This is the ASCII (text) file format which is human-readable but does not preserve the full accuracy of &
     119             :                     &the output values. It is also a significantly slower mode of chain file generation, &
     120             :                     &compared to both compact and binary chain file formats (see above and below). &
     121             :                     &If the verbose format is specified, all MCMC states will have equal sample-weights of 1 in the output chain file. &
     122             :                     &The verbose format can lead to much larger chain file sizes than the compact and binary file formats. &
     123             :                     &This is especially true if the target objective function has a very high-dimensional state space.\n\n&
     124             :         &    chainFileFormat = '" // ChainFileFormatObj%binary // "'\n\n&
     125             :         &            This is the binary file format which is not human-readable, but preserves the exact values in the output &
     126             :                     &MCMC chain file. It is also often the fastest mode of chain file generation. If the binary file format is chosen, the chain &
     127             :                     &will be automatically output in the compact format (but as binary) to ensure the production of the smallest-possible output chain file. &
     128             :                     &Binary chain files will have the " // FILE_EXT%binary // " file extensions. Use the binary format if you need full accuracy representation &
     129             :                     &of the output values while having the smallest-size output chain file in the shortest time possible.\n\n&
     130             :         &The default value is chainFileFormat = '" // ChainFileFormatObj%def // "' as it provides a reasonable trade-off between &
     131         349 :         &speed and output file size while generating human-readable chain file contents. Note that the input values are case-insensitive."
     132         349 :     end function constructChainFileFormat
     133             : 
     134             : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     135             : 
     136         349 :     subroutine nullifyNameListVar(ChainFileFormatObj)
     137             : #if INTEL_COMPILER_ENABLED && defined DLL_ENABLED && (OS_IS_WINDOWS || defined OS_IS_DARWIN)
     138             :         !DEC$ ATTRIBUTES DLLEXPORT :: nullifyNameListVar
     139             : #endif
     140             :         implicit none
     141             :         class(ChainFileFormat_type), intent(in) :: ChainFileFormatObj
     142         349 :         chainFileFormat = ChainFileFormatObj%null
     143         349 :     end subroutine nullifyNameListVar
     144             : 
     145             : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     146             : 
     147         371 :     subroutine setChainFileFormat(ChainFileFormatObj,chainFileFormat)
     148             : #if INTEL_COMPILER_ENABLED && defined DLL_ENABLED && (OS_IS_WINDOWS || defined OS_IS_DARWIN)
     149             :         !DEC$ ATTRIBUTES DLLEXPORT :: setChainFileFormat
     150             : #endif
     151         349 :         use String_mod, only: getLowerCase
     152             :         implicit none
     153             :         class(ChainFileFormat_type), intent(inout)  :: ChainFileFormatObj
     154             :         character(*), intent(in)                    :: chainFileFormat
     155         371 :         character(:), allocatable                   :: lowerCaseVal
     156         371 :         ChainFileFormatObj%val = trim(adjustl(chainFileFormat))
     157         371 :         if ( ChainFileFormatObj%val==trim(adjustl(ChainFileFormatObj%null)) ) then
     158         337 :             ChainFileFormatObj%val = trim(adjustl(ChainFileFormatObj%def))
     159             :         end if
     160         371 :         lowerCaseVal = getLowerCase(ChainFileFormatObj%val)
     161         371 :         ChainFileFormatObj%iscompact = lowerCaseVal == getLowerCase(ChainFileFormatObj%compact)
     162         371 :         ChainFileFormatObj%isverbose = lowerCaseVal == getLowerCase(ChainFileFormatObj%verbose)
     163         371 :         ChainFileFormatObj%isBinary  = lowerCaseVal == getLowerCase(ChainFileFormatObj%binary)
     164         371 :     end subroutine setChainFileFormat
     165             : 
     166             : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     167             : 
     168         345 :     subroutine checkForSanity(ChainFileFormat,Err,methodName)
     169             : #if INTEL_COMPILER_ENABLED && defined DLL_ENABLED && (OS_IS_WINDOWS || defined OS_IS_DARWIN)
     170             :         !DEC$ ATTRIBUTES DLLEXPORT :: checkForSanity
     171             : #endif
     172         371 :         use Err_mod, only: Err_type
     173             :         use String_mod, only: num2str
     174             :         implicit none
     175             :         class(ChainFileFormat_type), intent(in)     :: ChainFileFormat
     176             :         character(*), intent(in)                    :: methodName
     177             :         type(Err_type), intent(inout)               :: Err
     178             :         character(*), parameter                     :: PROCEDURE_NAME = "@checkForSanity()"
     179         345 :         if ( .not.(ChainFileFormat%isCompact .or. ChainFileFormat%isVerbose .or. ChainFileFormat%isBinary) ) then
     180           4 :             Err%occurred = .true.
     181             :             Err%msg =   Err%msg // &
     182             :                         MODULE_NAME // PROCEDURE_NAME // ": Error occurred. &
     183             :                         &The input requested chain file format ('" // ChainFileFormat%val // &
     184             :                         "') represented by the variable chainFileFormat cannot be anything other than '" // &
     185             :                         ChainFileFormat%compact // "' or '" // ChainFileFormat%verbose // "' or '" // ChainFileFormat%binary // "'. &
     186             :                         &If you don't know an appropriate value for chainFileFormat, drop it from the input list. " // methodName // &
     187           4 :                         " will automatically assign an appropriate value to it.\n\n"
     188             :         end if
     189         690 :     end subroutine checkForSanity
     190             : 
     191             : !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     192             : 
     193             : end module SpecBase_ChainFileFormat_mod ! LCOV_EXCL_LINE

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