particle_tracerET

Zachariah B. Etienne <zachetie *at* gmail *dot* com >
Documentation by Leonardo R. Werneck <wernecklr *at* gmail *dot* com >

Feb 2, 2022

Abstract

particle_tracerET is used to track the motion of test particles that comove with fluid flows. With this data once can generate accurate, self-consistent visualizations of magnetic field lines over the course of e.g., a binary neutron star simulation.

1 Overview

particle_tracerET tracks the motion of test particles that comove with fluid flows. As magnetic field lines remain attached to the fluid elements they thread in the MHD approximation, this thorn provides essential functionality for self-consistent visualizations of the dynamics of magnetic field lines (i.e., magnetic field vector streamlines) over time in a GRMHD simulation.

Magnetic field lines can be visualized by first picking a fluid element (i.e., a point in space at which the fluid density and magnetic fields are nonzero), and then generating the vector field streamline according to the magnetic field vector.

The instantaneous velocity of these test particles is given by the velocity in the induction equation \(v^{i} = u^{i}/u^{0}\) at the location of each test particle, so this thorn tracks particle dynamics by solving the ordinary differential equations (ODEs): \begin {equation} \frac {dx}{dt} = v^{x}\;,\quad \frac {dy}{dt} = v^{y}\;,\quad \frac {dz}{dt} = v^{z}\;, \end {equation} subject to the initial conditions \begin {equation} x(0) = x_{0}\;,\quad y(0) = y_{0}\;,\quad z(0) = z_{0}\;. \end {equation} The above initial value problem is solved for each particle using an RK4 ODE integration, interpolating the velocity vector at each particle position, at each RK4 substep. The frequency of RK4 substeps generally can be far lower than that of the global simulation RK substepping, and is set to be every “update_RK4_freqcctk_iteration’s.

The velocities \(v^{i} = u^{i}/u^{0}\) are computed using as inputs the HydroBase velocity and ADMBase spacetime metric variables. particle_tracerET stores \(v^{i}\) to MHDvx, MHDvy, and MHDvz.

Note that the velocities above differ from the HydroBase velocities, the so-called Valencia three-velocity, \(v^{i}_{(n)}\). The relationship between \(v^{i}\) and \(v^{i}_{(n)}\) is given by (see e.g., [1]) \begin {equation} v^{i} = \alpha v^{i}_{(n)} - \beta ^{i}\;. \end {equation}

Initially, particles are seeded inside a sphere of radius \(R\) located at position \((X,Y,Z)\). The parameters that correspond to \(R\), \(X\), \(Y\), and \(Z\) are given in Table 1.






Variable Thorn parameter


\(R\) seed_particles_inside_sphere__radius
\(X\) seed_particles_inside_sphere__x_coord
\(Y\) seed_particles_inside_sphere__y_coord
\(Z\) seed_particles_inside_sphere__z_coord





Once the position of the particle is known, it is accepted by the algorithm with probability \begin {equation} P = \left [\frac {\rho (\vec {x}_{\rm p})}{\rho _{\rm max}}\right ]^{C}\;, \end {equation} where \(\rho (\vec {x}_{\rm p})\) is the density interpolated at the particle position \(\vec {x}_{\rm p}\), \(\rho _{\rm max}\) is the maximum density on the computational domain, and \(C\) is the central condensation parameter.

2 Basic usage

The following snippet shows what to add to your parfile in order to setup the thorn to seed 5000 particles inside a sphere of radius \(R=50\) centered at \((X,Y,Z)=(0,0,0)\) (default). The maximum density is specified as well, which will affect the probability \(P\) with which the particles are accepted by the algorithm. The particle positions are then updated once every 16 time steps by solving the ODEs above.

ActiveThorns = "particle_tracerET"
particle_tracerET::num_particles                        = 5000
particle_tracerET::density_max                          = 0.000959482674936154
particle_tracerET::seed_particles_inside_sphere__radius = 50
particle_tracerET::update_RK4_freq                      = 16

References

[1]   

Z. B. Etienne, V. Paschalidis, R. Haas, P. Mösta, & S. L. Shapiro, IllinoisGRMHD: an open-source, user-friendly GRMHD code for dynamical spacetimes, Classical and Quantum Gravity, 32(17), 175009 (2015).

3 Parameters




central_condensation_parameter
Scope: private  REAL



Description: Probability of accepting random point x,y,z = (density(x,y,z)/density_max)ĉentral_condensation_paramter



Range   Default: 1.0
*:*
Any number






debug
Scope: private  INT



Description: Evolve analytic velocity data and verify that the RK4 solution is consistent to 4th order.



Range   Default: (none)
0:1
0 = disable; 1=enable debug






density_max
Scope: private  REAL



Description: Maximum density within sphere.



Range   Default: (none)
*:*
Any number






interpolator_name
Scope: private  STRING



