util module

This modules contains simple utility codes (sorting, file handling etc) that pyatomdb relies on.

util.py contains a range of miscellaneous helper codes that assist in running other AtomDB codes but are not in any way part of a physical calculation.

Version -.1 - initial release Adam Foster July 17th 2015

exception pyatomdb.util.NotImplementedError

Bases: ValueError

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception pyatomdb.util.OptionError

Bases: ValueError

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception pyatomdb.util.ReadyError

Bases: ValueError

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception pyatomdb.util.UnitsError

Bases: ValueError

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

pyatomdb.util.check_version()

Checks if there is a more recent version of the database to install.

Parameters
None.
Returns
None
pyatomdb.util.convert_spec(spec, specunit, specunitout)

Convert spectral ranges from specunit to specunitout

Parameters
specarray

The units to return

specunitstring

The input spectral unit (‘keV’, ‘A’)

specunitoutstring

The output spectral unit (‘keV’, ‘A’)

Returns
specoutarray

spec, converted to specunitout

pyatomdb.util.convert_temp(Te, teunit, teunitout)

Convert temperature (Te) from units teunit to teunitout

Parameters
Tefloat

The temperature

teunitstring

units of Te

teunitoutstring

output temperature units

pyatomdb.util.download_atomdb_emissivity_files(adbroot, userid, version)

Download the AtomDB equilibrium emissivity files for AtomDB”

This code will go to the AtomDB FTP site and download the necessary files. It will then unpack them into a directory adbroot. It will not overwrite existing files with the same md5sum (to avoid pointless updates) but it will not know this until it has downloaded and unzipped the main file.

Parameters
adbrootstring

The location to install the data. Typically should match $ATOMDB

useridstring

An 8 digit ID number. Usually passed as a string, but integer is also fine (provided it is all numbers)

versionstring

The version string for the release, e.g. “3.0.2”

Returns
None
pyatomdb.util.download_atomdb_nei_emissivity_files(adbroot, userid, version)

Download the AtomDB non-equilibrium emissivity files for AtomDB”

This code will go to the AtomDB FTP site and download the necessary files. It will then unpack them into a directory adbroot. It will not overwrite existing files with the same md5sum (to avoid pointless updates) but it will not know this until it has downloaded and unzipped the main file.

Parameters
adbrootstring

The location to install the data. Typically should match $ATOMDB

useridstring

An 8 digit ID number. Usually passed as a string, but integer is also fine (provided it is all numbers)

versionstring

The version string for the release, e.g. “3.0.2”

Returns
None
pyatomdb.util.figcoords(lowxpix, lowypix, highxpix, highypix, lowxval, lowyval, highxval, highyval, xpix, ypix, logx=False, logy=False)
pyatomdb.util.generate_equilibrium_ionbal_files(filename, settings=False)

Generate the eigen files that XSPEC uses to calculate the ionizatoin balances

Parameters
filenamestring

file to write

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

Returns
none
pyatomdb.util.generate_isis_files(version='', outfile='atomdb_VERSION_lineid.tar.bz2')

Generate the atomic data necessary solely for identifying lines in AtomDB. Useful in ISIS, for example.

Parameters
versionstring

version number to generate line ID tarball for. Defaults to version in $ATOMDB/VERSION

outfilestring

the file to be generated. Defaults to atomdb_VERSION_lineid.tar.bz2

Returns
——-
none
pyatomdb.util.generate_web_fitsfiles(version='', outdir='')

Split the linelist files into many small files and make an index for them

Parameters
versionstring

version number to generate this for. Defaults to version in $ATOMDB/VERSION

outdirstring

Output files will be placed in this directory. Defaults to ‘webonly”

Returns
——-
none
pyatomdb.util.generate_xspec_ionbal_files(Z, filesuffix, settings=False)

Generate the eigen files that XSPEC uses to calculate the ionizatoin balances

Parameters
Zint

atomic number of element

filesuffixstring

the filename will be eigenELSYMB_filesuffix.fits

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

Returns
none
pyatomdb.util.initialize()

Initialize your AtomDB Setup

This code will let you select where to install AtomDB, get the latest version of the filemap, and download the emissivity files needed for various functions to work.

Parameters
None.
Returns
None
pyatomdb.util.keyword_check(keyword)

Returns False is the keyword is in fact false, otherwise returns True

Parameters
keyword: any

The keyword value

Returns
bool

True if the keyword is set to not False, otherwise False

pyatomdb.util.load_user_prefs(adbroot='$ATOMDB')

