E852 documentation: track swimming routines

Introduction

This document describes the routines used to integrate trajectories of charged particles in a magnetic field. These routines also work for neutral particles and in the absense of the magnetic field.

Particles are propagated from a starting point to:

the point of closest approach to a given point in space
the point of intersection with any plane in space
the point of intersection with any cylindrical surface
just some distance along the track

Include files, libraries and initialization

To use routines documented herein, the program should include these include files:

trackswim.h

and be linked with these libraries: (the last two libraries are needed only for the the package initialization code and are not used by the swimming routines themselves)

libUtil.a
libdata.a
libmapmanager_ro.a

To initialize the package, call:


	#include <trackswim.h>
	#include <param.h>

	param_loadDatabase("trackswim",0);
	trackswim_init();

Track definition

These routines can use the following definitions of tracks:

for the trk3_xxx(...) routines, the track is defined as:


	vector3_t v;	the starting point
	vector3_t p;	the momentum
	int charge;	the charge (positive, negative or zero)

for the trk3p_xxx(...) routines, the track is defined as:


	vector3_t v;		the starting point
	vector3_t punit;	the momentum magnitude
	double qp;		charge divided by momentum (positive, negative or zero)

for the trk_xxx(...) routines, the track is defined as an array of 7 numbers:


	(x,y,z,qp,dpx,dpy,dpz),

	where 	x,y,z are the starting point,
		qp is q/p - charge divided by momentum magnitude
		dpx,dpy,dpz are the momentum unit vector

Common arguments and return values

The functions return 0 if success, non 0 in case if failure.

The track returned by the functions is always the point where the swimming had stopped.

The flags argument is normally 0. See the include file for more details.

The box argument defines the boundary volume. Swimming is terminated when the trajectory leaves this volume. To swim without restrictions, set this argument to NULL.

Swimming routines

Swimming to a plane
The target plane is defined as
```
	dnorm - normal vector and
	dpos  - distance from point (0,0,0)
```
Both 'dpos' and 'dnorm' can be either positive or negative.

int trk_swimToPlane(double trk[],const char dname[], const double dnorm[3],double dpos, const trk_planeLimits_t *box); int trk3_swimToPlane(vector3_t *v,vector3_t *p,int charge, const char *planeName, const vector3_t *dnorm,float dpos, const trk_planeLimits_t *box, int flags); int trk3p_swimToPlane(vector3_t *v,vector3_t *punit,float qp, const char *planeName, const vector3_t *dnorm,float dpos, const trk_planeLimits_t *box, int flags);
Swimming to a point
When swimming to a point, the routine attempts to find the point on the trajectory closest to the target point.
The following functions are available:
int trk_swimToV(double trk[], const double target[3]); int trk3_swimToV(vector3_t *v,vector3_t *p,int charge, const vector3_t *target, int flags); int trk3p_swimToV(vector3_t *v,vector3_t *punit,double qp, const vector3_t *target, int flags);
Swimming to a cylinder
[PRELIMINARY as of 1995-May-07]
Notice the lack of trk_swimToCyl function.
/* Routines to swim to a Cylinder * * The target cylinder is defined by it's 'center', 'axis' and 'radius'. */ int trk3_swimToCyl(vector3_t *v,vector3_t *p,int charge, const vector3_t *center,const vector3_t *axis,float radius, int flags); int trk3p_swimToCyl(vector3_t *v,vector3_t *punit,float qp, const vector3_t *center,const vector3_t *axis,float radius, int flags);
To swim a distance along the trajectory
/* Routines to swim a given distance along the track. Distance can be positive or negative */ int trk_swimAway(double trk[],double dist); int trk3_swimAway(vector3_t *v,vector3_t *p,int charge,double dist,int flags); int trk3p_swimAway(vector3_t *v,vector3_t *punit,double qp,double dist,int flags);

Mathematics used inside the package

The package can be configured to use the following trajectory integration methods:

straight line approximation
ptracb(arc approximation)
arc approximation with variable step size

Staight line approximation is slow and inefficient, but very simple to implement and therefore "bug free". It is used mainly to debug the other methods.

ptracb is the tracking code written by S.U.Chung and successfully used to analyze previous MPS experiments. It works fairly well in a uniform magnetic field. It's main flaws are: lack of interface with "boundary conditions", errors in defining the "plane" boundary conditions and lack of variable step size.

The arc approximating method was developed mainly to fix the aforementioned flaws in ptracb. It uses the same arc approximation formulaes as ptracb. One step of either method will give identical results. The main difference is in the way the variable step size and the boundary conditions are implemented.

The variable step size is implemented by sampling the magnetic field along the trajectory and will decrease the step size if it detects "fast changes of the field". If the field "stops changing", the step size is automatically increased. This feature enables to run with larger step size (4 cm versus 1 cm in ptracb). Larger step size means less steps, less calculations of the magnetic field and faster integration.

The "boundary conditions" are implemented by a goal function, which is minimized along the trajectory. For example, when swimming to a plane, this function is defined as "the distance from the current point to the plane". The minimum of the goal function is found by the golden-ratio algorithm for single variable optimization (see: Bronshtein/Semendyayev, "Handbook of Mathematics", section 9.2.2.2.1, published by Van Nostrand Reinhold Company, Inc.).

Config files

The package uses the configuration database trackswim.db, which is extensively self documented.

This file defines, among other things, the step size and the trajectory integration technique.

CO 1995-May-07
//end file

E852 documentation: track swimming routines

Introduction

Include files, libraries and initialization

Track definition

Common arguments and return values

Swimming routines

Swimming to a plane

Swimming to a point

Swimming to a cylinder

To swim a distance along the trajectory

Mathematics used inside the package

Config files