Description: Which interpolator should I use



Range   Default: Lagrange polynomial interpolation
.+
Any nonempty string






interpolator_pars
Scope: private  STRING



Description: Parameters for the interpolator



Range   Default: order=4
.*
”Any string that Util_TableSetFromStr ing() will take”






num_particles
Scope: private  INT



Description: Number of particles



Range   Default: (none)
0:*
zero (disable particle generation), or some other number






out_of_bounds_xyz
Scope: private  REAL



Description: fabs(x) > out_of_bounds_xyz —— fabs(y) > out_of_bounds_xyz —— fabs(z) > out_of_bounds_xyz -> OUT OF BOUNDS.



Range   Default: 800.0
0:*
Any number






outdir
Scope: private  STRING



Description: Directory for particle tracerET output files, overrides IO::out_dir



Range   Default: (none)
ˆ$
An empty string to choose the default from IO::out_dir
.+
A valid directory name






output_file_format
Scope: private  STRING



Description: File format (ASCII or Binary)



Range   Default: ascii
ascii
ASCII format
binary
Binary format






output_format
Scope: private  STRING



Description: Output format



Range   Default: default
default
First column is time then particles positions.
with_iterations
First column is iteration, second column is time, then particles positions.






output_four_velocity_u4d
Scope: private  BOOLEAN



Description: Whether or not to output the particles’ covariant four-velocity



  Default: no






output_four_velocity_u4u
Scope: private  BOOLEAN



Description: Whether or not to output the particles’ contravariant four-velocity



  Default: no






output_freq
Scope: private  INT



Description: How often to do particle tracer output, overrides IO::out_every



Range   Default: -3
-3
Default value: 2*update_RK4_freq
-2
Use IO::out_every
1:*
Output every so many time steps
-1:0
No output






seed_particles_inside_sphere__radius
Scope: private  REAL



Description: radius of sphere within which to seed particles



Range   Default: (none)
0:*
Any number






seed_particles_inside_sphere__x_coord
Scope: private  REAL



Description: x-coord of sphere center, within which to seed particles



Range   Default: (none)
*:*
Any number






seed_particles_inside_sphere__y_coord
Scope: private  REAL



Description: y-coord of sphere center, within which to seed particles



Range   Default: (none)
*:*
Any number






seed_particles_inside_sphere__z_coord
Scope: private  REAL



Description: z-coord of sphere center, within which to seed particles



Range   Default: (none)
*:*
Any number






start_tracing_particles_iteration
Scope: private  INT



Description: Iteration at which to start tracing particles



Range   Default: (none)
0:*
zero or some positive number.






update_rk4_freq
Scope: private  INT



Description: How often (in units of cctk_iteration) to perform an RK4 substep? Usually 4–8 works best. Definitely choose a power of 2.



Range   Default: (none)
0:4096
zero (disable integration) or some other number






verbose
Scope: private  INT



Description: Set verbosity level: 1=useful info; 2=moderately annoying (though useful for debugging)



Range   Default: 1
0:2
0 = no output; 1=useful info; 2=moderately annoying (though useful for debugging)






out_dir
Scope: shared from IO STRING






out_every
Scope: shared from IO INT



4 Interfaces

General

Implements:

particle_traceret

Inherits:

grid

hydrobase

admbase

Grid Variables

4.0.1 PRIVATE GROUPS




  Group Names     Variable Names     Details   




rk4iterationcountervar   compact0
RK4IterationCounter   descriptionCounter that keeps track of which RK4 iteration we are on.
  dimensions0
  distributionCONSTANT
  group typeSCALAR
  timelevels1
 variable typeINT




auxiterationcountervars   compact0
file_output_freq   descriptionAuxiliary variables
initial_number_of_active_refinement_levels  dimensions0
  distributionCONSTANT
  group typeSCALAR
  timelevels1
 variable typeINT




rk4_delta_time RK4_delta_time   compact0
  dimensions0
  distributionCONSTANT
  group typeSCALAR
  timelevels1
 variable typeREAL




particle_position_arrays   compact0
particle_position_x   descriptionPosition of each particle
particle_position_y   dimensions1
particle_position_z   distributionCONSTANT
  group typeARRAY
  sizeNUM_PARTICLES
  timelevels1
 variable typeREAL




particle_velocity_arrays   compact0
particle_velx   descriptionThree-velocity of each particle
particle_vely   dimensions1
particle_velz   distributionCONSTANT
  group typeARRAY
  sizeNUM_PARTICLES
  timelevels1
 variable typeREAL




particle_position_aux_arrays   compact0
particle_position_x_k1   descriptionRK4 coefficients k1
    descriptionk2
