particletracksmodule Module Reference

Particle track output module. More...

Data Types
type	particletrackeventselectiontype
	Selection of particle events. More...
type	particletrackstype
	Particle track output manager. Handles printing as well as writing to files. One output unit can be configured for printing. Multiple files can be configured for writing, with each file optionally associated with a PRP package or with the full model. Events can be filtered by type, so that only certain event types are printed or written to files. Particle events are buffered in memory or in a scratch file, flushed to disk only when the time step is successfully solved for the last time (there may be multiple solves per time step, depending on ATS and Picard options). More...

Functions/Subroutines
subroutine	init_file (this, iun, csv, iprp)
	Initialize a binary or CSV output file. More...
subroutine	init_buffer (this, scratch)
	Initialize the event buffer strategy. More...
subroutine	destroy (this)
	Destroy the particle track manager. More...
subroutine	expand_files (this, increment)
	Grow the array of track files. More...
subroutine	select_events (this, release, featexit, timestep, terminate, weaksink, usertime, subfexit, dropped)
	Pick events to track. More...
logical function	is_selected (this, event)
	Check if a given event code is selected for tracking. More...
subroutine	buffer_event (this, particle, event)
	Buffer an event for deferred write. More...
subroutine	flush_buffer (this)
	Flush the event buffer to disk. More...
subroutine	discard_buffer (this)
	Discard buffered events without writing. More...
logical(lgp) function, public	add_particle_event (context, particle, event)
	Add a particle event to be written to eligible files and printed to an output file unit if requested. This function should be subscribed as an event handler to particle event dispatchers. Events are buffered to be written to output files upon successful completion of a time step when the framework OT hook is executed. More...

Variables
character(len= *), parameter, public	trackheader = 'kper,kstp,imdl,iprp,irpt,ilay,icell,izone,istatus,ireason,trelease,t,x,y,z,name'
character(len= *), parameter, public	trackdtypes = '<i4,<i4,<i4,<i4,<i4,<i4,<i4,<i4,<i4,<i4,<f8,<f8,<f8,<f8,<f8,|S40'

Detailed Description

Each particle's track consists of events reported as the particle is advected through the model domain. Events are snapshots of particle state, along with optional metadata, at a particular moment in time.

Particles have no ID property. A particle can be uniquely identified by the unique combination of its release attributes (model, package, position, and time). This is possible because only one particle may be released from a given point at a given time.

This module consumes particle events and is responsible for writing them to one or more track files, binary or CSV, and for logging the events if requested. Each track file is associated with either a PRP package or with the full PRT model (there may only be 1 such latter).

Events can be buffered in memory or in a scratch file, and in either case are flushed to disk only when a time step successfully finishes.

Function/Subroutine Documentation

add_particle_event()

logical(lgp) function, public particletracksmodule::add_particle_event	(	class(*), pointer	context,
		type(particletype), intent(inout), pointer	particle,
		class(particleeventtype), intent(in), pointer	event
	)

Definition at line 252 of file ParticleTracks.f90.

    class(*), pointer :: context
    type(ParticleType), pointer, intent(inout) :: particle
    class(ParticleEventType), pointer, intent(in) :: event
    logical(LGP) :: handled
 
    select type (context)
    type is (particletrackstype)
      if (context%iout >= 0) &
        call event%log(context%iout)
      if (context%is_selected(event)) &
        call context%buffer_event(particle, event)
      handled = .true.
    end select

Here is the caller graph for this function:

buffer_event()

subroutine particletracksmodule::buffer_event	(	class(particletrackstype)	this,
		type(particletype), intent(in), pointer	particle,
		class(particleeventtype), intent(in), pointer	event
	)

Definition at line 216 of file ParticleTracks.f90.

    class(ParticleTracksType) :: this
    type(ParticleType), pointer, intent(in) :: particle
    class(ParticleEventType), pointer, intent(in) :: event
    type(ParticleTrackRecordType) :: rec
 
    rec%kper = event%kper; rec%kstp = event%kstp
    rec%imdl = event%imdl; rec%iprp = event%iprp
    rec%irpt = event%irpt; rec%ilay = event%ilay
    rec%icu = event%icu; rec%izone = event%izone
    rec%istatus = event%istatus; rec%ireason = event%get_code()
    rec%trelease = event%trelease; rec%ttrack = event%ttrack
    rec%x = event%x; rec%y = event%y; rec%z = event%z
    rec%name = trim(adjustl(particle%name))
 
    call this%buffer%append(rec)

destroy()

subroutine particletracksmodule::destroy

(

class(particletrackstype)

this

)

Definition at line 128 of file ParticleTracks.f90.

    class(ParticleTracksType) :: this
    call this%buffer%destroy()

discard_buffer()

subroutine particletracksmodule::discard_buffer

(

class(particletrackstype)

this

)

Definition at line 241 of file ParticleTracks.f90.

    class(ParticleTracksType) :: this
    call this%buffer%discard()

expand_files()

subroutine particletracksmodule::expand_files	(	class(particletrackstype)	this,
		integer(i4b), intent(in), optional	increment
	)

