PyAtomDB APEC module

This modules contains the APEC code. It calls many different subroutines from throughout the PyAtomDB module. Currently largely unwritten, as APEC code needs to be tidied up for transfer.

The apec module contains routines crucial for the APEC code. This also includes some interfaces to external C libraries (or will, eventually).

Version 0.1 - initial release Adam Foster September 16th 2015

pyatomdb.apec.calc_brems_gaunt(E, T, z1, brems_type, datacache=False, settings=False)

calculate the bremstrahulung free-free gaunt factor

Parameters:

E : float

Energy (in keV) to calculate gaunt factor

T : float

Temperature (in K) of plasma

z1 : int

Ion charge +1 of ion (e.g. 6 for C VI)

brems_type : int

Type of bremstrahlung requested: 1 = HUMMER = Non-relativistic: 1988ApJ...327..477H 2 = KELLOGG = Semi-Relativistic: 1975ApJ...199..299K 3 = RELATIVISTIC = Relativistic: 1998ApJ...507..530N 4 = BREMS_NONE = no bremstrahlung

settings : dict

See description in atomdb.get_data

datacache : dict

Used for caching the data. See description in atomdb.get_data

Returns:

gaunt_ff : float

The gaunt factor for the free-free process.

pyatomdb.apec.calc_cascade_population(matrixA, matrixB)
pyatomdb.apec.calc_ee_brems(E, T, N)

calculate the electron-electron bremsstrahlung.

Parameters:

E : array (float)

energy grid (keV)

T : float

Electron temperature (keV)

N : float

electron density (cm^-3)

Returns:

array(float)

ee_brems in photons cm^s s^-1 keV-1 at each point E. This should be multiplied by the bin width to get flux per bin.

References

Need to check this!

pyatomdb.apec.calc_full_ionbal(Te, tau=100000000000000.0, init_pop=False, Te_init=False, Zlist=False, teunit='K', extrap=True, cie=True, settings=False)

Calculate the ionization balance for all the elements in Zlist.

One of init_pop or Te_init should be set. If neither is set, assume all elements start from neutral.

Parameters:

Te : float

electron temperature in keV or K (default K)

tau : float

N_e * t for the non-equilibrium ioniziation (default 1e14)

init_pop : dict of float arrays, indexed by Z

initial populations. E.g. init_pop[6]=[0.1,0.2,0.3,0.2,0.2,0.0,0.0]

Te_init : float

initial ionization balance temperature, same units as Te

Zlist : int array

array of nuclear charges to include in calculation (e.g. [8,26] for oxygen and iron)

teunit : {‘K’ , ‘keV’}

units of temperatures (default K)

extrap : bool

Extrappolate rates to values outside their given range. (default False)

cie : bool

If true, collisional ionization equilbrium calculation (tau, init_pop, Te_init all ignored)

Returns:

final_pop : dict of float arrays, indexed by Z

final populations. E.g. final_pop[6]=[0.1,0.2,0.3,0.2,0.2,0.0,0.0]

pyatomdb.apec.calc_ioniz_popn(levpop, Z, z1, z1_drv, T, Ne, settings=False, datacache=False, do_xi=False)

Calculate the level population due to ionization into the ion

Parameters:

levpop: array(float)

The level population of the parent ion. Should already have abundance and ion fraction built in.

Z: int

z1: int

z1_drv: int

T: float

Ne: float

settings: dict

datacache: dict

do_xi: bool

Include collisional ionization

Returns:

levpop_out: array(float)

The level populations of the Z,z1 ion

pyatomdb.apec.calc_recomb_popn(levpop, Z, z1, z1_drv, T, dens, drlevrates, rrlevrates, settings=False, datacache=False)

Calculate the level population of a recombined ion

Parameters:

levpop: array(float)

Level populations, already taking into account elemental abundance and ion fraction of z1_drv

Z: int

z1: int

z1_drv: int

te: electron temperature (K)

dens: electron density (cm^-3)

drlevrates: array(float)

Rates into each level from DR calculations

rrlevrates: array(float)

Rates into each level from RR calculations

Returns:

array(float)

Level population

pyatomdb.apec.calc_satellite(Z, z1, T, datacache=False, settings=False)

Calcaulate DR satellite lines

Parameters:

Z: int

The nuclear charge of the element Z: int

z1 : int