particle_position_x_k1   descriptionk3
particle_position_x_k1   descriptionk4 of each particle
particle_position_y_k1   dimensions1
particle_position_z_k1   distributionCONSTANT
particle_position_x_k2   group typeARRAY
particle_position_y_k2   sizeNUM_PARTICLES
particle_position_z_k2   timelevels1
particle_position_x_k3  variable typeREAL








  Group Names     Variable Names    Details   




velocity_consistent_with_mhd_induction_equations   compact0
MHDvx   dimensions3
MHDvy   distributionDEFAULT
MHDvz   group typeGF
  tagsInterpNumTimelevels=1 prolongation=”none” Checkpoint=”no”
  timelevels1
 variable typeREAL




particle_four_velocity_u4u_arrays   compact0
particle_u4U0   descriptionParticle contravariant four-velocity arrays
particle_u4U1   dimensions1
particle_u4U2   distributionCONSTANT
particle_u4U3   group typeARRAY
  sizeNUM_PARTICLES
  timelevels1
 variable typeREAL




particle_four_velocity_u4d_arrays   compact0
particle_u4D0   descriptionParticle covariant four-velocity arrays
particle_u4D1   dimensions1
particle_u4D2   distributionCONSTANT
particle_u4D3   group typeARRAY
  sizeNUM_PARTICLES
  timelevels1
 variable typeREAL




particle_four_velocity_u4u_gridfunctions   compact0
u4U0GF   descriptionParticle contravariant four-velocity gridfunctions
u4U1GF   dimensions3
u4U2GF   distributionDEFAULT
u4U3GF   group typeGF
  tagsInterpNumTimelevels=1 prolongation=”none” Checkpoint=”no”
  timelevels1
 variable typeREAL




particle_four_velocity_u4d_gridfunctions   compact0
u4D0GF   descriptionParticle covariant four-velocity gridfunctions
u4D1GF   dimensions3
u4D2GF   distributionDEFAULT
u4D3GF   group typeGF
  tagsInterpNumTimelevels=1 prolongation=”none” Checkpoint=”no”
  timelevels1
 variable typeREAL




5 Schedule

This section lists all the variables which are assigned storage by thorn WVUThorns_Diagnostics/particle_tracerET. Storage can either last for the duration of the run (Always means that if this thorn is activated storage will be assigned, Conditional means that if this thorn is activated storage will be assigned for the duration of the run if some condition is met), or can be turned on for the duration of a schedule function.

Storage

 

Always: Conditional:
RK4IterationCounterVar AuxIterationCounterVars RK4_delta_time particle_four_velocity_u4D_arrays particle_four_velocity_u4D_gridfunctions
particle_position_arrays particle_four_velocity_u4U_arrays particle_four_velocity_u4U_gridfunctions
particle_velocity_arrays  
particle_position_aux_arrays  
velocity_consistent_with_MHD_induction_equations  
ADMBase::metric[metric_timelevels] ADMBase::curv[metric_timelevels] ADMBase::lapse[lapse_timelevels] ADMBase::shift[shift_timelevels] 
HydroBase::rho[timelevels] HydroBase::press[timelevels] HydroBase::eps[timelevels] HydroBase::vel[timelevels] HydroBase::Bvec[timelevels]  
   

Scheduled Functions

CCTK_INITIAL (conditional)

  particle_traceret_initial

  initialization routines of the particle_traceret thorn

 

 Before:admbase_initialdata
    hydrobase_initial
 Type: group

particle_tracerET_Initial (conditional)

  initializeallparticletracerethelpervars

  check all parameters have been set correctly; initialize particle tracer rk4 iteration counter

 

 Language:c
 Options: global
 Type: function

particle_tracerET_Initial (conditional)

  particle_traceret_file_output_routine_startup

  create directory for file output.

 

 After: initializeallparticletracerethelpervars
 Language:c
 Options: global
 Type: function

CCTK_ANALYSIS (conditional)

  convert_to_mhd_3velocity

  convert to mhd 3 velocity

 

 Before: particle_traceret
 Language:c
 Options: global-early
   loop-local
 Type: function

CCTK_ANALYSIS (conditional)

  particle_traceret

  particle traceret subroutines

 

 Type:group

particle_tracerET (conditional)

  initializeparticlepositions

  initialize particle positions

 

 Language:c
 Options: global-early
 Type: function

particle_tracerET (conditional)

  doonerk4stepforparticletraceret

  do one rk4 step for particle traceret

 

 After: initializeparticlepositions
 Language:c
 Options: global-early
 Type: function

particle_tracerET (conditional)

  compute_particles_four_velocities

  compute particles four velocities

 

 After: doonerk4stepforparticletraceret
 Before: particle_traceret_file_output
 Language:c
 Options: global-early
   loop-local
 Type: function

particle_tracerET

  particle_traceret_file_output

  output particle traceret data to disk

 

 After: doonerk4stepforparticletraceret
 Language:c
 Options: global-early
 Type: function