tracing Module Reference

Detailed Description

Tracing implementation for the Open FUSION Toolkit.

The default tracing implementation uses LSODE as the ode solver for advancing field lines.

Authors

Chris Hansen

Date

Feburary 2012

Data Types
type	oft_tracer
	Abstract class for OFT tracers. More...
type	oft_tracer_euler
	Tracer implementation using an Euler method. More...
type	oft_tracer_lsode
	Tracer implementation using LSODE as the ODE solver package. More...
type	oft_tracer_ptr
	Tracer pointer. More...
interface	tracer_copy
	Abstract interface for creating bare copies of a tracer object. More...
interface	tracer_recv
	Abstract interface for recieving tracer information from a different domain. More...
interface	tracer_send
	Abstract interface for sending tracer information to a new domain. More...
interface	tracer_setup
	Abstract interface for tracer setup with a new start point. More...
interface	tracer_step
	Abstract interface for advancing a tracer by one step. More...
interface	tracer_ydot
	Abstract interface for general tracer ODE function. More...

Functions/Subroutines
subroutine	create_tracer (tracer, type)
	Create tracer object.
subroutine	set_timeout (new_timeout)
	Set timeout for tracing calls.
character(len=40) function	termination_reason (status_flag)
	Get string describing tracer exit reason.
subroutine	tracer_euler_copy (self, new)
	Create a bare copy of the LSODE tracer object.
subroutine	tracer_euler_delete (self)
	Delete internal storage and reset counters.
type(mpi_request) integer(i4) function, dimension(2)	tracer_euler_recv (self, proc)
	Recieve tracer information from a different domain.
subroutine	tracer_euler_save (self)
	Advancing tracer by one step using LSODE.
type(mpi_request) integer(i4) function, dimension(2)	tracer_euler_send (self, proc)
	Send tracer information to a new domain.
subroutine	tracer_euler_setup (self, y, cell, init)
	Setup a EULER tracer with a new starting point.
subroutine	tracer_euler_step (self)
	Advancing tracer by one step using EULER.
logical function	tracer_lsode_cast (self, source)
	Cast a tracer object to a oft_tracer_lsode.
subroutine	tracer_lsode_copy (self, new)
	Create a bare copy of the LSODE tracer object.
subroutine	tracer_lsode_delete (self)
	Delete internal storage and reset counters.
subroutine	tracer_lsode_eval_b (neq, t, y, ydot)
	Field evaluation callback used by dlsode
type(mpi_request) integer(i4) function, dimension(2)	tracer_lsode_recv (self, proc)
	Recieve tracer information from a different domain.
subroutine	tracer_lsode_save (self)
	Save LSODE common block data to arrays.
type(mpi_request) integer(i4) function, dimension(2)	tracer_lsode_send (self, proc)
	Send tracer information to a new domain.
subroutine	tracer_lsode_setup (self, y, cell, init)
	Setup a LSODE tracer with a new starting point.
subroutine	tracer_lsode_step (self)
	Advancing tracer by one step using LSODE.
subroutine	tracing_line (tracer, pt, filename)
	Advance tracer from a single point and save field line to specified file.
subroutine	tracing_poincare (tracer, pts, n, filename, offset, pcoord, qfile)
	Advance a group of tracers while accumulating crossing of the yz-plane into a poincare section.
subroutine	tracing_poincare_master (tracers, n)
	Manage tracer communication and status for parallel tracing.
subroutine	tracing_poincare_worker (tracers, n, ibuff, outbuff, nbuff, nloc, xcross, icoord, qbuff)
	Advance a group of tracers on the local domain while accumulating crossings of the yz-plane into a buffer array.

Variables
class(oft_tracer), pointer	active_tracer => NULL()
	Active tracer for current thread.
integer(i4), parameter, private	nlocpts = 1E6
	Number of points in processor buffers.
real(r8), parameter, private	offmesh_tol = 1.d-2
	Tolerance for cell logical coordinate test.
logical, private	test_timeout = .FALSE.
	Timeout has passed?
real(r8), private	timeout = 60.d0
	Timeout for tracing calls (seconds)
type(oft_timer), private	timeout_timer
	Timer for timeout tests.
integer(i4), parameter, private	tracer_error_blimit = -4
	Tracer exceeded buffer size.
integer(i4), parameter, private	tracer_error_exit = -1
	Tracer exited mesh.
integer(i4), parameter, private	tracer_error_fail = -6
	Tracer failed.