Loads user preference data from $ATOMDB/userdata

Parameters
adbrootstring

The AtomDB root directory. Defaults to environment variable $ATOMDB.

Returns
dictionary

keyword/setting pairs e.g. settings[‘USERID’] = “12345678”

pyatomdb.util.make_linelist(linefile, outfile)

Create atomdb linelist file from line.fits file

Parameters
linefilestring

The filename of the line file

outfilestring

The output filename of the string

Returns
none
pyatomdb.util.make_release_filetree(filemapfile_in, filemapfile_out, replace_source, destination, versionname)

Take an existing filemap, copy the files to the atomdbftp folder as required.

Parameters
filemapfile_instring

The existing filemap file for the new release

filemapfile_outstring

The filename for the produced filemap

replace_sourcestring

All new files are in this directory.

destinationstring

The folder to store the files in

versionnamestring

The version string for the new files (e.g. 3_0_4)

Returns
None

Notes

This code searches for any files which don’t have $ATOMDB in the filename and assumes they are new.

It updates the file name to be $ATOMDB/elname/elname_ion/elname_ion_FTYPE_versionname.fits

Versionname will have its last number stsripped and replaced with “a”. So 3_0_4_2 becomes 3_0_4_a. This reflects that 4-number versions are for revisions of a file under development, while 3 number + letter are for released data.

And then copies it to the destination folder, compressing it with gzip.

pyatomdb.util.make_release_tarballs(ciefileroot, neifileroot, filemap, versionname, releasenotes, parfile, neiparfile, makelinelist=False)

Create tarball for exmissivity files for a new release.

Parameters
ciefilerootstring

The path to the CIE line and coco files, with the _line.fits and _coco.fits ommitted.

neifilerootstring

The path to the NEI line and coco files, with the _line.fits and _comp.fits ommitted.

filemapstring

The filemap file

versionnamestring

The version string for the new files (e.g. 3.0.4).

releasenotesstring

The file name for the release notes.

parfilestring

The parameter file used to create the data

neiparfilestring

The parameter file used to create the NEI data

makelinelistbool

Remake the line list from the line file. If not specified, assumes linelist file already exists.

Returns
None
pyatomdb.util.make_vec(d)

Create vector version of d, return True or false depending on whether input was vector or not

Parameters
d: any scalar or vector

The input

Returns
vecdarray of floats

d as a vector (same as input if already an iterable type)

isvecbool

True if d was a vector, otherwise False.

pyatomdb.util.md5Checksum(filePath)

Calculate the md5 checksum of a file

Parameters
filepathstr

the file to calculate the md5sum of

Returns
string

the hexadecimal string md5 hash of the file

References

Taken from http://joelverhagen.com/blog/2011/02/md5-hash-of-file-in-python/

pyatomdb.util.mkdir_p(path)

Create a directory. If it already exists, do nothing.

Parameters
pathstring

The directory to make

Returns
none
pyatomdb.util.question(question, default, multichoice=[])

Ask question with default answer provided. Return answer

Parameters
questionstr

Question to ask

defaultstr

Default answer to question

multichoicestr

if set, answer must be one of these choices

Returns
str

The answer.

pyatomdb.util.record_upload(fname)

Transmits record of a file transfer to AtomDB

This simply transmits the USERID, filename, and time to AtomDB. If USERID=0, then the user has chosen not to share this information and this is skipped

Parameters
fnamestring

The file name being downloaded.

Returns
None
pyatomdb.util.switch_version(version, force=False)

Changes the AtomDB version. Note this will overwrite several links on your hard disk, and will NOT be repaired upon quitting python.

The files affect are the VERSION file and the soft links $ATOMDB/apec_line.fits, $ATOMDB/apec_coco.fits, $ATOMDB/filemap and $ATOMDB/apec_linelist.fits

Parameters
version: string

The version of AtomDB to switch to. Should be of the form “2.0.2”

forcebool

If True, force a re-download of all the relevant files regardless of whether they already exist or not.

Returns
None
pyatomdb.util.unique(s)

Return a list of the elements in s, but without duplicates.

For example, unique([1,2,3,1,2,3]) is some permutation of [1,2,3], unique(“abcabc”) some permutation of [“a”, “b”, “c”], and unique(([1, 2], [2, 3], [1, 2])) some permutation of [[2, 3], [1, 2]].

For best speed, all sequence elements should be hashable. Then unique() will usually work in linear time.

