Header file for crange. More...

#include <stdio.h>
#include <stdlib.h>
#include <math.h>
#include <string.h>
#include <unistd.h>
#include <errno.h>
#include <time.h>
#include <gsl/gsl_complex.h>
#include <gsl/gsl_complex_math.h>
#include <config.h>
#include <iniparser.h>

Data Structures
struct	TDATA
	Structure containing target data. More...

struct	RANGE_TABLE
	Structure to store range tables. More...

Macros
#define	LOGTENEMIN 0.0

#define	LOGTENEMAX 6.0

#define	MAXE 200

#define	MAXAB 50

#define	M_PI 3.14159265358979323846264338327950288

#define	M_PI_2 1.57079632679489661923132169163975144

#define	M_LN10 2.30258509299404568402

#define	ALPHA 7.29735301383e-3

#define	ATOMICMASSUNIT 931.4943

#define	PROTONMASS 938.2723

#define	ELECTRONMASS 0.511003e+6

#define	SSWITCH_BA 0x001

#define	SSWITCH_SH 0x002

#define	SSWITCH_LE 0x004

#define	SSWITCH_ND 0x008

#define	SSWITCH_EC 0x010

#define	SSWITCH_NS 0x020

#define	SSWITCH_KI 0x040

#define	SSWITCH_RA 0x080

#define	SSWITCH_PA 0x100

#define	SSWITCH_BR 0x200

#define	SSWITCH_DEFAULT (SSWITCH_ND \| SSWITCH_NS)

#define	NAMEWIDTH 8

Typedefs
typedef struct TDATA	tdata
	Define tdata. More...

typedef struct RANGE_TABLE	range_table
	Define range_table. More...

Functions
gsl_complex	complex_hyperg (gsl_complex a, gsl_complex b, gsl_complex z)
	Confluent hypergeometric function. More...

gsl_complex	complex_lngamma (gsl_complex z)
	Complex logarithm of the Gamma function. More...

double	effective_charge (double z0, double e1, double z2, short sswitch)
	Computes effective projectile charge. More...

double	djdx (double e1, double z0, double I0, double f0, double K, short sswitch, tdata *target)
	Computes primary ionization. More...

double	dedx (double e1, double rel0, double z0, double a1, short sswitch, tdata *target)
	Computes dE/dx. More...

double	delta (double g, tdata *target)
	Computes the density effect. More...

double	olddelta (double g, tdata *target)
	Computes an obsolete version of the density effect. More...

double	bma (double z1, double b)
	Computes the Bloch, Mott and Ahlen corrections. More...

double	relbloch (double z12, double b1, double lambda, double theta0)
	Compute the relativistic Bloch correction. More...

double	lindhard (double zz, double aa, double bb, short sswitch)
	Compute the Lindhard-Sørensen correction. More...

double	Fbrems (double x)
	Compute a mathematical function related to bremsstrahlung. More...

double	range (double e, double z1, double a1, short sswitch, tdata target, int tno)
	Computes total range given initial energy. More...

double	qrange (double e, double z1, double a1, short sswitch, tdata *target)
	Computes total range by direct integration of dE/dx. More...

double	benton (double e, double z1, double a1, tdata *target)
	Computes ranges at low energies. More...

double	renergy (double e, double r0, double z1, double a1, short sswitch, tdata *target)
	Extract energies from range tables. More...

void	run_range (FILE finput, FILE foutput, short sswitch, tdata *extratargets)
	Parses and executes the task list. More...

short	init_switch (char *switchfile)
	Initializes the value of of the switch bit field. More...

tdata *	init_target (char *targetfile)
	Read optional target data file. More...

void	init_table (void)
	Initialize range-energy tables. More...

double	energy_table (int i)
	Returns the energy corresponding to a value in a range table. More...

tdata *	find_target (char target, tdata extratargets)
	Finds target data corresponding to a target name. More...

void	print_target (tdata *target)
	Prints a target table entry in INI format. More...

Variables
range_table	trange [MAXAB]
	The range-energy table. More...

Detailed Description

Header file for crange.

This header file collects all the other header files needed to compile crange, as well as all defines, function declarations, etc.

Definition in file crange.h.