integer(i4), parameter, private	tracer_error_slimit = -3
	Tracer exceeded maxtrans
integer(i4), parameter, private	tracer_error_time = -5
	Tracer exceeded timeout.
integer(i4), parameter, private	tracer_error_tlimit = -2
	Tracer exceeded maxsteps
integer(i4), parameter, private	tracer_init = 99
	Tracer is awaiting setup.
integer(i4), parameter, private	tracer_recv_active = 21
	Tracer is waiting for recv to complete.
integer(i4), parameter, private	tracer_recv_ready = 20
	Tracer is ready to recv.
integer(i4), parameter, private	tracer_send_active = 11
	Tracer is waiting for send to complete.
integer(i4), parameter, private	tracer_send_ready = 10
	Tracer is ready to send.
integer(i4), parameter, private	tracer_trace_active = 2
	Tracer is being advanced.
integer(i4), parameter, private	tracer_trace_ready = 1
	Tracer is ready to advance.

Function/Subroutine Documentation

create_tracer()

subroutine create_tracer	(	class(oft_tracer), intent(out), pointer	tracer,
		integer(i4), intent(in)	type
	)

Create tracer object.

The following tracer types are currently available:

• (1) LSODE tracer, using LSODEs non-stiff Adam's method
• (2) \ref tracing::oft_tracer_lsode "LSODE tracer", using LSODEs stiff BDF method
• (3) EULER tracer, using an adaptive step size

  Parameters

  [out]	tracer	Tracer object
  [in]	type	Tracer type key

set_timeout()

subroutine set_timeout

(

real(r8), intent(in)

new_timeout

)

Set timeout for tracing calls.

Parameters

[in]

timeout

New timeout (seconds)

termination_reason()

character(len=40) function termination_reason

(

integer(i4), intent(in)

status_flag

)

Get string describing tracer exit reason.

Parameters

[in]

status_flag

Tracer exit status

Returns

Tracer exit reason

tracer_euler_copy()

subroutine tracer_euler_copy	(	class(oft_tracer_euler), intent(in)	self,
		class(oft_tracer), intent(out), pointer	new
	)

Create a bare copy of the LSODE tracer object.

Parameters

[out]	new	Copy of object with same tolerances and field interpolation object
[in]	self	Tracer object
[out]	new	Copy of object with same tolerances and referenced interpolator

tracer_euler_delete()

subroutine tracer_euler_delete

(

class(oft_tracer_euler), intent(inout)

self

)

Delete internal storage and reset counters.

Parameters

[in,out]

self

Tracer object

tracer_euler_recv()

type(mpi_request) integer(i4) function, dimension(2) tracer_euler_recv	(	class(oft_tracer_euler), intent(inout)	self,
		integer(i4), intent(in)	proc
	)

Recieve tracer information from a different domain.

This subroutine sets up non-blocking MPI recieve requests and unpacks the resulting data sent by tracer_euler_send

Parameters

[in,out]	self	Tracer object
[in]	proc	Processor ID to receive tracer information from

Returns

MPI request IDs for transfer of real and integer data (2)

tracer_euler_save()

subroutine tracer_euler_save

(

class(oft_tracer_euler), intent(inout)

self

)

Advancing tracer by one step using LSODE.

Parameters

[in,out]

self

Tracer object

tracer_euler_send()

type(mpi_request) integer(i4) function, dimension(2) tracer_euler_send	(	class(oft_tracer_euler), intent(inout)	self,
		integer(i4), intent(in)	proc
	)

Send tracer information to a new domain.

This subroutine transfers the number of steps and tracer position. Data is packed into a single array for each real and integer data types and non-blocking MPI sends are created to transfer each array

Parameters

[in,out]	self	Tracer object
[in]	proc	Processor ID to send tracer information to

Returns

MPI request IDs for transfer of real and integer data (2)

tracer_euler_setup()

subroutine tracer_euler_setup	(	class(oft_tracer_euler), intent(inout)	self,
		real(r8), dimension(:), intent(in)	y,
		integer(i4), intent(in), optional	cell,
		logical, intent(in), optional	init
	)

Setup a EULER tracer with a new starting point.

Parameters

[in,out]	self	Tracer object
[in]	y	New start point [3]
[in]	cell	Guess cell for use in mesh_findcell (optional)
[in]	init	Flag indicating tracer is starting a new trace and all counts should be set to zero (optional)

tracer_euler_step()

subroutine tracer_euler_step

(

class(oft_tracer_euler), intent(inout)

self

)

