xx particletracerET

particlextracerET

Zachariah B.xEtienne <zachetie *at* gmail *dot* com >

Documentation by Leonardo R.xWerneck <wernecklr *at* gmail *dot* com >

Feb 2, 2022

Abstract

particlextracerET 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

particlextracerET 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 at the location of each test particle, so this thorn tracks particle dynamics by solving the ordinary differential equations (ODEs): subject to the initial conditions 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_freq”

cctk_iteration’s.

The velocities are computed using as inputs the HydroBase velocity and ADMBase spacetime metric variables.

particlextracerET stores to MHDvx, MHDvy, and MHDvz.

Note that the velocities above differ from the HydroBase velocities, the so-called Valencia three-velocity, . The relationship between and is given by (see e.g.,x[1])

Initially, particles are seeded inside a sphere of radius located at position . The parameters that correspond to , , , and are given in Table 1.

11Variable11  Thorn parameter

11        11seed_particles_inside_sphere__radius
11        11seed_particles_inside_sphere__x_coord
11        11seed_particles_inside_sphere__y_coord
11        11seed_particles_inside_sphere__z_coord

Once the position of the particle is known, it is accepted by the algorithm with probability where is the density interpolated at the particle position , is the maximum density on the computational domain, and 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 centered at (default). The maximum density is specified as well, which will affect the probability 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.

ActiveThornsx=x"particle_tracerET"
particle_tracerET::num_particlesxxxxxxxxxxxxxxxxxxxxxxxx=x5000
particle_tracerET::density_maxxxxxxxxxxxxxxxxxxxxxxxxxxx=x0.000959482674936154
particle_tracerET::seed_particles_inside_sphere__radiusx=x50
particle_tracerET::update_RK4_freqxxxxxxxxxxxxxxxxxxxxxx=x16

References

[1]xxx

Z.xB.xEtienne, V.xPaschalidis, R.xHaas, P.xMxsta, & S.xL.xShapiro, IllinoisGRMHD: an open-source, user-friendly GRMHD code for dynamical spacetimes, Classical and Quantum Gravity, 32(17), 175009 (2015).

3 Parameters

11centralxcondensationxparameter10Scope: privatex01  REAL
11Description:  Probability  of  accepting  random  point  x,y,z  = (density(x,y,z)/densityxmax)xentralxcondensationxparamter
11  Range  10  x01  Default: 1.0
11*:*  10Any number

11debug  10Scope: privatex01  INT

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

11  Range  10  x01  Default: (none)
110:1  100 = disable; 1=enable debug

11

11densityxmax  10Scope: privatex01  REAL

11Description: Maximum density within sphere.

11 Range 10 x01 Default: (none)
11*:*  10Any number

11

11interpolatorxname  10Scope: privatex01  STRING

11Description: Which interpolator should I use

11 Range 10 x01 Default: Lagrange polynomial interpolation
11.+  10Any nonempty string

11

11interpolatorxpars  10Scope: privatex01  STRING

11Description: Parameters for the interpolator

11 Range 10 x01 Default: order=4
11.*  10”Any string that UtilxTableSetFromStr ing() will take”

11

11numxparticles  10Scope: privatex01  INT

11Description: Number of particles

11 Range 10 x01 Default: (none)
110:*  10zero (disable particle generation), or some other number

11

11outxofxboundsxxyz  10Scope: privatex01  REAL

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

11  Range  10  x01  Default: 800.0
110:*  10Any number

11

11outdir  10Scope: privatex01  STRING

11Description: Directory for particle tracerET output files, overrides IO::outxdir

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

11

11outputxfilexformat  10Scope: privatex01  STRING

11Description: File format (ASCII or Binary)

11 Range 10 x01 Default: ascii
11ascii  10ASCII format
11binary  10Binary format

11

11outputxformat  10Scope: privatex01  STRING

11Description: Output format

11 Range 10 x01 Default: default
11default  10First column is time then particles positions.
11withxiterations  10First column is iteration, second column is time, then particles positions.

11

11outputxfourxvelocityxu4d  10Scope: privatex01  BOOLEAN

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

11                           10  x01  Default: no

11outputxfourxvelocityxu4u  10Scope: privatex01  BOOLEAN

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

11                           10  x01  Default: no

11

11outputxfreq  10Scope: privatex01  INT

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

11 Range 10 x01 Default: -3
11-3  10Default value: 2*updatexRK4xfreq
11-2  10Use IO::outxevery
111:*  10Output every so many time steps
11-1:0  10No output

11

11seedxparticlesxinsidexspherexxradius 10Scope: privatex01  REAL

11Description: radius of sphere within which to seed particles

11 Range 10 x01 Default: (none)
110:*  10Any number

11

11seedxparticlesxinsidexspherexxxxcoord 10Scope: privatex01  REAL

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