Macro Definition Documentation

#define ALPHA 7.29735301383e-3

The fine structure constant.

Definition at line 59 of file crange.h.

#define ATOMICMASSUNIT 931.4943

1 amu in units of MeV/c².

Definition at line 65 of file crange.h.

#define ELECTRONMASS 0.511003e+6

Electron mass in units of eV/c².

Definition at line 77 of file crange.h.

#define LOGTENEMAX 6.0

$\log_{10} E_{\mathrm{max}}$ Maximum energy in units of A MeV.

Definition at line 37 of file crange.h.

#define LOGTENEMIN 0.0

$\log_{10} E_{\mathrm{min}}$ Minimum energy in units of A MeV.

Definition at line 36 of file crange.h.

#define M_LN10 2.30258509299404568402

The value of $\ln 10$ in case it is not defined in math.h

Definition at line 50 of file crange.h.

#define M_PI 3.14159265358979323846264338327950288

The value of pi, in case it is not defined in math.h.

Definition at line 44 of file crange.h.

#define M_PI_2 1.57079632679489661923132169163975144

The value of pi/2, in case it is not defined in math.h.

Definition at line 47 of file crange.h.

#define MAXAB 50

The number of range tables. Arbitrary, but should be larger than the number of targets.

Definition at line 39 of file crange.h.

#define MAXE 200

The number of energies in the range-energy tables.

Definition at line 38 of file crange.h.

#define NAMEWIDTH 8

The maximum number of characters in a target name.

Definition at line 96 of file crange.h.

#define PROTONMASS 938.2723

Proton mass in units of MeV/c².

Definition at line 71 of file crange.h.

#define SSWITCH_BA 0x001

Barkas effect bit.

Definition at line 82 of file crange.h.

#define SSWITCH_BR 0x200

Projectile Bremsstrahlung bit.

Definition at line 91 of file crange.h.

#define SSWITCH_DEFAULT (SSWITCH_ND | SSWITCH_NS)

Default bits set density effect and finite nuclear size.

Definition at line 92 of file crange.h.

#define SSWITCH_EC 0x010

Electron capture switcher bit.

Definition at line 86 of file crange.h.

#define SSWITCH_KI 0x040

Kinetic effect bit.

Definition at line 88 of file crange.h.

#define SSWITCH_LE 0x004

Leung effect bit.

Definition at line 84 of file crange.h.

#define SSWITCH_ND 0x008

Density effect switcher bit.

Definition at line 85 of file crange.h.

#define SSWITCH_NS 0x020

Finite Nuclear Size effect bit.

Definition at line 87 of file crange.h.

#define SSWITCH_PA 0x100

Pair Production energy loss bit.

Definition at line 90 of file crange.h.

#define SSWITCH_RA 0x080

Radiative correction effect bit.

Definition at line 89 of file crange.h.

#define SSWITCH_SH 0x002

Shell effect bit.

Definition at line 83 of file crange.h.

Typedef Documentation

typedef struct RANGE_TABLE range_table

Define range_table.

Define a range_table variable for convenience.

Definition at line 160 of file crange.h.

typedef struct TDATA tdata

Define tdata.

Define a tdata variable for convenience.

Definition at line 141 of file crange.h.

Function Documentation

double benton	(	double	e,
		double	z1,
		double	a1,
		tdata *	target
	)

Computes ranges at low energies.

This function is the result of empirical fits to very low energy 1 A MeV < E < 8 A MeV ion ranges. It follows the methods of Barkas & Berger, [5]. A simplified discussion, with a more complicated formula is given in Benton & Henke, [6]. As yet I know of no nicer way to deal with these low energies.

Parameters

e	Projectile kinetic energy in A MeV.
z1	Projectile charge.
a1	Projectile atomic mass.
target	A pointer to a TDATA structure.

Returns: Projectile range in g cm^-2.

Note: The array join[4] demarcates three energy regions represented by the three sets of coefficients in amn[3][4][4]. The demarcation is variable in order to minimize discontinuities at the boundary. The coefficients in cjoin[2][7], which is used to initialize join[4], are inherited from legacy code; I have not found them in the non-obscure literature. Approximately, the three regions are E < 1 A MeV, 1 < E < 7 A MeV and E > 7 A MeV. I can find no reason why join[4] has four elements and not two.