If not possible, the sequence elements should enjoy a total ordering, and if list(s).sort() doesn’t raise TypeError it’s assumed that they do enjoy a total ordering. Then unique() will usually work in O(N*log2(N)) time.

If that’s not possible either, the sequence elements must support equality-testing. Then unique() will usually work in quadratic time.

Parameters
slist type object

List to remove the duplicates from

Returns
list type object

…with all the duplicates removed

References

Taken from Python Cookbook, written by Tim Peters. http://code.activestate.com/recipes/52560/

pyatomdb.util.write_ai_file(fname, dat, clobber=False)

Write the data in list dat to fname

Parameters
fnamestring

The file to write

datlist

The data to write. Should be a list with the following keywords:

  • Z : int: nuclear charge

  • z1 : int: ion charge + 1

  • comments : iterable of strings: comments to append to the file

  • data : numpy.array : stores all the individual level data, with the following types:

    • ion_init : int : Inital ion state of transition

    • ion_final : int : Final ion state of transition

    • level_init : int : Initial level of transition

    • level_final : int : Final level of transition

    • auto_rate : float : Autoionization rate (s-1)

    • auto_err : float : Error in autoionization rate (s-1)

    • auto_ref : string(20) : Autoionization rate reference (bibcode)

clobberbool

Overwrite existing file if it exists.

Returns
none
pyatomdb.util.write_develop_data(data, filemapfile, Z, z1, ftype, folder, froot)
pyatomdb.util.write_dr_file(fname, dat, lvdat=None, clobber=False)

Write the data in list dat to fname

Parameters
fnamestringThe file to write
datlistThe data to write. Should be a list with the following keywords:

  • Z : int : nuclear charge

  • z1 : int: ion charge + 1

  • comments : iterable of strings: comments to append to the file

  • data : numpy.array: stores all the individual level data, with the following types

    • upper_lev : int : upper level of transition

    • lower_lev : int : lower level of transition

    • wavelen : float : Wavelength of transtion (A)

    • wave_obs : float : Observed wavelength of transition (A)

    • wave_err : float Error in wavelength (A)

    • dr_type : int : DR data type. 1=Jaconelli, 2 = Safranova

    • e_excite : float : transition excitation energy (keV)

    • eexc_err : float : error in transition excitation energy (keV)

    • satelint : float : intensity factor (s-1)

    • satinterr : float : error in intensity factor (s-1)

    • params : float(10) : parameters

    • drrate_ref : string(20) : DR rate reference (usually bibcode)

    • wave_ref : string(20) : wavelength reference (bibcode)

    • wv_obs_ref : string(20) : observed wavelength reference (bibcode)

clobberbool

Overwrite existing file if it exists.

Returns
none
pyatomdb.util.write_ec_file(fname, dat, clobber=False)

Write the data in list dat to fname

Parameters
fnamestring

The file to write

datlist

The data to write. Should be a list with the following keywords:

  • Z : int : nuclear charge

  • z1 : int : ion charge + 1

  • comments : iterable of strings: comments to append to the file

  • data : numpy.array : stores all the individual level data, with the following types:

    • lower_lev : int : Lower level of transition

    • upper_lev : int : Upper level of transition

    • coeff_type : int : Coefficient type

    • min_temp : float : Minimum temperature in range (K)

    • max_temp : float : Maximum temperature in range (K)

    • temperature : float(20) : List of temperatures (K)

    • effcollstrpar : float(20) : Effective collision strength parameters

    • inf_limit : float (OPTIONAL - if type 1.2.0) : High temperature limit point, if provided.

    • reference : string(20) : Collisional excitation reference (bibcode)

clobberbool

Overwrite existing file if it exists.

Returns
none
pyatomdb.util.write_ionbal_file(Te, dens, ionpop, filename, Te_linear=False, dens_linear=False)

Create ionization balance file

Parameters
Tearray(float)

temperatures (in K)

densarray(float)

electron densities (in cm^-3)

ionpopdict of arrays

one entry for each element: ionpop[2] = numpy.array(nion,nte, ndens)

filenamestr

filename to write to

Te_linearbool

if true, temperature grid is linear

dens_linearbool

if true, density grid is linear

pyatomdb.util.write_ir_file(fname, dat, clobber=False)

Write the data in list dat to fname

Parameters
fnamestring

The file to write

datlist

