timeselectmodule Module Reference

Specify times for some event to occur.

Data Types
type	timeselecttype
	Represents a series of instants at which some event should occur. More...

Functions/Subroutines
subroutine	deallocate (this)
	Deallocate the time selection object. More...
subroutine	expand (this, increment)
	Expand capacity by the given amount. Resets the current slice. More...
subroutine	init (this)
	Initialize or clear the time selection object. More...
logical(lgp) function	increasing (this)
	Determine if times strictly increase. More...
subroutine	log (this, iout, verb)
	Show the current time selection, if any. More...
subroutine	select (this, t0, t1, changed)
	Select times between t0 and t1 (inclusive). More...
subroutine	advance (this)
	Update the selection to the current time step. More...
logical(lgp) function	any (this)
	Check if any times are currently selected. More...
integer(i4b) function	count (this)
	Return the number of times currently selected. More...
subroutine	sort (this)
	Sort the time selection in increasing order. More...
subroutine	extend (this, a)
	Extend the time selection with the given array. More...

Function/Subroutine Documentation

advance()

subroutine timeselectmodule::advance

(

class(timeselecttype)

this

)

Definition at line 197 of file TimeSelect.f90.

    ! modules
    use tdismodule, only: kper, kstp, nper, nstp, totimc, delt
    ! dummy
    class(TimeSelectType) :: this
    ! local
    real(DP) :: l, u
 
    l = minval(this%times)
    u = maxval(this%times)
    if (.not. (kper == 1 .and. kstp == 1)) l = totimc
    if (.not. (kper == nper .and. kstp == nstp(kper))) u = totimc + delt
    call this%select(l, u)

any()

logical(lgp) function timeselectmodule::any

(

class(timeselecttype)

this

)

Indicates whether any times are selected for the current time step.

Note that this routine does NOT indicate whether the times array has nonzero size; use the size intrinsic for that.

Definition at line 221 of file TimeSelect.f90.

    class(TimeSelectType) :: this
    logical(LGP) :: a
 
    a = all(this%selection > 0)

count()

integer(i4b) function timeselectmodule::count

(

class(timeselecttype)

this

)

Returns the number of times selected for the current time step.

Note that this routine does NOT return the total size of the times array; use the size intrinsic for that.

Definition at line 236 of file TimeSelect.f90.

    class(TimeSelectType) :: this
    integer(I4B) :: n
 
    if (this%any()) then
      n = this%selection(2) - this%selection(1)
    else
      n = 0
    end if

deallocate()

subroutine timeselectmodule::deallocate

(

class(timeselecttype)

this

)

Definition at line 50 of file TimeSelect.f90.

    class(TimeSelectType) :: this
    deallocate (this%times)

expand()

subroutine timeselectmodule::expand	(	class(timeselecttype)	this,
		integer(i4b), intent(in), optional	increment
	)

Definition at line 56 of file TimeSelect.f90.

    class(TimeSelectType) :: this
    integer(I4B), optional, intent(in) :: increment
 
    call expandarray(this%times, increment=increment)
    this%selection = (/1, size(this%times)/)

extend()

subroutine timeselectmodule::extend	(	class(timeselecttype)	this,
		real(dp), dimension(:)	a
	)

This routine sorts the selection after appending the elements of the given array, but users should likely still call increasing() to check for duplicate times.

Definition at line 267 of file TimeSelect.f90.

    class(TimeSelectType) :: this
    real(DP) :: a(:)
 
    this%times = [this%times, a]
    call this%sort()

increasing()

logical(lgp) function timeselectmodule::increasing

(

class(timeselecttype)

this

)

Returns true if the times array strictly increases, as well as if the times array is empty, or not yet allocated. Note that this function operates on the entire times array, not the current selection. Note also that this function conducts exact comparisons; deduplication with tolerance must be done manually.

Definition at line 82 of file TimeSelect.f90.

    class(TimeSelectType) :: this
    logical(LGP) :: inc
    integer(I4B) :: i
    real(DP) :: l, t
 
    inc = .true.
    if (.not. allocated(this%times)) return
    do i = 1, size(this%times)
      t = this%times(i)
      if (i /= 1) then
        if (l >= t) then
          inc = .false.
          return
        end if
      end if
      l = t
    end do