Recombined Ion charge +1 of ion (e.g. 5 for C VI -> C V)

te: float

The electron temperature (K)

settings: dictionary

The settings read from the apec.par file by parse_par_file

Returns:

array(linelist)

List of DR lines

array(levlistin)

Rates into each lower level, driven by DR

pyatomdb.apec.calc_total_coco(cocodata, settings)

Calculate the total emission in erg cm^3 s^-1

pyatomdb.apec.compress_continuum(xin, yin, tolerance, minval=0.0)

Compress the continuum into linear interpolatable grids

Parameters:

xin : array(float)

The bin edges (keV)

yin : array(float)

The continuum in photons (or ergs) cm^3 s^-1 bin^-1. Should be 1 element shorter then xin

tolerance : float

The tolerance of the final result (if 0.01, the result will always be within 1% of the original value)

Returns:

xout : array (float)

The energy points of the compressed energy grid (keV)

yout : array (float)

The continuum, in photons(or ergs) cm^3 s^-1 keV^-1

pyatomdb.apec.continuum_append(a, b)

Join two continuum arrays together, expanding arrays as necessary

Parameters:

a: numpy.array(dtype=continuum)

The first array

b: numpy.array(dtype=continuum)

The second array

Returns

c: numpy.array(dtype=continuum)

The two arrays combined, with continuum arrays resized as required.

pyatomdb.apec.create_chdu_cie(cocodata)
pyatomdb.apec.create_cparamhdu_cie(cocodata)
pyatomdb.apec.create_lhdu_cie(linedata)
pyatomdb.apec.create_lhdu_nei(linedata)
pyatomdb.apec.create_lparamhdu_cie(linedata)
pyatomdb.apec.do_brems(Z, z1, T, abund, brems_type, eedges)

Calculate the bremstrahlung emission in units of photon cm^3 s^-1 bin^-1

Parameters:

Z : int

nuclear charge for which result is required

z1 : int

ion charge +1

T : float

temperture (Kelvin)

abund : float

elemental abundance (should be between 1.0 and 0.0)

brems_type : int

Type of bremstrahlung requested: 1 = HUMMER = Non-relativistic: 1988ApJ...327..477H 2 = KELLOGG = Semi-Relativistic: 1975ApJ...199..299K 3 = RELATIVISTIC = Relativistic: 1998ApJ...507..530N 4 = BREMS_NONE = no bremstrahlung

eedges : array(float)

The energy bin edges for the spectrum (keV)

Returns:

array(float)

bremstrahlung emission in units of photon cm^3 s^-1 bin^-1

pyatomdb.apec.do_lines(Z, z1, lev_pop, N_e, datacache=False, settings=False, z1_drv_in=-1)

Convert level populations into line lists

Parameters:

Z: int

The nuclear charge of the element

z1 : int

Ion charge +1 of ion (e.g. 6 for C VI)

lev_pop : array(float)

The level population for the ion. Should already have elemental abundance and ion fraction multiplied in.

N_e : float

Electron Density (cm^-3)

datacache : dict

Used for caching the data. See description in atomdb.get_data

settings : dict

See description in atomdb.get_data

z1_drv_in : int

the driving ion for this calculation, if not z1 (defaults to z1)

Returns:

linelist: numpy.dtype(linetype)

The list of lines and their emissivities. see generate_datatypes

twophot: array(float)

The two-photon continuum on the grid specified by the settings If settings[‘TwoPhoton’] is False, then returns a grid of zeros.

pyatomdb.apec.extract_gauntff(Z, gamma2, gaunt_U, gaunt_Z, gaunt_Ng, gaunt_g2, gaunt_gf)

Extract the appropriate Gaunt free-free factor from the relativistic data tables of Nozawa, Itoh, & Kohyama, 1998 ApJ, 507,530

Parameters:

Z : int

Z for which result is required

gamma2 : array(float)

gamma^2 in units of Z^2 Rydbergs/kT

gaunt_U : array(float)

u=E/kT

gaunt_Z : array(int)

nuclear charge

gaunt_Ng : array(int)

number of gamma^2 factors

gaunt_g2 : array(float)

gamma^2 factors

gaunt_gf : array(float)

ff factors

Returns:

array(float)

Gaunt factors.

References

Nozawa, Itoh, & Kohyama, 1998 ApJ, 507,530

