6.5 KiB
CATima library manual
Compiling and Instalation
See README.md for details. link2 Units
The following units are used for input and outputs:
- projectile energy - MeV/u
- density - g/cm^3
- material thickness - g/cm^2
- material length - cm
- angle - rad
- time of flight - ns
Projectile
The Projectile class is used to store projectile data. Each projectile must provide A,Z combination, additionally charge state can be set as well. The example of projectile definition:
catima::Projectile p1(12,6); //12C projectile
catima::Projectile p2(12,6,5); //12C(5+) projectile
to set the energy of the projectile in MeV/u units:
p1.T = 1000.0;
p2(1000.0);
Material Definition
The material is defined and stored in Material class. The class stores the atom constituents, thickness and density of the material etc.
There are 2 ways to define materials: specifying all elements in constructor or using add_element(double, int, double) function.
The example of water definition:
catima::Material carbon({0,6,1}); // carbon with elemental atomic weight
catima::Material water1({
{1,1,2}, // {weight, Z, stn or weight fraction}
{16,8,1}
});
water1.density(1.0);
water1.thickness(2.0);
water1.I(78.); // set custom ionization potential in eV
catima::Material water2;
water2.add_element(1,1,2);
water2.add_element(16,8,1);
water2.density(1.0).thickness(2.0);
If mass number is equal to 0, the mass number of the element is taken as atomic weight of the element. Compound elements can be defined either via stoichiometric number or via weight fraction. If the number is less than 1 it is assumed weight fraction is being used, otherwise stoichiometric number or molar fraction is being used.
catima::Material air ({{0,7,0.755267},{0,8,0.231781},{0,18,0.012827},{0,6,0.000124}},0.001205); // weight fractions
catima::Material water ({{0,1,2},{0,8,1}},1); // mole fraction
predefined materials
If the library is compiled with predefined materials database, the Material can be retrieved from the database as:
using namespace catimal
Material water = get_material(material::WATER);
Material graphite = get_material(6);
The list of predefined material can be found at material_database.h file
Calculation
To calculate all observable following function can be used:
Result calculate(Projectile &p, const Material &t, double T, Config c)
Result calculate(Projectile &p, const Material &t, Config c)
Both function returns structure Result which contains all calculated variables.
struct Result{
double Ein=0.0;
double Eout=0.0;
double Eloss = 0.0;
double range=0.0;
double dEdxi=0.0;
double dEdxo=0.0;
double sigma_E=0.0;
double sigma_a=0.0;
double sigma_r=0.0;
double tof=0.0;
};
If one is interested only in one of the variable, the following function can be used:
double dedx(Projectile &p, double T, const Material &t, Config c=default_config);
double domega2dx(Projectile &p, double T, const Material &t, Config c=default_config);
double range(Projectile &p, double T, const Material &t, Config c=default_config);
double range_straggling(Projectile &p, double T, const Material &t, Config c=default_config);
double angular_straggling(Projectile &p, double T, const Material &t, Config c=default_config);
Example calculation:
...
double T=1000;
auto result = catima::calculate(p1(1000),water1);
cout<<"T "<<T<<", dEdx = "<<result.dEdxi<<" MeV/g/cm2"<<", range = "<<result.range<<" g/cm2"<<endl;
Multilayer Material
The layers of Materials are stored in catima::Layers class.
There are following ways to define Layers from catima::Material classes:
catima::Material graphite({12,6,1});
catima::Material nitrogen({14,7,1});
...
catima::Layers matter1;
matter1.add(graphite);
matter1.add(nitrogen);
matter1.add(graphite);
cout<<"number of layers = "<<matter1.num()<<"\n"; // 3
Layers can be copied from existing Layes:
catima::Layers matter2;
matter2 = matter1; //matter2 contain 3 layers
matter2.add(nitrogen);
matter2.add(graphite); //matter2 contains 5 layers now
Layers can be created as a combination of another Layers:
catima::Layers matter3 = matter1 + matter2;
Config
The calculation configuration is set via catima::Config class. The dafault configuration is predefined in catima::default_config variable. This default_config is supplied as default argument to functions like catima::calculate. If custom config is needed another configuration can be provided.
the structure Config is defined as:
struct Config{
#ifndef GLOBAL
unsigned char z_effective=z_eff_type::pierce_blann;
#else
unsigned char z_effective=z_eff_type::atima14;
#endif
#ifdef REACTIONS
unsigned char skip=skip_none;
#else
unsigned char skip=skip_calculation::skip_reactions;
#endif
unsigned char corrections = 0;
unsigned char calculation = 1;
};
effective charge calculation###
the following effective charge calculations are buit in:
enum z_eff_type:char {
none = 0,
pierce_blann = 1,
anthony_landorf = 2,
hubert = 3,
winger = 4,
schiwietz = 5,
global = 6,
atima14 = 7
}; hubert = 3
- z_eff_type::none - the provided Projectile Q is used as a charge
- z_eff_type::pierce_blann - Pierce Blann formula, using function: z_eff_Pierce_Blann()
- z_eff_type::anthony_landorf - function: z_eff_Anthony_Landorf()
- z_eff_type::hubert - function: z_eff_Hubert()
- z_eff_type::winger - function: z_eff_Winger()
- z_eff_type::global - function: z_eff_global()
- z_eff_type::atima14 - function: z_eff_atima14()
All available switches are defined in config.h file.
Using the library
the include direcotry and LD_LIBRARY_PATH must be properly adjusted. The app must be linked against catima library. For example check examples directory and makefile inside to see how to link.
All functions and classes are inside catima namespace
Normally including main file is enough:
#include "catima/catima.h"
Using with C
the C wrapper is provided in cwapper.h, this file can be included in C app. The C app must be then linked against catima library. It provides only basic interface.