Definition at line 1247 of file crange.c.

double bma	(	double	z1,
		double	b
	)

Computes the Bloch, Mott and Ahlen corrections.

This function computes the Mott correction of Ahlen, [1], the Bloch correction of F. Bloch, [8], and the Ahlen correction of Ahlen, [3]. All three of these corrections are rendered obsolete by the Lindhard-Sørensen correction, and are included here for historical interest and comparison with older calculations.

Parameters

z1	The projectile charge.
b	The projectile velocity in units of the speed of light (i.e. $\beta = v/c$ ).

Returns: The sum of the Bloch, Mott and Ahlen corrections.

Note: The variables lambda and theta0 are free parameters in the Ahlen correction. Theta0 also appears in the Mott correction. Here I have used Ahlen's recommended values, lambda = 1, theta0 = 0.1. An alternative formula, $\theta_0 = \sqrt{\alpha/(\beta \gamma \lambda)}$ , is suggested by Waddington, Freier & Fixsen, [26].

Warning: The Mott correction has a severely limited range of validity, especially for high charges. It's so bad it can render the calculation not just inaccurate, but unphysical (dE/dx < 0) below about 10 A MeV for uranium. Ahlen recommends turning the Mott correction off for $Z/\beta > 100$ . Here for $Z/\beta > 100$ the Mott correction is given the value at $Z/\beta = 100$ . This prescription is given by Waddington, Freier & Fixsen, [26].

Bug:: Currently, this function is not called by anything.

Definition at line 768 of file crange.c.

gsl_complex complex_hyperg	(	gsl_complex	a,
		gsl_complex	b,
		gsl_complex	z
	)

Confluent hypergeometric function.

Computes the confluent hypergeometric function. All input parameters are complex numbers. Uses the formula:

$M(a,b,z) = 1 + \sum_{n=1} \frac{(a)_n}{(b)_n}\frac{z^n}{n!} ,$

where

$(x)_n \equiv \frac{\Gamma(x+n)}{\Gamma(x)}$

is the Pochhammer Symbol.

Parameters

a	First parameter of the hypergeometric function.
b	Second parameter of the hypergeometric function.
z	A complex number.

Returns: The value , a complex number.

Warning: May not be stable for large values of .

Definition at line 267 of file crange.c.

gsl_complex complex_lngamma ( gsl_complex z )

Complex logarithm of the Gamma function.

Computes the fully complex logarithm of the fully complex Gamma function. Works in all portions of the complex plane, including the negative real axis.

Parameters

z	A complex number.

Returns: $\ln \Gamma(z)$ , a complex number.

Warning: The Gamma function has poles at all integers <= 0.

Definition at line 299 of file crange.c.

double dedx	(	double	e1,
		double	rel0,
		double	z0,
		double	a1,
		short	sswitch,
		tdata *	target
	)

Computes dE/dx.

This is the core of the whole package, the dE/dx calculator. I have based this largely on the work of Salamon, [20]. Values of certain physical constants have been updated, as well as some of the corrections to the basic stopping power formula.

If the restricted energy loss parameter rel0 is non-zero, dedx() computes restricted energy loss instead.

The dE/dx calculator includes a number of effects that are controlled by switches encoded in a bit field. Below we describe each bit field and the effect it controls.

