libamtrack-package: libamtrack package
In libamtrack: Computational Routines for Proton and Ion Radiotherapy

Description Details Author(s) References See Also Examples

This package is the R interface to the open-source, ANSI C library libamtrack. libamtrack provides computational routines for the prediction of detector response and relative biological efficiency in heavy charged particle beams. It is designed for research in proton and ion dosimetry and radiotherapy. libamtrack also provides many auxiliary physics routines for proton and ion beams. Please note that libamtrack is still under heavy development and so is the R interface. Function can be unstable especially when arguments are pushed out of their scope. If you experience any trouble your feed back is very appreciated: s.greilich@dkfz.de.

Package:	libamtrack
Version:	0.6.4 (Yellow Armadillo)
Date:	2018-06-18
Depends:	R (>= 2.12.0)
Suggests:	lattice
SystemRequirements:	gsl (optinally: cernlib to enable energy loss distributions)
License:	GPL (version 3 or later)

FUNCTION INDEX: Efficiency / RBE routines: These functions compute the relative efficiency / RBE of a mixed particle field according to a specific amorphous track model flavour and phyiscs

`AT.run.GSM.method`	Grid-summation ('checkerboard') method
`AT.run.IGK.method`	Ion-gamma-kill ('Katz') method
`AT.run.CPPSC.method`	Compund-Poison process with successive convolutions (CPP-SC, 'SPIFF') method
`AT.CPPSC.alpha.and.beta`	Alpha, beta for ion beams as predicted by CPP-SC method

Track-structure routines: These functions handle underlying physic used in amorphous track modeling:

`AT.D.RDD.Gy`	Dose distribution around a particle track
`AT.r.RDD.m`	Inverse dose distribution around a particle track
`AT.max.electron.ranges.m`	Maximum electron range / track width
`AT.gamma.response`	Gamma / X ray response of a system
`AT.inverse.gamma.response`	Inverse Gamma / X ray response of a system

SPC routines: These functions provide an interface to spectral depth data:

`AT.SPC.read`	Read in spc data from file
`AT.SPC.spectrum.at.depth.step`	Extract spectrum at given depth step
`AT.SPC.spectrum.at.depth.g.cm2`	Extract spectrum at given depth (will use clostest step)
`AT.SPC.tapply`	Applies a function to all depths of spc data

FLUKA routines: These function provide an interface to FLUKA output files:

`AT.FLUKA.read.USRBIN.mesh`	Reads USRBIN output (Cartesian mesh, also for multiple runs).
`AT.FLUKA.read.USRBIN.regs`	Reads USRBIN output (regions, also for multiple runs).
`AT.FLUKA.read.USRTRACK`	Reads USRTRACK output (energy spectra, also for multiple runs).
`AT.FLUKA.particle.name.to.libamtrack.particle.name`	Converts FLUKA particle names to libamtrack conventions.

Physics routines: These functions handle the physics of proton and ion beams needed in libamtrack. Stopping-power routines:

`AT.Mass.Stopping.Power`	Electronic mass stopping power (data source by name)
`AT.Stopping.Power`	Electronic stopping power (data source by name)
`AT.Mass.Stopping.Power.with.no`	Electronic mass stopping power (data source by number)
`AT.Stopping.Power.with.no`	Electronic stopping power (data source by number)
`AT.stopping.power.ratio`	Computes stopping power ratios, also for mixed fields
TODO:	Re-enable CSDA functions
`AT.CSDA.range.g.cm2`	CSDA range using PSTAR data

Mean LET / energy in mixed fields routines:

`AT.fluence.weighted.LET.MeV.cm2.g`	Computes fluence-weighted LET
`AT.dose.weighted.LET.MeV.cm2.g`	Computes dose-weighted LET
`AT.fluence.weighted.E.MeV.u`	Computes fluence-weighted mean energy
`AT.dose.weighted.E.MeV.u`	Computes dose-weighted mean energy

Dose / fluence conversions:

`AT.dose.Gy.from.fluence.cm2`	Compute dose(s) for given fluence(s) and particle(s)
`AT.fluence.cm2.from.dose.Gy`	Compute fluence(s) given dose(s) and particle(s)
`AT.total.D.Gy`	Computes total dose for a mixed field
`AT.total.fluence.cm2`	Computes total fluence for a mixed field

Beam related routines:

`AT.beam.par.technical.to.physical`	For double Gaussian beam, converts FWHM and particle number into fluence and sigma width
`AT.beam.par.physical.to.technical`	Inverse, converts fluence and sigma width into FWHM and particle number

Misc physics routines:

`AT.momentum.MeV.c.u.from.E.MeV.u`	Momentum from kinetic energy
`AT.E.MeV.u.from.momentum.MeV.c.u`	Kinetic energy from momentum
`AT.effective.charge.from.E.MeV.u`	Effective charge of an ion depending on its kinetic energy
`AT.max.E.transfer.MeV`	Max energy transfered from an ion to secondary electrons
`AT.mean.number.of.tracks.contrib`	Mean number of tracks that desposite dose in a representative point
`AT.Rutherford.SDCS`	Rutherford cross section of energy transferred to sec. electrons
`AT.beta.from.E`	Relativistic beta of an ion with
`AT.E.from.beta`	Kinetic energy for given beta
`AT.gamma.from.E`	Relativistic gamma of an ion

Other routines:

`AT.particle.name.from.particle.no`	Converts particle index numbers into particle names
`AT.particle.no.from.particle.name`	Converts particle names into particle index numbers
`AT.particle.no.from.Z.and.A`	Returns particle index number for given mass and atomic number
`AT.A.from.particle.no`	Returns mass number for given particle number
`AT.Z.from.particle.no`	Returns atomic number for given particle number
`AT.nuclear.spin.from.particle.no`	Returns nuclear spin for given particle number
`AT.electron.density.m3`	Returns electron density from average Z and A
`AT.electron.density.m3.from.material.no`	Returns electron density for given material
`AT.material.name.from.material.no`	Converts material index numbers into material names
`AT.material.no.from.material.name`	Converts material names into material index numbers
`AT.electron.density.m3.from.composition`	Computes electron density from material composition
`AT.average.A.from.composition`	Computes average mass number from material composition
`AT.average.Z.from.composition`	Computes average atomic number from material composition
`AT.effective.Z.from.composition`	Computes effective atomic number from material composition
`AT.I.eV.from.composition`	Computes average I value from material composition
`AT.set.user.material`	Sets properties of user defined material (CAVE: only valid until library is freed)
`AT.set.user.material.from.composition`	Sets properties of user defined material from elemental composition (CAVE: only valid until library is freed)
`AT.get.materials.data`	Returns properties of pre-defined materials

Helper routines shipped with libamtrack:

`AT.add.leading.zeros`	Adds leading zeros to a character string representing a number
`AT.add.trailing.zeros`	Adds trailing zeros to a character string representing a number

C2R autoconversion developed by: Felix Klein fklein@embl.de Package maintainer: Steffen Greilich s.greilich@dkfz.de

Greilich, Grzanka, Bassler, Andersen and Jakel, Amorphous track models: A numerical comparison study, doi:10.1016/j.radmeas.2010.05.039

http://libamtrack.dkfz.org

##############################################################################
############################ 1. LET ##########################################
cat("Compute the LET (in keV/um) of a 270 MeV/u carbon ion in Aluminum\n")
cat("using the PSTAR stopping power data:\n")
AT.Stopping.Power( E.MeV.u               = 270,
                   particle.no           =
 AT.particle.no.from.particle.name("12C"),
                   material.no           =
 AT.material.no.from.material.name("Aluminum"),
                   stopping.power.source = "PSTAR")
                  
cat("... and in water:\n")
AT.Stopping.Power( E.MeV.u               = 270,
                   particle.no           =
 AT.particle.no.from.particle.name("12C"),
                   material.no           =
 AT.material.no.from.material.name("Water, Liquid"),
                   stopping.power.source = "PSTAR")
###############################################################################

# 2. DOSE AROUND A TRACK 
cat
("Compare the Geiss parametrization for protons and Carbon at different energies:\n"
)
df    <-    expand.grid(    E.MeV.u           = 10^seq(0, 3, length.out = 4), 
      # from 1 to 1000 MeV/u in 4 steps
                            particle.no       = c(1001,6012),                 
      # protons and carbons
                            r.m               = 10^seq(-9, -2, length.out =
 100),   # from 1 nm to 1 cm in 100 steps
                            material.no       = 2,                            
      # Aluminium Oxide
                            rdd.model         = 3,                            
      # Geiss parametrization
                            rdd.parameter     = 5e-8,                         
      # Fixed core size of 50 nm
                            er.model          = 4,                            
      # Geiss track width parametrization
                            D.Gy              = 0)                            
      # For later use
ii                   <-  df$particle.no == 1001                               
      # Add particle names
df$particle.name     <-  "Carbon-12"
df$particle.name[ii] <-  "Protons"
for (i in 1:nrow(df)){                                                        
      # Loop through particles/energies
    df$D.Gy[i]    <-    AT.D.RDD.Gy(     r.m              = df$r.m[i],
                                         E.MeV.u          = df$E.MeV.u[i],
                                         particle.no      = df$particle.no[i],
                                         material.no      = df$material.no[i],
                                         rdd.model        = df$rdd.model[i],
                                         rdd.parameter    =
 df$rdd.parameter[i],
                                         er.model         = df$er.model[i],
                                         stopping.power.source.no            
 = 2)[[1]]                           # use PSTAR data
}
lattice::xyplot( log10(D.Gy) ~ log10(r.m)|particle.name,                      
               # Plot
                 df,
                 type      = 'l',
                 groups    = E.MeV.u,
                 auto.key  = TRUE)[c(2,1)]
        
#####################################################################
#################### 3. DETECTOR EFFICIENCY #########################
cat("Compute the relative efficiency of Alanine in 10 MeV protons\n")
cat("Waligorskis version of the Katz' model\n")
AT.run.IGK.method( particle.no                          = 1001,               
         # namely protons with
                   E.MeV.u                              = 10,                 
         # 10 MeV/u
                   fluence.cm2.or.dose.Gy               = c(-1.0),            
         # delivering 1 Gy
                   material.no                          = 5,                  
         # i.e. Alanine
                   rdd.model                            = 4,                  
         
# Katz parametrization of radial dose distribution with simplified extended
# targets
                   rdd.parameter                        = c(5e-8,1e-10),      
         # with 50 nm target size and 1e-10 dose minimum
                   er.model                             = 2,                  
         # Butts&Katz parametrization of track radius
                   gamma.model                          = 2,                  
         # Use general target/hit model but here...
                   gamma.parameters                     = c(1,500,1,1,0),     
         # ...as exponential saturation with characteristic dose 500 Gy
                   saturation.cross.section.factor      = 1.4,                
         # factor to take 'brush' around track into account
                   write.output                         = TRUE,               
         # write a log file
                   stopping.power.source.no             = 2)                  
         # use PSTAR data