pyatomdb.apec.gather_rates(Z, z1, te, dens, datacache=False, settings=False, do_la=True, do_ai=True, do_ec=True, do_pc=True, do_ir=True)

fetch the rates for all the levels of Z, z1

Parameters:

Z: int

The nuclear charge of the element

z1 : int

ion charge +1

te : float

temperture (Kelvin)

dens: float

electron density (cm^-3)

settings : dict

See description in atomdb.get_data

datacache : dict

Used for caching the data. See description in atomdb.get_data

Returns:

up: numpy.array(float)

Initial level of each transition

lo: numpy.array(float)

Final level of each transition

rate: numpy.array(float)

Rate for each transition (in s-1)

pyatomdb.apec.generate_apec_headerblurb(settings, linehdulist, cocohdulist)

Generate all the headers for an apec run, and apply them to the HDUlist.

Parameters:

settings: dict

The output of read_apec_parfile

hdulist : list or array of fits HDUs

The hdus to have headings added.

Returns:

None

pyatomdb.apec.generate_cie_outputs(settings, Z, linelist, contlist, pseudolist)

Convert a linelist and continuum values into an equilibrium AtomDB fits output

Parameters:

settings: dictionary

The settings read from the apec.par file by parse_par_file

Z: int

The nuclear charge of the element

linelist: numpy.array(dtype=linelisttype)

The list of lines, separated by ion

contlist: dict

Dictionary with the different continuum contributions from each ion. Each is an array of ph cm^3 s^-1 bin^-1

pseudolist: dict

Dictionary with the different pseudocontinuum contributions from each ion. Each is an array of ph cm^3 s^-1 bin^-1

Returns:

None

pyatomdb.apec.generate_datatypes(dtype, npseudo=0, ncontinuum=0)

returns the various data types needed by apec

Parameters:

dtype : string

One of “linetype”, “cielinetype”, “continuum”

npseudo : int (default=0)

Number of pseudocontinuum points for “continuum” type

ncontinuum : int (default=0)

Number of continuum points for “continuum” type

Returns:

numpy.dtype

The data dtype in question

pyatomdb.apec.generate_nei_outputs(settings, Z, linelist, contlist, pseudolist, ionfrac_nei)

Convert a linelist and continuum values into a non-equilibrium AtomDB fits output

Parameters:

settings: dictionary

The settings read from the apec.par file by parse_par_file

Z: int

The nuclear charge of the element

linelist: numpy.array(dtype=linelisttype)

The list of lines, separated by ion

contlist: dict

Dictionary with the different continuum contributions from each ion. Each is an array of ph cm^3 s^-1 bin^-1

pseudolist: dict

Dictionary with the different pseudocontinuum contributions from each ion. Each is an array of ph cm^3 s^-1 bin^-1

Returns:

None

pyatomdb.apec.kurucz(uin, gam)

Correction factors to Kellogg bremstrahlung calculation by Bob Kurucz

Parameters:

uin : array(float)

energy grid, units of E/kT (both in keV)

gam : array(float)

Z**2/T, in units of Rydbergs

Returns:

array(float)

gaunt factors at high gam (> 0.1)

pyatomdb.apec.make_vector(linear, minval, step, nstep)

Create a vector from the given inputs

Parameters:

linear: boolean

Whether the array should be linear or log spaced

minval: float

initial value of the array. In dex if linear==False

step: float

step between points on the array. In dex if linear==False

nstep: int

number of steps

Returns:

array(float)

array of values spaced out use the above parameters

pyatomdb.apec.make_vector_nbins(linear, minval, maxval, nstep)

Create a vector from the given inputs

Parameters:

linear: boolean

Whether the array should be linear or log spaced

minval: float

initial value of the array. In dex if linear==False

maxval: float

maximum value of the array. In dex if linear==False

nstep: int

number of steps

Returns:

array(float)

array of values spaced out use the above parameters

pyatomdb.apec.parse_par_file(fname)

Parse the apec.par input file for controlling APEC

Parameters:

fname : string

file name

Returns:

dict

The settings in “key:value” pairs.

pyatomdb.apec.run_apec(fname)

Run the entire APEC code using the data in the parameter file fname

Parameters:

fname : string

file name

Returns:

None

pyatomdb.apec.run_apec_element(settings, te, dens, Z)

Run the APEC code using the settings provided for one element

Parameters:

settings: dictionary

The settings read from the apec.par file by parse_par_file

te: float

The electron temperature (K)

dens: float

The electron density (cm^-3)

Z: int

The nuclear charge of the element

Returns:

None

pyatomdb.apec.run_apec_ion(settings, te, dens, Z, z1, ionfrac, abund)

Run the APEC code using the settings provided for an individual ion.

Parameters:

settings: dictionary

The settings read from the apec.par file by parse_par_file

te: float

The electron temperature (K)

dens: float

The electron density (cm^-3)

Z: int

The nuclear charge of the element

z1: int

The ion charge +1 of the ion

ionfrac: float

The fractional abundance of this ion (between 0 and 1)

abund: float

The elemental abundance of the element (normalized to H)

Returns:

linelist : numpy array

List of line details and emissivities

continuum : array

Continuum emission in photons bin-1 s-1. This is a 3-item dict, with “rrc”, “twophot”, “brems” entries for each continuum source

pseudocont : array

Pseudo Continuum emission in photons bin-1 s-1

pyatomdb.apec.run_wrap_run_apec(fname, Z, iTe, iDens)

After running the APEC code ion by ion, use this to combine into FITS files.

Parameters:

fname : string

file name of par file

Z: int

The atomic numbers

iTe: int

The temperature index

iDens: int

The density index

Returns:

None

pyatomdb.apec.solve_ionbal(ionrate, recrate, init_pop=False, tau=False)

solve_ionbal: given a set of ionization and recombination rates, find the equilibrium ionization balance. If init_pop and tau are set, do an non-equilibrium calculation starting from init_pop and evolving for n_e * t = tau (cm^-3 s)

Parameters:

ionrate : float array

the ionization rates, starting with neutral ionizing to +1

recrate : float array

the recombination rates, starting with singly ionized recombining to neutral

init_pop : float array

initial population of ions for non-equlibrium calculations. Will be renormalised to 1.

tau : float

N_e * t for the non-equilibrium ioniziation

Returns:

final_pop : float array

final populations.

Notes

Note that init_pop & final_pop will have 1 more element than ionrate and recrate.

pyatomdb.apec.solve_ionbal_eigen(Z, Te, init_pop=False, tau=False, Te_init=False, teunit='K', filename=False, datacache=False)

Solve the ionization balance for a range of ions using the eigenvector approach and files as distributed in XSPEC.

Parameters:

Z : int

atomic number of element

Te : float

electron temperature, default in K

init_pop : float array

initial population of ions for non-equlibrium calculations. Will be renormalised to 1.

tau : float

N_e * t for the non-equilibrium ioniziation

Te_init : float

initial ionization balance temperature, same units as Te

teunit : {‘K’ , ‘keV’}

units of temperatures (default K)

filename : string

Can optionally point directly to the file in question, i.e. to look at older data look at $HEADAS/../spectral/modelData/eigenELSYMB_v3.0.fits. If not set, download from AtomDB FTP site.

Returns:

final_pop : float array

final populations.

pyatomdb.apec.solve_level_pop(init, final, rates, settings)

Solve the level population

Parameters:

init : array(int)

The initial level for each transition

final : array(int)

The initial level for each transition

rates : array(float)

The rate for each transition

settings: dictionary

The settings read from the apec.par file by parse_par_file

Returns:

array(float)

The level population

pyatomdb.apec.wrap_ion_directly(fname, ind, Z, z1)
pyatomdb.apec.wrap_run_apec(fname, readpickle=False)

After running the APEC code ion by ion, use this to combine into FITS files.

Parameters:

fname : string

file name

readpickle : bool

Load apec results by element from pickle files, instead of regenerating

Returns:

None

pyatomdb.apec.wrap_run_apec_element(settings, te, dens, Z, ite, idens, writepickle=False, readpickle=False)

Combine wrap_run_apec_ion results for an element

Parameters:

settings: dictionary

The settings read from the apec.par file by parse_par_file

te: float

The electron temperature (K)

dens: float

The electron density (cm^-3)

Z: int

The nuclear charge of the element

ite: int

The temperature index

idens: int

The density index

writepickle: bool

Dump data into a pickle file. Useful for rapidly combining data after runs.

readpickle: bool

Read data from a pickle file. Useful for rapidly combining data after runs. Usually the result of a previous call using writepickle=True

Returns:

None