SSWITCH_ND : Density effect version. If this bit is set (which it is by default), a newer version of the density effect is used. See delta() and olddelta() for details.
SSWITCH_SH : Inner shell correction. The inner shell correction is somewhat problematic. It arises when the projectile velocity is comparable to the velocity of inner shell electrons in the target medium. This is discussed by Fano, [9]. The shell correction can be included explicitly using this formula from Barkas & Berger, [5]. Alternatively, the shell correction can be "hidden" in the logarithmic mean ionization potential. Much more work is required before this topic can be fully understood.
SSWITCH_LE : Relativistic shell correction. The Leung, or relativistic shell correction is a small effect which is due to relativistic inner shell electrons in very heavy targets. See Leung, [15], and Leung, [16]. SSWITCH_LE has no effect unless SSWITCH_SH is also turned on.
The Lindhard-Sørensen effect (see lindhard()) is turned on by default. The Bloch, Mott & Ahlen effects are included for historical interestest. Right now these can be turned on by uncommenting a particular section of the code.
SSWITCH_KI : Ultrarelativistic kinematic correction. This an estimate of the ultrarelativistic kinematic correction from Ahlen, [2]. It corrects to the finite mass (as opposed to size) of the nucleus in relativistic electron-nucleus collisions.
SSWITCH_RA : Radiative correction. This is the radiative correction discussed in Ahlen, [2]. It arises from bremsstrahlung of scattered electrons in ultrarelativistic collisions. The form here is that of Jankus, [14]. The parameter Q from that paper is here set equal to the geometric mean between the the electron rest energy and $2 m_e c^2 \gamma$ .
SSWITCH_PA : Slowing due to pair production. This value and the value for the bremsstrahlung correction below are based on the work of Sørensen, [24].
SSWITCH_BR : Slowing due to projectile bremsstrahlung. This version is that of Sørensen, [24], who has shown that this effect is much smaller than the version suggested by Weaver & Westphal, [27].. This is due to their treatment of the projectile and target nuclei as a point particles. That version appeared in some much older versions of this code, but has been replaced with Sørensen's version. We have not yet updated this code to reflect Sørensen's more recent paper [25].
SSWITCH_BA : Barkas effect. This is the Barkas correction as calculated in Jackson & McCarthy, [13]. It is multiplied by a factor of two to bring it into agreement with Lindhard, [18]. It is not, however, equal to the results of Lindhard, and more work is needed to decide which, if any, form is correct. The recommended value seems to be the Jackson & McCarthy result multiplied by two. Jackson & McCarthy do not have reliable values of for . For the purposes of the computation, the cut-off is placed at . I have followed the convention of Salamon in having the Barkas correction multiply just the "Bethe" portion of the stopping logarithm rather than the whole stopping logarithm. As there is considerable disagreement in the literature about the application of correction, and as changing the convention makes makes a difference of less than 1 A MeV even in calculating the energy of stopping uranium, I have chosen to leave it where it is. Furthermore, I have found that a simple power law $V^{-2}$ is adequate to model Jackson & McCarthy's function for , so I have used this instead of the numbers found by reading off one of Jackson & McCarthy's figures (these values are stored in the array fva[10], but only the last value is used).

Parameters

e1	The projectile kinetic energy in A MeV.
rel0	Restricted energy loss parameter in eV.
z0	The projectile charge.
a1	The projectile atomic number.
sswitch	The switch bit field.
target	A pointer to a TDATA structure.

Returns: dE/dx in units of A MeV g^-1 cm²

Definition at line 545 of file crange.c.

double delta	(	double	g,
		tdata *	target
	)

Computes the density effect.

This function implements the density effect correction as formulated in Sternheimer & Peierls, [21] and as extended in Sternheimer, Berger & Seltzer, [22]. This version can distinguish between solids and gasses, and between metals and insulators. For conducting materials, there is a low-energy density effect.

Parameters

g	Projectile Lorentz factor.
target	A pointer to a TDATA structure.

Returns: The value of the density effect.

Definition at line 657 of file crange.c.

double djdx	(	double	e1,
		double	z0,
		double	I0,
		double	f0,
		double	K,
		short	sswitch,
		tdata *	target
	)

Computes primary ionization.

This computes the primary ionization, the number of delta-rays produced per unit length. The formula is based on Bethe [7], as well as Fleischer et al., [10].

Parameters

e1	The projectile kinetic energy in A MeV.
z0	The projectile charge.
I0	The binding energy of outermost electron in eV.
f0	The fraction of electrons in the outermost state.
K	A constant that depends on the target.
sswitch	The switch bit field.
target	A pointer to a TDATA structure.

Returns: Number of delta-rays per unit length in units of g^-1 cm².

Bug:: The parameters needed are not contained in the target table.

Definition at line 437 of file crange.c.

double effective_charge	(	double	z0,
		double	e1,
		double	z2,
		short	sswitch
	)

Computes effective projectile charge.

