apec module

This modules contains the APEC code. It calls many different subroutines from throughout the PyAtomDB module.

It is expected (as of May 2020) that this code will go through a major rewrite to make it more pythonic and to make many helper routines private to declutter the module. Be wary of embedding too many links to this module in your code.

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)[source]

calculate the bremstrahulung free-free gaunt factor

Parameters:
Efloat

Energy (in keV) to calculate gaunt factor

Tfloat

Temperature (in K) of plasma

z1int

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

brems_typeint

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

settingsdict

See description in atomdb.get_data

datacachedict

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

Returns:
gaunt_fffloat

The gaunt factor for the free-free process.

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

calculate the electron-electron bremsstrahlung.

Parameters:
Earray (float)

energy grid (keV)

Tfloat

Electron temperature (keV)

Nfloat

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=False, init_pop='ionizing', Te_init=False, Zlist=False, teunit='K', extrap=True, cie=True, settings=False, datacache=False)[source]

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:
Tefloat

electron temperature in keV or K (default K)

taufloat

N_e * t for the non-equilibrium ioniziation (default False, i.e. off)

init_popdict 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_initfloat

initial ionization balance temperature, same units as Te

Zlistint 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)

extrapbool

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

ciebool

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

Returns:
final_popdict 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)[source]

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, dronly=False, rronly=False)[source]

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
T: 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)[source]

Calcaulate DR satellite lines

Parameters:
Z: int

The nuclear charge of the element Z: int

z1int

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)[source]

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

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

Compress the continuum into linear interpolatable grids

Parameters:
xinarray(float)

The bin edges (keV)

yinarray(float)

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

tolerancefloat

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

Returns:
xoutarray (float)

The energy points of the compressed energy grid (keV)

youtarray (float)

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

pyatomdb.apec.continuum_append(a, b)[source]

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)[source]
pyatomdb.apec.create_cparamhdu_cie(cocodata)[source]
pyatomdb.apec.create_lhdu_cie(linedata)[source]
pyatomdb.apec.create_lhdu_nei(linedata)[source]
pyatomdb.apec.create_lparamhdu_cie(linedata)[source]
pyatomdb.apec.do_brems(Z, z1, T, abund, brems_type, eedges)[source]

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

Parameters:
Zint

nuclear charge for which result is required

z1int

ion charge +1

Tfloat

temperture (Kelvin)

abundfloat

elemental abundance (should be between 1.0 and 0.0)

brems_typeint

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

eedgesarray(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)[source]

Convert level populations into line lists

Parameters:
Z: int

The nuclear charge of the element

z1int

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

lev_poparray(float)

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

N_efloat

Electron Density (cm^-3)

datacachedict

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

settingsdict

See description in atomdb.get_data

z1_drv_inint

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)[source]

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

Parameters:
Zint

Z for which result is required

gamma2array(float)

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

gaunt_Uarray(float)

u=E/kT

gaunt_Zarray(int)

nuclear charge

gaunt_Ngarray(int)

number of gamma^2 factors

gaunt_g2array(float)

gamma^2 factors

gaunt_gfarray(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)[source]

fetch the rates for all the levels of Z, z1

Parameters:
Z: int

The nuclear charge of the element

z1int

ion charge +1

tefloat

temperture (Kelvin)

dens: float

electron density (cm^-3)

settingsdict

See description in atomdb.get_data

datacachedict

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)[source]

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

Parameters:
settings: dict

The output of read_apec_parfile

hdulistlist or array of fits HDUs

The hdus to have headings added.

Returns:
None
pyatomdb.apec.generate_cie_outputs(settings, Z, linelist, contlist, pseudolist)[source]

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)[source]

returns the various data types needed by apec

Parameters:
dtypestring

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

npseudoint (default=0)

Number of pseudocontinuum points for “continuum” type

ncontinuumint (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)[source]

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)[source]

Correction factors to Kellogg bremstrahlung calculation by Bob Kurucz

Parameters:
uinarray(float)

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

gamarray(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)[source]

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)[source]

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)[source]

Parse the apec.par input file for controlling APEC

Parameters:
fnamestring

file name

Returns:
dict

The settings in “key:value” pairs.

pyatomdb.apec.return_ionbal(Z, Te, init_pop=False, tau=False, teunit='K', filename=False, datacache=False, fast=True, settings=False, debug=False, extrap=True)[source]

Solve the ionization balance for a element Z.

Parameters:
Zint

atomic number of element

Tefloat or array

electron temperature(s), default in K

init_popfloat array

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

taufloat or array

N_e * t for the non-equilibrium ioniziation, in cm^3 s^-1.

Te_initfloat

initial ionization balance temperature, same units as Te

teunit{‘K’ , ‘keV’}

units of temperatures (default K)

filenamestring

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.

datacachedict

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

fastbool

If true, use precalculated eigenvector files to obtain CIE and NEI results

Returns:
final_popfloat array

final populations.

pyatomdb.apec.run_apec(fname)[source]

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

Parameters:
fnamestring

file name

Returns:
None
pyatomdb.apec.run_apec_element(settings, te, dens, Z)[source]

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)[source]

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:
linelistnumpy array

List of line details and emissivities

continuumarray

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

pseudocontarray

Pseudo Continuum emission in photons bin-1 s-1

pyatomdb.apec.run_wrap_run_apec(fname, Z, iTe, iDens)[source]

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

Parameters:
fnamestring

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)[source]

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:
ionratefloat array

the ionization rates, starting with neutral ionizing to +1

recratefloat array

the recombination rates, starting with singly ionized recombining to neutral

init_popfloat array

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

taufloat

N_e * t for the non-equilibrium ioniziation

Returns:
final_popfloat array

final populations.

Notes

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

pyatomdb.apec.solve_level_pop(init, final, rates, settings)[source]

Solve the level population

Parameters:
initarray(int)

The initial level for each transition

finalarray(int)

The initial level for each transition

ratesarray(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)[source]
pyatomdb.apec.wrap_run_apec(fname, readpickle=False, writepickle=False)[source]

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

Parameters:
fnamestring

file name

readpicklebool

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)[source]

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