Since, for a given ion, there can be different calculations of atomic data with slightly (or not so slightly!) different results, more than one version of the data can exist for a given ion. The data are stored in and read from different types of files depending on the mechanism of line formation:
In the case of collisionally excited lines, the data are organized in different way depending on the file format:
Since version 1.0.1, fits file have being totally replaced by plain ascii tables (extension .dat), which are organized as follows:
Chianti data are also usable if the user installed the Chianti database and set up the XUVTOP environment variable pointing to the corresponding directory.
Each of these file contains information for a finite number of levels N. Specifically, the energy levels and the statistical weights are arrays with N elements (one value per level), while the transition probability tables are triangular N*N matrices with zeros on the main diagonal (transition probabilities are different from zero only for (j -> i) transitions with j > i).
This number is a feature of the particular atomic calculation, not an intrinsic feature of the physical atom, so that an Atom object created within PyNeb will have a number of levels NLevels equal to the number of levels of all the data used (or the minimum of them if either of the atom, coll or levels is different).
You can access the NIST raw data by:
In [1]:
%matplotlib inline
import pyneb as pn
O3 = pn.Atom('O', 3)
In [2]:
O3.NIST
Out[2]:
You can access the full raw NIST data set by:
In [3]:
pn.utils.manage_atomic_data.getLevelsNIST('O2') #O2 is lighter than O3...
Out[3]:
You can print the name of the atomic data used for a given ion with:
In [4]:
print(O3.atomFile)
In [5]:
print(O3.collFile)
As the files can be located in different directories (including some from the user), you may also find useful to print out the path:
In [6]:
print(O3.atomPath)
print(O3.collPath)
A set of data files for a given group of ions is called a data set. The default data set (or the adopted data set, if a different one has been set) can be displayed with the command:
In [7]:
pn.atomicData.getDataFile()
Out[7]:
while the data files set for a particular ion can be displayed by providing an argument to the above; e.g. for [SIV]:
In [8]:
pn.atomicData.getDataFile('S4')
Out[8]:
The complete inventory of data available for a given ion can be displayed with the command:
In [9]:
pn.atomicData.getAllAvailableFiles('O2')
Out[9]:
This method looks for all the “o_ii_*” files in a set of paths which includes the location of the atomic data provided with the package and the current directory (the one from where the python session is running); additional paths can be added with the following command:
In [10]:
pn.atomicData.addDataFilePath("/tmp")
If you want to change several data files at once, it may be worth defining a dictionary with all your preferred atomic data files within your script:
In [11]:
DataFileDict = {'N1': {'atom': 'n_i_atom_KS86-WFD96.dat', 'coll': 'n_i_coll_PA76-DMR76.dat'},
'N2': {'atom': 'n_ii_atom_GMZ97-WFD96.dat', 'coll': 'n_ii_coll_LB94.dat'},
'O2': {'atom': 'o_ii_atom_Z82-WFD96.dat', 'coll': 'o_ii_coll_P06-T07.dat'},
'O3': {'atom': 'o_iii_atom_FFT04-SZ00.dat', 'coll': 'o_iii_coll_AK99.dat'},
'Ne3': {'atom': 'ne_iii_atom_GMZ97.dat', 'coll': 'ne_iii_coll_McLB00.dat'}}
pn.atomicData.setDataFileDict(DataFileDict)
Make sure that all the files listed actually exist, as this is not checked by the code at this level.
Predefined atomic data sets are provided by PyNeb. Each data set is identified by a label; the one of the default data set can be retrieved by the following command:
In [12]:
pn.atomicData.defaultDict
Out[12]:
To display the complete list of the existing predefined dictionaries, enter:
In [13]:
pn.atomicData.getAllPredefinedDict()
Out[13]:
The following command can be used to set one of them:
In [14]:
pn.atomicData.includeFitsPath()
pn.atomicData.setDataFileDict("IRAF_09")
To revert to the default set:
In [15]:
pn.atomicData.resetDataFileDict()
pn.atomicData.removeFitsPath()
You can have a look at the other methods of pn.atomicData in the Reference Manual, or using the help command.
You may have downloaded the CHIANTI database from the website http://www.chiantidatabase.org/chianti_download.html. In this case you can use its data to feed PyNeb. You need first to define the environment variable XUVTOP to point to the directory where the database is on your disk.
Then you can ask PyNeb to use the atomic data from CHIANTI for a given ion:
In [16]:
pn.atomicData.setDataFile('o_iii_atom.chianti')
pn.atomicData.setDataFile('o_iii_coll.chianti')
O3_ch = pn.Atom('O',3)
print(O3_ch)
If you need to include all the available CHIANTI data, you can use the following command:
In [17]:
atoms = pn.atomicData.getAllAtoms()
print(atoms)
print('After including CHIANTI:')
pn.atomicData.addAllChianti()
atoms = pn.atomicData.getAllAtoms()
print(atoms)
The following is an example of a 6-level atom file of [O III], containing the matrix of transition probabilities. The energy levels and statistical weigths are not in this file. This file is o_iii_atom_FFT04.dat.
Aij
1/s 1/s 1/s 1/s 1/s 1/s
0.0000000e+00 0.0000000e+00 0.0000000e+00 0.0000000e+00 0.0000000e+00 0.0000000e+00
2.5960000e-05 0.0000000e+00 0.0000000e+00 0.0000000e+00 0.0000000e+00 0.0000000e+00
3.0300000e-11 9.6320000e-05 0.0000000e+00 0.0000000e+00 0.0000000e+00 0.0000000e+00
2.3220000e-06 6.9510000e-03 2.0290000e-02 0.0000000e+00 0.0000000e+00 0.0000000e+00
0.0000000e+00 2.2550000e-01 6.9980000e-04 1.6850000e+00 0.0000000e+00 0.0000000e+00
2.1910000e-03 2.3080000e+02 5.7650000e+02 5.7770000e-03 3.7600000e-11 0.0000000e+00
*** ATOM oxygen
*** SPECTRUM 3
*** GSCONFIG unknown
*** SOURCE3 Froese Fischer et al 2004, ADNDT 87, 1
*** NOTE3 A-values from all levels The effective collision strengths are a function of electron temperature (a collective property of the electron distribution) and are obtained as the average over a Maxwellian distribution of the collision strengths, which depend on the energy. (Note: in this document, we will often refer to the effective collision strengths as collision strengths for short, although this is not strictly correct.) They are usually published for a handful of T values and must be interpolated to get the collision strength at the desired values. As a result, there is a whole 1-D array of collision strengths, with one element for each tabulated temperature value, for each transition j -> i with j > i. The existence of this 3rd dimension prevents the data from being simply stored in a matrix as transition probabilities are. Instead, each transition is presented in a line, as in the following example:
*** OIII collision strengths data
0 0 3.699e+00 4.000e+00 4.301e+00 4.477e+00
1 2 5.240e-01 5.648e-01 6.007e-01 6.116e-01
1 3 2.469e-01 2.766e-01 3.106e-01 3.264e-01
1 4 2.347e-01 2.693e-01 3.094e-01 3.256e-01
1 5 4.094e-02 4.069e-02 4.299e-02 4.424e-02
1 6 1.130e-01 1.239e-01 1.346e-01 1.373e-01
2 3 1.210e+00 1.330e+00 1.451e+00 1.499e+00
2 4 7.067e-01 8.108e-01 9.313e-01 9.802e-01
2 5 1.228e-01 1.223e-01 1.294e-01 1.332e-01
2 6 3.390e-01 3.717e-01 4.038e-01 4.119e-01
3 4 1.188e+00 1.363e+00 1.564e+00 1.645e+00
3 5 2.045e-01 2.046e-01 2.170e-01 2.235e-01
3 6 5.650e-01 6.195e-01 6.730e-01 6.865e-01
4 5 4.544e-01 5.661e-01 6.230e-01 6.219e-01
4 6 0.000e+00 0.000e+00 0.000e+00 0.000e+00
5 6 0.000e+00 0.000e+00 0.000e+00 0.000e+00
*** T_UNIT log(K)
*** ATOM oxygen
*** SPECTRUM 3
*** GSCONFIG p2
*** SOURCE1 Palay, E. et al. 2012, MNRAS Letters, 423, L35
*** NOTE1 All collision strengths from levels up to 5
*** SOURCE2 Aggarwal and Keenan 1999, ApJS 123, 311
*** NOTE2 Collision strengths of 6-1, 6-2, 6-3 The first row of the data block (0 0 …) contains, from the third element on, the array of electron temperatures for which the collision strengths are tabulated (in log10(K) or K/10000, depending on the particular data set).
The original fits data for collision strengths support, by default, a Chebyshev polynomial interpolation: each transition is described by a Chebyshev polynomial of order n that interpolates the tabulated values. The default value for the Chebyshev order is the number of temperature values, but other order can be specified when calling pn.writeColl. If, for some reason, a Chebyshev interpolation is not desired, the data can also be interpolated linearly, when the instantiation of the corresponding Atom is done.
The ascii data (those currently used by default) only support linear interpolation among tabulated values.
Notice the use of SOURCE and NOTE keywords to store the data references. It is very important to fill in these keywords and to give a descriptive name to the file, i.e. a name that reflects the sources of the data. When an Atom object is built, this information is stored and is retrievable thereafter through:
In [18]:
O3.printSources()
The atomic data available can be plotted using the methods of the DataPlot class. The class must be instantiated by specifying which data sets are to be plotted. The available methods are plotA, plotRelA and plotAllA to plot transition probabilities, and plotOmega to plot collision strengths.
You must first create an instantiation of DataPlot for a given atom, e.g.:
In [24]:
dp_O3 = pn.DataPlot('O', 3, NLevels=5)
dp_S3 = pn.DataPlot('S', 3)
Then you can plot the different As and Omegas :
In [25]:
dp_S3.plotA(figsize=(8, 6)) # transition probabilities plot
In [26]:
dp_S3.plotRelA(figsize=(8, 6)) # relative transition probabilities plot
In [27]:
dp_S3.plotAllA(figsize=(8, 6))
In [28]:
dp_O3.plotOmega(figsize=(10, 8)) # collision strength plot