This is the modification of projectile charge due to electron capture. Hubert, Bimbot & Gauvin, [12], give an empirically determined function which depends on the target material. This version is used if SSWITCH_EC is set. Two older versions, from Anthony & Landford, [4], and Pierce & Blann, [19] are also available.

Parameters

z0	The bare projectile charge.
e1	The projectile kinetic energy in A MeV.
z2	The target mean nuclear charge.
sswitch	The switch bit field.

Returns: The effective projectile charge.

Bug:: The Pierce & Blann formula is not actually available; it is simply commented out.

Definition at line 366 of file crange.c.

double energy_table ( int i )

Returns the energy corresponding to a value in a range table.

This utility returns an energy value from a (virtual) vector containing A logarithmically uniform distribution of energies between a minimum and maximum energy (defined by LOGTENEMIN and LOGTENEMAX), with a number of entries given by MAXE.

Parameters

i	The index of the vector.

Returns: The i th energy in A MeV.

Definition at line 1569 of file crange.c.

double Fbrems ( double x )

Compute a mathematical function related to bremsstrahlung.

This function is used in an obsolete version of projectile slowing due to nuclear-nuclear bremsstrahlung. It appears in Heitler's treatment of bremsstrahlung, [11], which was adapted by Weaver & Westphal, [27].

Parameters

x	The input parameter.

Returns: The value of the function.

Bug:: Currently, this function is unused.

Definition at line 1039 of file crange.c.

tdata* find_target	(	char *	target,
		tdata *	extratargets
	)

Finds target data corresponding to a target name.

This function returns a pointer to a structure containing the target data corresponding to the input name. There is a built-in list. The built-in list may be added to or overridden by supplying an INI-type file on the command line, which will then be parsed & passed to this function. If the special target name "List" is passed to this function, the built-in list will be printed as an INI-type file.

Parameters

target	The name of a target.
extratargets	A pointer to an array of TDATA structures.

Returns: A pointer to a structure containing the target data. If the name of the target was not found, it will point to a dummy structure.

Definition at line 1596 of file crange.c.

short init_switch ( char * switchfile )

Initializes the value of of the switch bit field.

This utility reads an INI-type file and sets the switch bit field accordingly.

Parameters

switchfile The name of an INI-type file containing switch configuration.

Returns: The switch bit field.

Warning: If the iniparser library is not found, this function will only return the default value SSWITCH_DEFAULT.

Definition at line 1441 of file crange.c.

void init_table ( void )

Initialize range-energy tables.

Sets all data in the array of RANGE_TABLE structures trange to zero.

Definition at line 1543 of file crange.c.

tdata* init_target ( char * targetfile )

Read optional target data file.

This utility reads an INI-type file and returns an array of pointers to TDATA structures.

Parameters

targetfile the name of an INI-type file containing target data.

Returns: A pointer to an array of TDATA structures. This pointer must be free()d!

Warning: If the iniparser library is not found, this function will only return a NULL pointer.

Definition at line 1481 of file crange.c.

double lindhard	(	double	zz,
		double	aa,
		double	bb,
		short	sswitch
	)

Compute the Lindhard-Sørensen correction.

This is the Lindhard-Sørensen correction including finite nuclear size effects as described in Lindhard & Sørensen, [17]. The defined variable SSWITCH_NS will turn off the nuclear size effect if it is set to zero. For values of the Lorentz factor above 10/R, where R is the nuclear size divided by the electron Compton wavelength, the correction is set to its asymptotic value which is described by Sørensen, [23]. This also avoids some difficulties with the evaluation of the confluent hypergeometric function (A. H. Sørensen, private communication).

Parameters

zz	The projectile charge.
aa	The projectile atomic mass.
bb	The projectile velocity in units of the speed of light (i.e. $\beta = v/c$ ).
sswitch	The switch bit field.

Returns: The value of the Lindhard-Sørensen correction.

Definition at line 897 of file crange.c.

double olddelta	(	double	g,
		tdata *	target
	)

Computes an obsolete version of the density effect.

This function implements the density effect correction as originally formulated in Sternheimer & Peierls, [21]. Although it is now obsolete, I have included it here for compatibility with earlier codes.

Parameters