Advancing tracer by one step using EULER.

Parameters

[in,out]

self

Tracer object

tracer_lsode_cast()

logical function tracer_lsode_cast	(	class(oft_tracer_lsode), intent(out), pointer	self,
		class(oft_tracer), intent(in), target	source
	)

Cast a tracer object to a oft_tracer_lsode.

The source matrix must be oft_tracer_lsode or a child class, otherwise pointer will be returned as null and success == .FALSE.

Parameters

[out]	self	Reference to source object with desired class
[in]	source	Source tracer to cast

Returns

Cast success flag

tracer_lsode_copy()

subroutine tracer_lsode_copy	(	class(oft_tracer_lsode), intent(in)	self,
		class(oft_tracer), intent(out), pointer	new
	)

Create a bare copy of the LSODE tracer object.

Parameters

[in]	self	Tracer object
[out]	new	Copy of object with same tolerances and referenced interpolator

tracer_lsode_delete()

subroutine tracer_lsode_delete

(

class(oft_tracer_lsode), intent(inout)

self

)

Delete internal storage and reset counters.

Parameters

[in,out]

self

Tracer object

tracer_lsode_eval_b()

subroutine tracer_lsode_eval_b	(	integer, intent(in)	neq,
		real(r8), intent(in)	t,
		real(r8), dimension(neq), intent(in)	y,
		real(r8), dimension(neq), intent(out)	ydot
	)

Field evaluation callback used by dlsode

See tracer_lsode_step

tracer_lsode_recv()

type(mpi_request) integer(i4) function, dimension(2) tracer_lsode_recv	(	class(oft_tracer_lsode), intent(inout)	self,
		integer(i4), intent(in)	proc
	)

Recieve tracer information from a different domain.

This subroutine sets up non-blocking MPI recieve requests and unpacks the resulting data sent by tracer_lsode_send

Parameters

[in,out]	self	Tracer object
[in]	proc	Processor ID to receive tracer information from

Returns

MPI request IDs for transfer of real and integer data (2)

tracer_lsode_save()

subroutine tracer_lsode_save

(

class(oft_tracer_lsode), intent(inout)

self

)

Save LSODE common block data to arrays.

Parameters

[in,out]

self

Tracer object

tracer_lsode_send()

type(mpi_request) integer(i4) function, dimension(2) tracer_lsode_send	(	class(oft_tracer_lsode), intent(inout)	self,
		integer(i4), intent(in)	proc
	)

Send tracer information to a new domain.

This subroutine transfers the number of steps, tracer position and LSODE working arrays. Data is packed into a single array for each real and integer data types and non-blocking MPI sends are created to transfer each array

Parameters

[in,out]	self	Tracer object
[in]	proc	Processor ID to send tracer information to

Returns

MPI request IDs for transfer of real and integer data (2)

tracer_lsode_setup()

subroutine tracer_lsode_setup	(	class(oft_tracer_lsode), intent(inout)	self,
		real(r8), dimension(:), intent(in)	y,
		integer(i4), intent(in), optional	cell,
		logical, intent(in), optional	init
	)

Setup a LSODE tracer with a new starting point.

Parameters

[in,out]	self	Tracer object
[in]	y	New start point [3]
[in]	cell	Guess cell for use in mesh_findcell (optional)
[in]	init	Flag indicating tracer is starting a new trace and all counts should be set to zero (optional)

tracer_lsode_step()

subroutine tracer_lsode_step

(

class(oft_tracer_lsode), intent(inout)

self

)

Advancing tracer by one step using LSODE.

Parameters

[in,out]

self

Tracer object

tracing_line()

subroutine tracing_line	(	class(oft_tracer), intent(in), target	tracer,
		real(r8), dimension(:), intent(in)	pt,
		character(len=*), intent(in)	filename
	)

Advance tracer from a single point and save field line to specified file.

Parameters

[in]	tracer	Tracer to use for field line trace
[in]	pt	Starting point for trace [3]
[in]	filename	Filename to save field line data to

tracing_poincare()

subroutine tracing_poincare	(	class(oft_tracer), intent(in)	tracer,
		real(r8), dimension(3,n), intent(in)	pts,
		integer(i4), intent(in)	n,
		character(len=*), intent(in)	filename,
		real(r8), intent(in), optional	offset,
		integer(i4), intent(in), optional	pcoord,
		character(len=*), intent(in), optional	qfile
	)

Advance a group of tracers while accumulating crossing of the yz-plane into a poincare section.

