History Output API

Contents

• CCPP API
• Host Model API
• API Internals

CCPP API

Host Model API

• Coming Soon

API Internals (hist_api)

• hist_new_field (hist_api): Create a new field

   function hist_new_field(diag_name_in, std_name_in, long_name_in, units_in, &
        type_in, errors) result(new_field)
      type(hist_field_info_t), pointer                 :: new_field     ! The new field that is created
      character(len=*),                  intent(in)    :: diag_name_in  ! Field name in the history file
      character(len=*),                  intent(in)    :: std_name_in   ! CCPP Standard Name for the field
      character(len=*),                  intent(in)    :: long_name_in  ! The field's "long_name" attribute
      character(len=*),                  intent(in)    :: units_in      ! The field's "units" attribute
      character(len=*),                  intent(in)    :: type_in       ! String representation of the field's type
      type(hist_log_messages), optional, intent(inout) :: errors        ! Error log structure

• hist_new_buffer (hist_api): Create a new field buffer for processing captured diagnostic information
  • Note that the type of the buffer matches the type of its field.
  • While buffer is returned by hist_new_buffer, use is optional since it is already added to the linked-list of buffers contained in field.
  • The blocked data arguments are used when calls to hist_buffer_accumulate will be made from non-contiguous data (e.g., columns contained in separate spectral elements).

   subroutine hist_new_buffer(field, buff_shape, buff_kind, horiz_axis_ind,   &
        accum_type, output_vol, buffer, errors, block_ind, block_sizes)
      class(hist_field_info_t), pointer                 :: field          ! Field to which new buffer will be added
      integer,                            intent(in)    :: buff_shape(:)  ! Field shape
      integer,                            intent(in)    :: buff_kind      ! Buffer kind (e.g., REAL64)
      integer,                            intent(in)    :: horiz_axis_ind ! Which buffer index is the horizontal dimension
      character(len=*),                   intent(in)    :: accum_type     ! Accumulation type (e.g., 'lst', 'avg')
      integer,                            intent(in)    :: output_vol     ! Host-dependent history file number
      class(hist_buffer_t),     pointer,  intent(out)   :: buffer         ! Pointer to newly-created buffer
      type(hist_log_messages),  optional, intent(inout) :: errors         ! Error log structure
      integer,                  optional, intent(in)    :: block_ind      ! Which buffer index contains a block number (for blocked data)
      integer,                  optional, intent(in)    :: block_sizes(:) ! The number of active columns in each block (for blocked data)

• hist_buffer_accumulate (hist_api Accumulate field data according the buffer's processing method (e.g., average, last value) and sampling rules.
  • Note that there is a specific interface for each supported type / kind / rank combination.

   subroutine hist_field_accumulate(field, data, cols_or_block, cole, logger)
      class(hist_field_info_t), pointer,  intent(inout) :: field              ! Target accumulation field (all buffers attached to this field)
      <TYPE>(<KIND>),                     intent(in)    :: data(:[,:[,:...]]) ! New field data to accumulate
      integer,                            intent(in)    :: cols_or_block      ! First horizontal column or block number (for blocked data)
      integer,                  optional, intent(in)    :: cole               ! Last horizontal column to accumulate
      type(hist_log_messages),  optional, intent(inout) :: logger             ! Log message structure

• hist_buffer_norm_value (hist_api): Return the field's normalized value.
  • Note that there is a specific interface for each supported type / kind / rank combination.

   subroutine hist_buffer_norm_value(buffer, norm_val, default_val, logger)
      class(hist_buffer_t),    target,   intent(inout) :: buffer                 ! Return normalized value from this buffer
      <TYPE>(<KIND>),                    intent(inout) :: norm_val(:[,:[,:...]]) ! Field to receive normalized value
      <TYPE>(<KIND>),          optional, intent(in)    :: default_val            ! Value for columns with no accumulated value
      type(hist_log_messages), optional, intent(inout) :: logger                 ! Log message structure

• hist_buffer_clear (hist_api): Clear the buffer's accumulation state.

   subroutine hist_field_clear(field, logger)
      class(hist_field_info_t), pointer,  intent(inout) :: field  ! Clear accumulation state from this field's buffers
      type(hist_log_messages),  optional, intent(inout) :: logger ! Log message structure

• hist_buffer_accum_type (hist_api): Return a string describing the accumulation method used by this buffer (useful for output, e.g., as cell_methods attribure).

   function hist_buffer_accum_type(buffer) result(ac_str)
      class(hist_buffer_t), intent(in)   :: buffer ! Buffer from which to return accumulation type string