g	Projectile Lorentz factor.
target	A pointer to a TDATA structure.

Returns: The value of the density effect.

Definition at line 692 of file crange.c.

void print_target ( tdata * target )

Prints a target table entry in INI format.

This utility prints a TDATA structure in INI format.

Parameters

target A pointer to a TDATA structure.

Definition at line 1677 of file crange.c.

double qrange	(	double	e,
		double	z1,
		double	a1,
		short	sswitch,
		tdata *	target
	)

Computes total range by direct integration of dE/dx.

This function computes total range by direct integration of the dedx() function. It does not create a range table or do table interpolation.

Parameters

e	Initial energy in A MeV.
z1	Projectile charge.
a1	Projectile mass.
sswitch	The switch bit field.
target	A pointer to a TDATA structure.

Returns: Total range in g cm^-2.

Bug:: Currently, this function isn't called by anything.

Definition at line 1183 of file crange.c.

double range	(	double	e,
		double	z1,
		double	a1,
		short	sswitch,
		tdata *	target,
		int *	tno
	)

Computes total range given initial energy.

This function computes total range given initial energy. The technique is quite clever, in that if from one call to the next, the projectile and target material parameters do not change, the calculation of range is performed by table interpolation rather than direct integration. The savings in calculation time can be enormous. However, the range of valid energies is limited by the size of the table. The function dE/dx is evaluated at most of the energies defined by the function energy_table(). Results are stored in the RANGE_TABLE array trange. The size of trange (set by MAXAB) is arbitrary and should be set to whatever is most useful. Certainly it should be no smaller than the number of target materials being used.

Parameters

e	Initial projectile kinetic energy in A MeV.
z1	Projectile charge.
a1	Projectile atomic mass.
sswitch	The switch bit field.
target	A pointer to a TDATA structure.
tno	A pointer to the index of the most recently generated or used table.

Returns: Projectile range in g cm^-2.

Definition at line 1086 of file crange.c.

double relbloch	(	double	z12,
		double	b1,
		double	lambda,
		double	theta0
	)

Compute the relativistic Bloch correction.

This is the relativistic Bloch (or Ahlen) correction of Ahlen, [3]. The evaluation of this correction has been enormously simplified by the use of fully complex arithmetic.

Parameters

z12	The projectile charge.
b1	The projectile velocity in units of the speed of light (i.e. $\beta = v/c$ ).
lambda	A free parameter, described in bma().
theta0	A free parameter, described in bma().

Returns: The value of the relativistic Bloch correction.

Definition at line 838 of file crange.c.

double renergy	(	double	e,
		double	r0,
		double	z1,
		double	a1,
		short	sswitch,
		tdata *	target
	)

Extract energies from range tables.

This function extracts energies from a range table by table interpolation. It calls range() to initialze the range table or to find the correct table if it has already been computed.

Parameters

e	Projectile kinetic energy [A MeV].
r0	Range [g cm^-2].
z1	Projectile charge.
a1	Projectile atomic mass.
sswitch	The switch bit field.
target	A pointer to a TDATA structure.

Returns: The final energy of the projectile.

Definition at line 1348 of file crange.c.

void run_range	(	FILE *	finput,
		FILE *	foutput,
		short	sswitch,
		tdata *	extratargets
	)

Parses and executes the task list.

This utility function steps through the range, energy and dE/dx tasks specified in the input data file. The tasks are denoted by a single letter:

r compute ranges
e compute energies
d compute dE/dx
j compute dJ/dx (primary ionization)

The task letter should be followed by the energy (or range) at which to compute range (or energy), the charge and mass of the particle, and the name of the target material. Names of target materials can be found in the target.ini file. Target material names may be up to NAMEWIDTH characters in length and should contain no whitespace.

Parameters

finput	An open file pointer containing the task list.
foutput	An open file pointer to write results to.
sswitch	The switch bit field.
extratargets	A pointer to an array of TDATA structures.

Bug:: The primary ionization parameters are currently hard-coded.

Definition at line 1396 of file crange.c.

Variable Documentation

range_table trange[MAXAB]

The range-energy table.

This external variable contains the range-energy tables.

Definition at line 166 of file crange.h.

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation

Variable Documentation