atomdb module
This modules is designed to interact with the main atomic database, extracting real values of coefficients and so on.
The atomdb module contains several routines for interfacing with the AtomDB database to extract useful physical quantities, line lists, write new fits files and more. It is currently a dump of everything I’ve done with AtomDB. This should all be considered unstable and possibly susceptible to being wrong. It will be fixed, including moving many routines out of this library, as time goes on.
Version 0.1 - initial release Adam Foster July 17th 2015
Version 0.2 - added PI reading routines and get_data online enhancements. Adam Foster August 17th 2015
Version 0.3 - added RRC generation routines Adam Foster August 28th 2015
- pyatomdb.atomdb.calc_rad_rec_cont(Z, z1, z1_drv, T, ebins, abund=1.0, ion_pop=1.0, settings=False, datacache=False)[source]
Calculate the radiative recombination continuum for an ion at temperature T
- Parameters:
- Zint
nuclear charge
- z1int
recombined ion charge+1
- z1_drvint
recombining ion charge+1
- Tfloat
temperautre (K)
- ebinsarray(float)
energy bins (in keV) on which to caclulate the spectrum
- abundfloat
elemental abundance, relative to hydrogen
- ion_popfloat
the ion’s population fraction of that element (i.e. sum of all ion_pop for an element = 1)
- Returns:
- array(float)
RRC in photons cm^3 s^-1 bin^-1, in an array of length(ebins)-1
- array(float)
Recombination rates into the excited levels, in s-1
- pyatomdb.atomdb.calc_rrc(Z, z1, eedges, Te, lev, xstardat=False, xstarlevfinal=1, settings=False, datacache=False, returntotal=False)[source]
Calculate the radiative recombination continuum for a given ion
- Parameters:
- Zint
Atomic number
- z1int
recombined ion charge
- eedgesarray(float)
the bin edges for the spectrum to be calculated on (keV)
- Tefloat
The electron temperature (K)
- levint
The level of the ion for the recombination to be calculated into
- xstardatdict or HDUList
The xstar PI data. This can be an already sorted dictionary, as returned by sort_xstar_data, or the raw results of opening the PI file
- xstarlevfinalint
If you need to identify the recombining level, you can do so here. Should normally be 1.
- settingsdict
See description in read_data
- datacachedict
See description in read_data
- returntotalbool
If true, return the total recombination rate as well
- Returns:
- array(float)
The rrc in photons cm^3 s^-1 keV^-1
- optional float
If returntotal is set, also return total RRC calculated by separate integral from the ionization edge to infinity.
- pyatomdb.atomdb.calc_two_phot(wavelength, einstein_a, lev_pop, ebins)[source]
Calculate two photon spectrum
- Parameters:
- wavelengthfloat
Wavelength of the transition (Angstroms)
- einstein_afloat
The Einstein_A paramater for the transition
- lev_popfloat
The level population for the upper level
- ebinsarray(float)
The bin edges for the spectrum (in keV)
- Returns:
- array(float)
The flux in photons cm-3 s-1 bin-1 array is one element shorter than ebins.
- pyatomdb.atomdb.format_level(level)[source]
Take the output of a level from a level file and format it nicely
- Parameters:
- levelarray
The single line from an atomdb LV file corresponding to a level
- Returns:
- str
The formatted string.
- pyatomdb.atomdb.get_abundance(abundfile=False, abundset='AG89', element=[-1], datacache=False, settings=False, show=False)[source]
Get the elemental abundances, relative to H (H=1.0)
- Parameters:
- abundfilestring
special abundance file, if not using the default from filemap
- abundsetstring
Abundance set. To list those available, set to one that doesn’t exist (suggest “list”). Available:
- Allen
Allen, C. W. Astrophysical Quantities, 3rd Ed., 1973 (London: Athlone Press)
- AG89
Anders, E. and Grevesse, N. 1989, Geochimica et Cosmochimica Acta, 53, 197
- GA88
Grevesse, N, and Anders, E.1988, Cosmic abundances of matter, ed. C. J. Waddington, AIP Conference, Minneapolis, MN
- Feldman
Feldman, U., Mandelbaum, P., Seely, J.L., Doschek, G.A.,Gursky H., 1992, ApJSS, 81,387
Default is AG89
- elementlist of int
Elements to find abundance for. If not specified, return all.
- datacachedict
See get_data
- settingssettings
See get_data
- showbool
If set to true, print available abundances and their references to the screen.
- Returns:
- dict
abundances in dictionary, i.e :
{1: 1.0,
2: 0.097723722095581111,
3: 1.4454397707459272e-11,
4: 1.4125375446227541e-11,
5: 3.9810717055349735e-10,
6: 0.00036307805477010178,…
- pyatomdb.atomdb.get_data(Z, z1, ftype, datacache=False, settings=False, indexzero=False, offline=False)[source]
Read AtomDB data of type ftype for ion rmJ of element Z.
If settings are set, the filemap can be overwritten (see below), otherwise $ATOMDB/filemap will be used to locate the file. If indexzero is set, all levels will have 1 subtracted from them (AtomDB indexes lines from 1, but python and C index arrays from 0, so this can be useful)
- Parameters:
- Zint
Element nuclear charge
- rmJint
Ion charge +1 (e.g. 5 for C^{4+}, a.k.a. C V)
- ftypestring
- type of data to read. Currently available
‘IR’ - ionization and recombination
‘LV’ - energy levels
‘LA’ - radiative transition data (lambda and A-values)
‘EC’ - electron collision data
‘PC’ - proton collision data
‘DR’ - dielectronic recombination satellite line data
‘PI’ - XSTAR photoionization data
‘AI’ - autoionization data
‘ALL’ - reads all of the above. Does not return anything. Used for bulk downloading.
Or, for non-ion-specific data (abundances and bremstrahlung coeffts) * ‘ABUND’ - abundance tables * ‘HBREMS’ - Hummer bremstrahlung coefficients * ‘RBREMS’ - relativistic bremstrahlung coefficitients * ‘IONBAL’ - ionization balance tables * ‘EIGEN’ - eigenvalue files
- filemapstring
The filemap to use, if you do not want to use the default one.
- settingsdict
This will let you override some standard inputs for get_data:
settings[‘filemap’]: the filemap to use if you do not want to use the default $ATOMDB/filemap
settings[‘atomdbroot’]: If you have files in non-standard locations you can replace $ATOMDB with this value
- datacachedict
This variable will hold the results of the read in a dictionary. It will also be checked to see if the requested data has already been cached here before re-reading from the disk. If you have not yet read in any data but want to start caching, provide it as an empty dictionary i.e. mydatacache={}
2 parts of the data ares stored here:
Settings[‘data’] will store a copy of the data you read in. This means that if your code ends up calling for the same file multiple times, rather than re-reading from the disk, it will just point to this data already in memory. To clear the read files, just reset the data dictionary (e.g. settings[‘data’] ={})
settings[‘datasums’] stores the datasum when read in. Can be used later to check files are the same.
Both data and datasums store the data in identical trees, e.g.: settings[‘data’][Z][z1][ftype] will have the data.
- indexzero: bool
If True, subtract 1 from all level indexes as python indexes from 0, while AtomDB indexes from 1.
- offline: bool
If True, do not search online to download data files - just return as if data does not exist
- Returns:
- HDUlist
the opened pyfits hdulist if succesful. False if file doesn’t exist
- pyatomdb.atomdb.get_filemap_file(ftype, Z, z1, fmapfile='$ATOMDB/filemap', atomdbroot='$ATOMDB', quiet=False, misc=False)[source]
Find the correct file from the database for atomic data of type ftype for ion with nuclear charge Z and ioncharge+1 = z1
- Parameters:
- ftypestr
‘ir’ = ionization & recombination data
‘lv’ = energy levels
‘la’ = wavelength and transition probabilities (lambda & a-values)
‘ec’ = electron collision rates
‘pc’ = proton collision rates
‘dr’ = dielectronic recombination satellite line information
‘ai’ = autoionization rate data
‘pi’ = XSTAR photoionization data
‘em’ = emission feature data (currently unused)
- Zint
Element atomic number (=6 for C+4)
- z1int
Ion charge +1 (=5 for C+4)
- fmapfilestr
Specific filemap to use. Otherwise defaults to atomdbroot+’/filemap’
- atomdbrootstr
Location of ATOMDB database. Defaults to ATOMDB environment variable. all $ATOMDB in the filemap will be expanded to this value
- quietbool
If true, suppress warnings about files not being present for certain ions
- miscbool
If requesting “misc” data, i.e. the Bremsstrahlung inputs, use this. This is for non ion-specific data, therefore Z,z1 are ignored. types are: 10 or ‘abund’: elemental abundances 11 or ‘hbrems’: Hummer bremstrahlung gaunt factor coefficients 13 or ‘rbrems’: Relativistic bremstrahlung gaunt factor coefficients
- Returns:
- str
The filename for the relevant file, with all $ATOMDB expanded. If no file exists, returns zero length string.
- pyatomdb.atomdb.get_ionpot(Z, z1, settings=False, datacache=False)[source]
Get the ionization potential of an ion in eV
- Parameters:
- Zint
The atomic number of the element
- z1int
The ion charge + 1 of the ion
- settingsdict
See description in get_data
- datacachedict
Used for caching the data. See description in get_data
- Returns:
- float
The ionization potential of the ion in eV.
- pyatomdb.atomdb.get_ionrec_rate(Te_in, irdat_in=False, lvdat_in=False, Te_unit='K', lvdatp1_in=False, ionpot=False, separate=False, Z=-1, z1=-1, settings=False, datacache=False, extrap=True)[source]
Get the ionization and recombination rates at temperture(s) Te from ionization and recombination rate data file irdat.
- Parameters:
- Te_infloat or arr(float)
electron temperature in K (default), eV, or keV
- irdat_inHDUList
ionization and recombination rate data, if already open
- lvdat_inHDUList
level data for ion with lower charge (i.e. ionizing ion or recombined ion)
- Te_unit{‘K’ , ‘keV’ , ‘eV’}
temperature unit
- lvdatp1_inHDUList
level data for the ion with higher charge (i.e ionized or recombining ion)
- ionpotfloat
ionization potential of ion (eV).
- separatebool
if set, return DR, RR, EA and CI rates seperately. (DR = dielectronic recombination, RR = radiative recombination, EA = excitaiton autoionization, CI = collisional ionization) Note that EA & CI are not stored separately in all cases, so may return zeros for EA as the data is incorporated into CI rates.
- Zint
Element charge to get rates for (ignores “irdat_in”)
- z1int
Ion charge +1 to get rates for (ignores “irdat_in”) e.g. Z=6,z1=4 for C IV (C 3+)
- settingsdict
See description in read_data
- datacachedict
See description in read_data
- extrapbool
Extrappolate rates to Te ranges which are off the provided scale
- Returns:
- float, float:
(ionization rate coeff., recombination rate coeff.) in cm^3 s^-1 unless separate is set, in which case:
- float, float, float, float:
(CI, EA, RR, DR rate coeffs) in cm^3 s^-1 Note that these assume low density & to get the real rates you need to multiply by N_e N_ion.
- pyatomdb.atomdb.get_maxwell_rate(Te, colldata=False, index=-1, lvdata=False, Te_unit='K', lvdatap1=False, ionpot=False, force_extrap=False, silent=True, finallev=False, initlev=False, Z=-1, z1=-1, dtype=False, exconly=False, datacache=False, settings=False, ladat=False)[source]
Get the maxwellian rate for a transition from a file, typically for ionization, recombination or excitation.
- Parameters:
- Tefloat
electron temperature(s), in K by default
- colldataHDUList
If provided, the HDUList for the collisional data
- indexint
The line in the HDUList to do the calculation for. Indexed from 0.
- lvdataHDUList
the hdulist for the energy level file (as returned by pyfits.open(‘file’))
- Te_unit{‘K’ , ‘eV’ , ‘keV’}
Units of temperature grid.
- lvdatap1HDUList
The level data for the recombining or ionized data.
- ionpotfloat
The ionization potential in eV (required for some calculations, if not provided, it will be looked up)
- force_extrapbool
Force extrappolation to occur for rates outside the nominal range of the input data
- silentbool
Turn off notifications
- finallevint
Instead of specifying the index, can use upperlev, lowerlev instead.
- initlevint
Instead of specifying the index, can use upperlev, lowerlev instead
- Zint
Instead of providing colldata, can provide Z & z1. Z is the atomic number of the element.
- z1int
Instead of providing colldata, can provide Z & z1. z1 is the ion charge +1 for the initial ion
- dtypestr
data type. One of:
‘EC’ : electron impact excitation
‘PC’ : proton impact excitation
‘CI’ : collisional ionization
‘EA’ : excitation-autoionization
‘XI’ : excluded ionization
‘XR’ : excluded recombination
‘RR’ : radiative recombination
‘DR’ : dielectronic recombination
- exconlybool
For collisional excitation, return only the excitation rate, not the de-excitation rate.
- settingsdict
See description in read_data
- datacachedict
See description in read_data
- Returns:
- float or array(float)
Maxwellian rate coefficient, in units of cm^3 s^-1 For collisional excitation (proton or electron) returns excitation, dexcitation rates
Examples
>>> Te = numpy.logspace(4,9,20)
>>> # (1) Get excitation rates for row 12 of an Fe XVII file >>> colldata = pyatomdb.atomdb.get_data(26,17,'EC') >>> exc, dex = get_maxwell_rate(Te, colldata=colldata, index=12)
>>> # (2) Get excitation rates for row 12 of an Fe XVII file >>> exc, dex = get_maxwell_rate(Te, Z=26,z1=17, index=12)
>>> (3) Get excitation rates for transitions from level 1 to 15 of FE XVII >>> exc, dex = get_maxwell_rate(Te, Z=26, z1=17, dtype='EC', finallev=15, initlev=1)
- pyatomdb.atomdb.get_oscillator_strength(Z, z1, upperlev, lowerlev, datacache=False)[source]
Get the oscillator strength f_{ij} of a transition
- Parameters:
- Zint
The atomic number of the element
- z1int
The ion charge + 1 of the ion
- upperlevint
The upper level, indexed from 1
- lowerlevint
The lower level, indexed from 1
- datacachedict
Used for caching the data. See description in get_data
- Returns:
- float
The oscillator strength. Returns 0 if transition not found. If transition is not found but the inverse transition is present the oscillator strength is calculated for this instead.
- pyatomdb.atomdb.make_lorentz(version=False, do_all=True, cie=False, power=False, stronglines=False, neicsd=False, neilines=False, neicont=False, levpop=False)[source]
This makes all the Lorentz data comparison files from the Astrophysical Collisional Plasma Test Suite, version 0.4.0
- Parameters:
- versionstring (optional)
e.g. “3.0.7” to run the suite for v3.0.7. Otherwise uses latest version.
- Returns:
- none
- pyatomdb.atomdb.read_filemap(filemap='$ATOMDB/filemap', atomdbroot='$ATOMDB')[source]
Reads the AtomDB filemap file in to memory. By default, tries to read $ATOMDB/filemap, replacing all instances of $ATOMDB in the filemap file with the value of the environment variable $ATOMDB
- Parameters:
- filemap: str
the filemap file to read
- atomdbroot: str
location of files, if not $ATOMDB.
- pyatomdb.atomdb.rrc_ph_value(E, Z, z1, rrc_ph_factor, IonE, kT, levdat, xstardata=False, xstarfinallev=False)[source]
Returns RRC in photons cm3 s-1 keV-1
- Parameters:
- E:
- Z: int
Atomic number of element (i.e. 8 for Oxygen)
- z1: int
Ion charge +1 e.g. 5 for C+4, a.k.a. C V
- rrc_ph_factor: float
Conversion factor for RRC.
- IonE: float
Ionization potential of ion
- kT: float
Temperature (keV)
- levdat: lvdat line
Line from the lvdat file
- xstardatadict, str or HDUList
if the data is XSTAR data (pi_type=3), supply the xstardata. This can be a dictionary with 2 arrays, one “Energy”, one “sigma”, the file name, or the entire PI file (already loaded):
# load level data lvdata = atomdb.get_data(26, 24, 'LV', settings) # load XSTAR PI data if it exists pidata = atomdb.get_data(26, 24, 'PI', settings) # get pi xsection at energy E for the ground state to ground state sigma_photoion(E, lvdata[1].data['pi_type'][0], lvdata[1].data['pi_param'][0], xstardata=pidata, xstarfinallev=1)
- xstarfinallev: the level to ionize in to. Defaults to 1.
- Returns:
- float
The RRC in photons cm3 s-1 keV-1 at energy(ies) E.
- pyatomdb.atomdb.sigma_photoion(E, Z, z1, pi_type, pi_coeffts, xstardata=False, xstarfinallev=1)[source]
Returns the photoionization cross section at E, given an input of sig_coeffts.
- Parameters:
- E: float or array of floats
Energy/ies to find PI cross section at (keV)
- Z: int
Atomic number of element (i.e. 8 for Oxygen)
- pi_typeint
the “PI_TYPE” from the energy level file for this level, can be:
-1. No PI data 0. Hydrogenic 1. Clark 2. Verner 3. XSTAR
- pi_coefftsarray(float)
the “PI_PARAM” array for this level from the LV file
- xstardatadict, str or HDUList
if the data is XSTAR data (pi_type=3), supply the xstardata. This can be a dictionary with 2 arrays, one “Energy”, one “sigma”, the file name, or the entire PI file (already loaded):
# load level data lvdata = atomdb.get_data(26, 24, 'LV', settings) # load XSTAR PI data if it exists pidata = atomdb.get_data(26, 24, 'PI', settings) # get pi xsection at energy E for the ground state to ground state sigma_photoion(E, lvdata[1].data['pi_type'][0], lvdata[1].data['pi_param'][0], xstardata=pidata, xstarfinallev=1)
- xstarfinallev: the level to ionize in to. Defaults to 1.
- Returns:
- array(float)
pi cross section in cm^2 at energy E.
- pyatomdb.atomdb.write_filemap(d, filemap, atomdbroot='')[source]
Write filemap to file
- Parameters:
- ddict
Dictionary with filemap data in it. Structure defined as return value from read_filemap.
- filemapstr
Name of filemap file to read. If zero length, use “$ATOMDB/filemap”
- atomdbrootstr
Replace any $ATOMDB in the file names with this. If not provided, use “ATOMDB” environment variable instead
- Returns:
- none