11 Range 10 x01 Default: (none)
11*:*  10Any number

11

11seedxparticlesxinsidexspherexxyxcoord 10Scope: privatex01  REAL

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

11 Range 10 x01 Default: (none)
11*:*  10Any number

11

11seedxparticlesxinsidexspherexxzxcoord 10Scope: privatex01  REAL

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

11 Range 10 x01 Default: (none)
11*:*  10Any number

11

11startxtracingxparticlesxiteration10Scope: privatex01  INT

11Description: Iteration at which to start tracing particles

11 Range 10 x01 Default: (none)
110:*  10zero or some positive number.

11

11updatexrk4xfreq  10Scope: privatex01  INT

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

11  Range  10  x01  Default: (none)
110:4096  10zero (disable integration) or some other number

11

11verbose  10Scope: privatex01  INT

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

11  Range  10  x01  Default: 1
110:2  100 = no output; 1=useful info; 2=moderately annoying (though useful for debugging)

11

11outxdir  10Scope: shared from IOx01STRING

11outxevery  10Scope: shared from IOx01INT

11

4 Interfaces

General Implements: particlextraceret

Inherits: grid hydrobase admbase

Grid Variables

4.0.1 PRIVATE GROUPS

11 x Group Names x 10  x Variable Names x  x01 Details x11x
11 rk4iterationcountervar 10  x01  compact110
11                        10  RK4IterationCounter  x01 description11Counter that keeps track of which RK4 iteration we are on.
11                        10  x01 dimensions110
11                        10  x01 distribution11CONSTANT
11                        10  x01 group type11SCALAR
11                        10  x01 timelevels111
11                        10  x01variable type11INT
11 auxiterationcountervars 10  x01  compact110
11                        10  filexoutputxfreq  x01 description11Auxiliary variables
11                        10initialxnumberxofxactivexrefinementxlevelsx01 dimensions110
11                        10  x01 distribution11CONSTANT
11                        10  x01 group type11SCALAR
11                        10  x01 timelevels111
11                        10  x01variable type11INT
11 rk4xdeltaxtime 10 RK4xdeltaxtime x01 compact110
11                        10  x01 dimensions110
11                        10  x01 distribution11CONSTANT
11                        10  x01 group type11SCALAR
11                        10  x01 timelevels111
11                        10  x01variable type11REAL
11 particlexpositionxarrays 10  x01  compact110
11                        10  particlexpositionxx  x01 description11Position of each particle
11                        10  particlexpositionxy  x01 dimensions111
11                        10  particlexpositionxz  x01 distribution11CONSTANT
11                        10  x01 group type11ARRAY
11 10 x01 size11NUMxPARTICLES
11                        10  x01 timelevels111
11                        10  x01variable type11REAL
11 particlexvelocityxarrays 10  x01  compact110
11                        10  particlexvelx  x01 description11Three-velocity of each particle
11                        10  particlexvely  x01 dimensions111
11                        10  particlexvelz  x01 distribution11CONSTANT
11                        10  x01 group type11ARRAY
11 10 x01 size11NUMxPARTICLES
11                        10  x01 timelevels111
11                        10  x01variable type11REAL
11particlexpositionxauxxarrays10  x01  compact110
11                        10  particlexpositionxxxk1  x01 description11RK4 coefficients k1
11                        10  x  x01 description11k2
11                        10  particlexpositionxxxk1  x01 description11k3
11                        10  particlexpositionxxxk1  x01 description11k4 of each particle
11                        10  particlexpositionxyxk1  x01 dimensions111
11                        10  particlexpositionxzxk1  x01 distribution11CONSTANT
11                        10  particlexpositionxxxk2  x01 group type11ARRAY
11                        10  particlexpositionxyxk2  x01  size11NUMxPARTICLES
11                        10  particlexpositionxzxk2  x01 timelevels111
11                        10  particlexpositionxxxk3  x01variable type11REAL