init()

subroutine timeselectmodule::init

(

class(timeselecttype)

this

)

Definition at line 65 of file TimeSelect.f90.

    class(TimeSelectType) :: this
 
    if (allocated(this%times)) deallocate (this%times)
    allocate (this%times(0))
    this%selection = (/0, 0/)

log()

subroutine timeselectmodule::log	(	class(timeselecttype)	this,
		integer(i4b), intent(in)	iout,
		character(len=*), intent(in)	verb
	)

Parameters

	this	this instance
[in]	iout	output unit
[in]	verb	selection name

Definition at line 103 of file TimeSelect.f90.

    ! dummy
    class(TimeSelectType) :: this !< this instance
    integer(I4B), intent(in) :: iout !< output unit
    character(len=*), intent(in) :: verb !< selection name
    ! formats
    character(len=*), parameter :: fmt = &
      &"(6x,'THE FOLLOWING TIMES WILL BE ',A,': ',50(G0,' '))"
 
    if (this%any()) then
      write (iout, fmt) verb, this%times(this%selection(1):this%selection(2))
    else
      write (iout, "(a,1x,a)") 'NO TIMES WILL BE', verb
    end if

select()

subroutine timeselectmodule::select	(	class(timeselecttype)	this,
		real(dp), intent(in)	t0,
		real(dp), intent(in)	t1,
		logical(lgp), intent(inout), optional	changed
	)

Finds and stores the index of the first time at the same instant as or following the start time, and of the last time at the same instant as or preceding the end time. Allows filtering the times for e.g. a particular stress period and time step. Array indices are assumed to start at 1. If no times are found to fall within the selection (i.e. it falls entirely between two consecutive times or beyond the time range), indices are set to [-1, -1].

The given start and end times are first checked against currently stored indices to avoid recalculating them if possible, allowing multiple consuming components (e.g., subdomain particle tracking solutions) to share the object efficiently, provided all proceed through stress periods and time steps in lockstep, i.e. they all solve any given period/step before any will proceed to the next.

Definition at line 136 of file TimeSelect.f90.

    ! dummy
    class(TimeSelectType) :: this
    real(DP), intent(in) :: t0, t1
    logical(LGP), intent(inout), optional :: changed
    ! local
    integer(I4B) :: i, i0, i1
    integer(I4B) :: l, u, lp, up
    real(DP) :: t
 
    ! by default, need to iterate over all times
    i0 = 1
    i1 = size(this%times)
 
    ! if no times fall within the slice, set to [-1, -1]
    l = -1
    u = -1
 
    ! previous bounding indices
    lp = this%selection(1)
    up = this%selection(2)
 
    ! Check if we can reuse either the lower or upper bound.
    ! The lower doesn't need to change if it indexes the 1st
    ! time simultaneous with or later than the slice's start.
    ! The upper doesn't need to change if it indexes the last
    ! time before or simultaneous with the slice's end.
    if (lp > 0 .and. up > 0) then
      if (lp > 1) then
        if (this%times(lp - 1) < t0 .and. &
            this%times(lp) >= t0) then
          l = lp
          i0 = l
        end if
      end if
      if (up > 1 .and. up < i1) then
        if (this%times(up + 1) > t1 .and. &
            this%times(up) <= t1) then
          u = up
          i1 = u
        end if
      end if
      if (l == lp .and. u == up) then
        this%selection = (/l, u/)
        if (present(changed)) changed = .false.
        return
      end if
    end if
 
    ! recompute bounding indices if needed
    do i = i0, i1
      t = this%times(i)
      if (l < 0 .and. t >= t0 .and. t <= t1) l = i
      if (l > 0 .and. t <= t1) u = i
    end do
    this%selection = (/l, u/)
    if (present(changed)) changed = l /= lp .or. u /= up
 

sort()

subroutine timeselectmodule::sort

(

class(timeselecttype)

this

)

Note that this routine does NOT remove duplicate times. Call increasing() to check for duplicates in the array.

Definition at line 252 of file TimeSelect.f90.

    class(TimeSelectType) :: this
    integer(I4B), allocatable :: indx(:)
 
    allocate (indx(size(this%times)))
    call qsort(indx, this%times)
    deallocate (indx)