crange-1.6.2
Data Structures | Macros | Typedefs | Functions | Variables
crange.h File Reference

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>

Go to the source code of this file.

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...
 
tdatainit_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...
 
tdatafind_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/c2.

Definition at line 65 of file crange.h.

#define ELECTRONMASS   0.511003e+6

Electron mass in units of eV/c2.

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/c2.

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
eProjectile kinetic energy in A MeV.
z1Projectile charge.
a1Projectile atomic mass.
targetA 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
z1The projectile charge.
bThe 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
aFirst parameter of the hypergeometric function.
bSecond parameter of the hypergeometric function.
zA complex number.
Returns
The value $ M(a,b,z) $ , a complex number.
Warning
May not be stable for large values of $|z|$.

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
zA 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 $ F(V) $ for $ V < 0.8 $ . For the purposes of the computation, the cut-off is placed at $ V=1.0 $ . 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 $ V > 1.0 $ , 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
e1The projectile kinetic energy in A MeV.
rel0Restricted energy loss parameter in eV.
z0The projectile charge.
a1The projectile atomic number.
sswitchThe switch bit field.
targetA pointer to a TDATA structure.
Returns
dE/dx in units of A MeV g-1 cm2

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
gProjectile Lorentz factor.
targetA 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
e1The projectile kinetic energy in A MeV.
z0The projectile charge.
I0The binding energy of outermost electron in eV.
f0The fraction of electrons in the outermost state.
KA constant that depends on the target.
sswitchThe switch bit field.
targetA pointer to a TDATA structure.
Returns
Number of delta-rays per unit length in units of g-1 cm2.
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
z0The bare projectile charge.
e1The projectile kinetic energy in A MeV.
z2The target mean nuclear charge.
sswitchThe 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
iThe 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
xThe 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
targetThe name of a target.
extratargetsA 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
switchfileThe 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
targetfilethe 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
zzThe projectile charge.
aaThe projectile atomic mass.
bbThe projectile velocity in units of the speed of light (i.e. $ \beta = v/c $).
sswitchThe 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
gProjectile Lorentz factor.
targetA 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
targetA 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
eInitial energy in A MeV.
z1Projectile charge.
a1Projectile mass.
sswitchThe switch bit field.
targetA 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
eInitial projectile kinetic energy in A MeV.
z1Projectile charge.
a1Projectile atomic mass.
sswitchThe switch bit field.
targetA pointer to a TDATA structure.
tnoA 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
z12The projectile charge.
b1The projectile velocity in units of the speed of light (i.e. $ \beta = v/c $).
lambdaA free parameter, described in bma().
theta0A 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
eProjectile kinetic energy [A MeV].
r0Range [g cm-2].
z1Projectile charge.
a1Projectile atomic mass.
sswitchThe switch bit field.
targetA 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
finputAn open file pointer containing the task list.
foutputAn open file pointer to write results to.
sswitchThe switch bit field.
extratargetsA 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.