Definition at line 134 of file ParticleTracks.f90.

    class(ParticleTracksType) :: this
    integer(I4B), optional, intent(in) :: increment
    integer(I4B) :: inclocal, isize, newsize
    type(ParticleTrackFileType), allocatable, dimension(:) :: temp
 
    if (present(increment)) then
      inclocal = increment
    else
      inclocal = 1
    end if
 
    if (allocated(this%files)) then
      isize = size(this%files)
      newsize = isize + inclocal
      allocate (temp(newsize))
      temp(1:isize) = this%files
      deallocate (this%files)
      call move_alloc(temp, this%files)
    else
      allocate (this%files(inclocal))
    end if

flush_buffer()

subroutine particletracksmodule::flush_buffer

(

class(particletrackstype)

this

)

Definition at line 235 of file ParticleTracks.f90.

    class(ParticleTracksType) :: this
    call this%buffer%flush(this%files)

init_buffer()

subroutine particletracksmodule::init_buffer	(	class(particletrackstype)	this,
		logical(lgp), intent(in)	scratch
	)

Definition at line 115 of file ParticleTracks.f90.

    class(ParticleTracksType) :: this
    logical(LGP), intent(in) :: scratch
 
    if (scratch) then
      allocate (scratchfilebuffertype :: this%buffer)
    else
      allocate (memorybuffertype :: this%buffer)
    end if
    call this%buffer%init()

init_file()

subroutine particletracksmodule::init_file	(	class(particletrackstype)	this,
		integer(i4b), intent(in)	iun,
		logical(lgp), intent(in), optional	csv,
		integer(i4b), intent(in), optional	iprp
	)

Definition at line 97 of file ParticleTracks.f90.

    class(ParticleTracksType) :: this
    integer(I4B), intent(in) :: iun
    logical(LGP), intent(in), optional :: csv
    integer(I4B), intent(in), optional :: iprp
    type(ParticleTrackFileType), pointer :: file
 
    call this%expand_files(increment=1)
 
    allocate (file)
    file%iun = iun
    if (present(csv)) file%csv = csv
    if (present(iprp)) file%iprp = iprp
    this%ntrackfiles = size(this%files)
    this%files(this%ntrackfiles) = file

is_selected()

logical function particletracksmodule::is_selected	(	class(particletrackstype), intent(inout)	this,
		class(particleeventtype), intent(in)	event
	)

Definition at line 188 of file ParticleTracks.f90.

    class(ParticleTracksType), intent(inout) :: this
    class(ParticleEventType), intent(in) :: event
 
    select type (event)
    type is (releaseeventtype)
      selected = this%selected%release
    type is (cellexiteventtype)
      selected = this%selected%featexit
    type is (subcellexiteventtype)
      selected = this%selected%subfexit
    type is (timestepeventtype)
      selected = this%selected%timestep
    type is (terminationeventtype)
      selected = this%selected%terminate
    type is (weaksinkeventtype)
      selected = this%selected%weaksink
    type is (usertimeeventtype)
      selected = this%selected%usertime
    type is (droppedeventtype)
      selected = this%selected%dropped
    class default
      call pstop(1, "unknown event type")
      selected = .false.
    end select

Here is the call graph for this function:

select_events()

subroutine particletracksmodule::select_events	(	class(particletrackstype)	this,
		logical(lgp), intent(in)	release,
		logical(lgp), intent(in)	featexit,
		logical(lgp), intent(in)	timestep,
		logical(lgp), intent(in)	terminate,
		logical(lgp), intent(in)	weaksink,
		logical(lgp), intent(in)	usertime,
		logical(lgp), intent(in)	subfexit,
		logical(lgp), intent(in)	dropped
	)

Definition at line 159 of file ParticleTracks.f90.

    class(ParticleTracksType) :: this
    logical(LGP), intent(in) :: release
    logical(LGP), intent(in) :: featexit
    logical(LGP), intent(in) :: timestep
    logical(LGP), intent(in) :: terminate
    logical(LGP), intent(in) :: weaksink
    logical(LGP), intent(in) :: usertime
    logical(LGP), intent(in) :: subfexit
    logical(LGP), intent(in) :: dropped
    this%selected%release = release
    this%selected%featexit = featexit
    this%selected%timestep = timestep
    this%selected%terminate = terminate
    this%selected%weaksink = weaksink
    this%selected%usertime = usertime
    this%selected%subfexit = subfexit
    this%selected%dropped = dropped

Variable Documentation

trackdtypes

character(len=*), parameter, public particletracksmodule::trackdtypes = '<i4,<i4,<i4,<i4,<i4,<i4,<i4,<i4,<i4,<i4,<f8,<f8,<f8,<f8,<f8,|S40'

Definition at line 50 of file ParticleTracks.f90.

  character(len=*), parameter, public :: TRACKDTYPES = &
    '<i4,<i4,<i4,<i4,<i4,<i4,<i4,<i4,&
    &<i4,<i4,<f8,<f8,<f8,<f8,<f8,|S40'

trackheader

character(len=*), parameter, public particletracksmodule::trackheader = 'kper,kstp,imdl,iprp,irpt,ilay,icell,izone,istatus,ireason,trelease,t,x,y,z,name'

Definition at line 46 of file ParticleTracks.f90.

  character(len=*), parameter, public :: TRACKHEADER = &
    'kper,kstp,imdl,iprp,irpt,ilay,icell,izone,&
    &istatus,ireason,trelease,t,x,y,z,name'