The data to write. Should be a list with the following keywords:

  • Z : int : nuclear charge

  • z1 : int : ion charge + 1

  • comments : iterable of strings : comments to append to the file

  • ionpot : float : ionization potential (eV)

  • ip_dere : float : ionization potential (eV) (from dere, optional)

  • data : numpy.array : stores all the individual level data, with the following types:

    • element : int : Nuclear Charge

    • ion_init : int : Initial ion stage

    • ion_final : int : Final ion stage

    • level_init : int : Initial level

    • level_final : int : Final level

    • tr_type : string(2) : Transition type:

      CI = collisional excitaion
EA = excitation autoionization
RR = radiative recombination
DR = dieclectronic recombination
XI = ionization, excluded from total rate calculation
XR = recombination, excluded from total rate calculation
(XR and XI are used to populate level directly)

    • tr_index : int : index within the file

    • par_type : int : parameter type, i.e. how the data is stored

    • min_temp : float : Minimum temperature in range (K)

    • max_temp : float : Maximum temperature in range (K)

    • temperature : float(20) : List of temperatures (K)

    • ionrec_par : float(20) : Ionization and recombination rate parameters

    • wavelen : float : Wavelength of emitted lines (A) [not used]

    • wave_obs : float : Observed wavelength of emitted lines (A) [not used]

    • wave_err : float : Error in these wavelengths (A) [not used]

    • br_ratio : float : Branching ratio of this line [not used]

    • br_rat_err : float : Error in branching ratio [not used]

    • label : string(20) : Label for the transition

    • rate_ref : string(20) : Rate reference (bibcode)

    • wave_ref : string(20) : Wavelength reference (bibcode)

    • wv_obs_ref : string(20) : Observed wavelength reference (bibcode)

    • br_rat_ref : string(20) : Branching ratio reference (bibcode)

clobberbool

Overwrite existing file if it exists.

Returns
none
pyatomdb.util.write_la_file(fname, dat, clobber=False)

Write the data in list dat to fname

Parameters
fnamestring

The file to write

datlist

The data to write. Should be a list with the following keywords:

  • Z : int : nuclear charge

  • z1 : int : ion charge + 1

  • comments : iterable of strings : comments to append to the file

  • data : numpy.array: stores all the individual level data, with the following types:

    • upper_lev : int : Upper level of transition

    • lower_lev : int : Lower level of transition

    • wavelen : float : Wavelength of transition (A)

    • wave_err : float : Error in wavelength (A)

    • einstein_a : float : Einstein A coefficient (s-1)

    • ein_a_err : float : Error in A coefficient (s-1)

    • wave_ref : string(20) : wavelength reference (bibcode)

    • ein_a_ref : string(20) : A-value reference (bibcode)

clobberbool

Overwrite existing file if it exists.

Returns
none
pyatomdb.util.write_lv_file(fname, dat, clobber=False)

Write the data in list dat to fname

Parameters
fnamestringThe file to write
datlistThe data to write. Should be a list with the following keywords:

  • Z : int : nuclear charge

  • z1 : int: ion charge + 1

  • comments : iterable of strings: comments to append to the file

  • data : numpy.array: stores all the individual level data, with the following types

    • elec_config : string (40 char max) : Electron configuration strings

    • energy : float: Level energy (eV)

    • e_error : float : Energy level error (eV)

    • n_quan : int : N quantum number

    • l_quan : int : L quantum number

    • s_quan : float : S quantum number

    • lev_deg : int : level degeneracy

    • phot_type : int : photoionization data type:

      -1. none

 0. hydrogenic

 1. Clark

 2. Verner

 3. XSTAR data

    • phot_par : float(20) : photoionization paramters (see specific PI type for definition)

    • Aaut_tot : float (optional) : the total autoionization rate out of the level (s^-1)

    • Arad_tot : float (optional) : the total radiative rate out of the level (s^-1)

    • energy_ref : string(20) : energy reference (usually bibcode)

    • phot_ref : string(20) : photoionization reference (bibcode)

    • Aaut_ref : string(20) : total autoionization rate reference (bibcode)

    • Arad_ref : string(20) : total radiative decay rate reference (bibcode)

clobberbool

Overwrite existing file if it exists.

Returns
none
pyatomdb.util.write_user_prefs(prefs, adbroot='$ATOMDB')

Write user preference data to $ATOMDB/userdata. This will overwrite the entire file.

Therefore you should use “load_user_prefs”, then add in additional keywords, the call write_user_prefs.

Parameters
prefs: dictionary

keyword/setting pairs e.g. settings[‘USERID’] = “12345678”

adbrootstring

The AtomDB root directory. Defaults to environment variable $ATOMDB.

Returns
None