11  x Group Names x  10x Variable Names xx01 Details x11x
11velocityxconsistentxwithxmhdxinductionxequations10  x01  compact110
11                                           10  MHDvx  x01 dimensions113
11                                           10  MHDvy  x01 distribution11DEFAULT
11                                           10  MHDvz  x01 group type11GF
11                                           10  x01  tags11InterpNumTimelevels=1 prolongation=”none” Checkpoint=”no”
11                                           10  x01 timelevels111
11                                           10  x01variable type11REAL
11 particlexfourxvelocityxu4uxarrays 10 x01 compact110
11                                           10 particlexu4U0 x01 description11Particle contravariant four-velocity arrays
11                                           10 particlexu4U1 x01 dimensions111
11                                           10 particlexu4U2 x01 distribution11CONSTANT
11                                           10 particlexu4U3 x01 group type11ARRAY
11 10 x01 size11NUMxPARTICLES
11                                           10  x01 timelevels111
11                                           10  x01variable type11REAL
11 particlexfourxvelocityxu4dxarrays 10 x01 compact110
11                                           10 particlexu4D0 x01 description11Particle covariant four-velocity arrays
11                                           10 particlexu4D1 x01 dimensions111
11                                           10 particlexu4D2 x01 distribution11CONSTANT
11                                           10 particlexu4D3 x01 group type11ARRAY
11 10 x01 size11NUMxPARTICLES
11                                           10  x01 timelevels111
11                                           10  x01variable type11REAL
11  particlexfourxvelocityxu4uxgridfunctions  10  x01  compact110
11                                           10  u4U0GF  x01 description11Particle contravariant four-velocity gridfunctions
11                                           10  u4U1GF  x01 dimensions113
11                                           10  u4U2GF  x01 distribution11DEFAULT
11                                           10  u4U3GF  x01 group type11GF
11                                           10  x01  tags11InterpNumTimelevels=1 prolongation=”none” Checkpoint=”no”
11                                           10  x01 timelevels111
11                                           10  x01variable type11REAL
11  particlexfourxvelocityxu4dxgridfunctions  10  x01  compact110
11                                           10  u4D0GF  x01 description11Particle covariant four-velocity gridfunctions
11                                           10  u4D1GF  x01 dimensions113
11                                           10  u4D2GF  x01 distribution11DEFAULT
11                                           10  u4D3GF  x01 group type11GF
11                                           10  x01  tags11InterpNumTimelevels=1 prolongation=”none” Checkpoint=”no”
11                                           10  x01 timelevels111
11                                           10  x01variable type11REAL

11

5 Schedule This section lists all the variables which are assigned storage by thorn WVUThornsxDiagnostics/particlextracerET. 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

11Always:  11Conditional:
11RK4IterationCounterVar AuxIterationCounterVars RK4xdeltaxtime  11particlexfourxvelocityxu4Dxarrays particlexfourxvelocityxu4Dxgridfunctions
11particlexpositionxarrays  11particlexfourxvelocityxu4Uxarrays particlexfourxvelocityxu4Uxgridfunctions
11particlexvelocityxarrays  11x
11particlexpositionxauxxarrays  11x
11velocityxconsistentxwithxMHDxinductionxequations  11x
11ADMBase::metric[metricxtimelevels] ADMBase::curv[metricxtimelevels] ADMBase::lapse[lapsextimelevels] ADMBase::shift[shiftxtimelevels]11x
11HydroBase::rho[timelevels] HydroBase::press[timelevels] HydroBase::eps[timelevels] HydroBase::vel[timelevels] HydroBase::Bvec[timelevels] 11x

11x  11x

11

Scheduled Functions

CCTKxINITIAL (conditional) x particlextraceretxinitial x initialization routines of the particlextraceret thorn x

11x11Before:11admbasexinitialdata
11 x 11x  11hydrobasexinitial
11 x 11Type: 11group

11

particlextracerETxInitial (conditional) x initializeallparticletracerethelpervars x check all parameters have been set correctly; initialize particle tracer rk4 iteration counter x

11x11Language:11c
11 x 11Options: 11global
11 x 11Type: 11function

11

particlextracerETxInitial (conditional) x particlextraceretxfilexoutputxroutinexstartup x create directory for file output. x

11x11After: 11initializeallparticletracerethelpervars
11 x 11Language:11c
11 x 11Options: 11global
11 x 11Type: 11function

11

CCTKxANALYSIS (conditional) x convertxtoxmhdx3velocity x convert to mhd 3 velocity x

11x11Before: 11particlextraceret
11 x 11Language:11c
11 x 11Options: 11global-early
11 x 11x  11loop-local
11 x 11Type: 11function

CCTKxANALYSIS (conditional) x particlextraceret x particle traceret subroutines x

11x11Type:11group

11

particlextracerET (conditional) x initializeparticlepositions x initialize particle positions x

11x11Language:11c
11 x 11Options: 11global-early
11 x 11Type: 11function

11

particlextracerET (conditional) x doonerk4stepforparticletraceret x do one rk4 step for particle traceret x

11x11After: 11initializeparticlepositions
11 x 11Language:11c
11 x 11Options: 11global-early
11 x 11Type: 11function

11

particlextracerET (conditional) x computexparticlesxfourxvelocities x compute particles four velocities x

11x11After: 11doonerk4stepforparticletraceret
11 x 11Before: 11particlextraceretxfilexoutput
11 x 11Language:11c
11 x 11Options: 11global-early
11 x 11x  11loop-local
11 x 11Type: 11function

11

particlextracerET x particlextraceretxfilexoutput x output particle traceret data to disk x

11x11After: 11doonerk4stepforparticletraceret
11 x 11Language:11c
11 x 11Options: 11global-early
11 x 11Type: 11function