Tracing parallelizes across domains and streamlines. Each domain advances fieldlines in parallel using local worker threads. Communication between domains is handled by a master thread.

Note

When the local buffer for point crossings is exceeded tracing will exit. The size of the point buffer is set by the private module variable nlocpts

Parameters

[in]	tracer	Base tracer for field line advance
[in]	pts	Launch points for field lines [3,n]
[in]	n	Number of launch points
[in]	filename	Filename for section data
[in]	offset	X-intercept of section plane (optional, default: 0.0)
[in]	pcoord	Coordinate index orthogonal to section plane (optional, default: 1)
[in]	qfile	Filename for approximate safety factor, must be z-axis oriented (optional)

tracing_poincare_master()

subroutine tracing_poincare_master	(	type(oft_tracer_ptr), dimension(n), intent(inout), target	tracers,
		integer(i4), intent(in)	n
	)

Manage tracer communication and status for parallel tracing.

Parameters

[in,out]	tracers	Array of all active tracers [n]
[in]	n	Number of active tracers

tracing_poincare_worker()

subroutine tracing_poincare_worker	(	type(oft_tracer_ptr), dimension(n), intent(inout), target	tracers,
		integer(i4), intent(in)	n,
		integer(i4), dimension(nbuff), intent(inout)	ibuff,
		real(r8), dimension(3,nbuff), intent(inout)	outbuff,
		integer(i4), intent(in)	nbuff,
		integer(i4), intent(inout)	nloc,
		real(r8), intent(in), optional	xcross,
		integer(i4), intent(in), optional	icoord,
		real(r8), dimension(2,n), intent(inout), optional	qbuff
	)

Advance a group of tracers on the local domain while accumulating crossings of the yz-plane into a buffer array.

Parameters

[in,out]	tracers	Array of all active tracers [n]
[in]	n	Number of active tracers
[in,out]	ibuff	Local buffer of tracer indices [nbuff]
[in,out]	outbuff	Local buffer of plane crossings [3,nbuff]
[in]	nbuff	Size of local buffer
[in,out]	nloc	Number of crossings on local task
[in]	xcross	X-intercept of section plane (optional, default: 0.0)
[in]	icoord	Coordinate index orthogonal to section plane (optional, default: 1)
[in,out]	qbuff	Buffer for q information

Variable Documentation

active_tracer

class(oft_tracer), pointer active_tracer => NULL()

Active tracer for current thread.

nlocpts

integer(i4), parameter, private nlocpts = 1E6

private

Number of points in processor buffers.

offmesh_tol

real(r8), parameter, private offmesh_tol = 1.d-2

private

Tolerance for cell logical coordinate test.

test_timeout

logical, private test_timeout = .FALSE.

private

Timeout has passed?

timeout

real(r8), private timeout = 60.d0

private

Timeout for tracing calls (seconds)

timeout_timer

type(oft_timer), private timeout_timer

private

Timer for timeout tests.

tracer_error_blimit

integer(i4), parameter, private tracer_error_blimit = -4

private

Tracer exceeded buffer size.

tracer_error_exit

integer(i4), parameter, private tracer_error_exit = -1

private

Tracer exited mesh.

tracer_error_fail

integer(i4), parameter, private tracer_error_fail = -6

private

Tracer failed.

tracer_error_slimit

integer(i4), parameter, private tracer_error_slimit = -3

private

Tracer exceeded maxtrans

tracer_error_time

integer(i4), parameter, private tracer_error_time = -5

private

Tracer exceeded timeout.

tracer_error_tlimit

integer(i4), parameter, private tracer_error_tlimit = -2

private

Tracer exceeded maxsteps

tracer_init

integer(i4), parameter, private tracer_init = 99

private

Tracer is awaiting setup.

tracer_recv_active

integer(i4), parameter, private tracer_recv_active = 21

private

Tracer is waiting for recv to complete.

tracer_recv_ready

integer(i4), parameter, private tracer_recv_ready = 20

private

Tracer is ready to recv.

tracer_send_active

integer(i4), parameter, private tracer_send_active = 11

private

Tracer is waiting for send to complete.

tracer_send_ready

integer(i4), parameter, private tracer_send_ready = 10

private

Tracer is ready to send.

tracer_trace_active

integer(i4), parameter, private tracer_trace_active = 2

private

Tracer is being advanced.

tracer_trace_ready

integer(i4), parameter, private tracer_trace_ready = 1

private

Tracer is ready to advance.