PyAtomDB Util module

This modules contains simple utility codes (sorting 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

pyatomdb.util.check_version()

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

Parameters:None.
Returns:None
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:

adbroot : string

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

userid : string

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

version : string

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:

adbroot : string

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

userid : string

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

version : string

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:

filename : string

file to write

settings : dict

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_isis.tar.bz2')

Generate the ISIS tarball

Parameters:

version : string

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

outfile : string

the file to be generated. Defaults to atomdb_VERSION_isis.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:

version : string

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

outdir : string

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:

Z : int

atomic number of element

filesuffix : string

the filename will be eigenELSYMB_filesuffix.fits

settings : dict

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:

adbroot : string

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:

linefile : string

The filename of the line file

outfile : string

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_in : string

The existing filemap file for the new release

filemapfile_out : string

The filename for the produced filemap

replace_source : string

All new files are in this directory.

destination : string

The folder to store the files in

versionname : string

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:

ciefileroot : string

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

neifileroot : string

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

filemap : string

The filemap file

versionname : string

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

releasenotes : string

The file name for the release notes.

parfile : string

The parameter file used to create the data

neiparfile : string

The parameter file used to create the NEI data

makelinelist : bool

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:

vecd : array of floats

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

isvec : bool

True if d was a vector, otherwise False.

pyatomdb.util.md5Checksum(filePath)

Calculate the md5 checksum of a file

Parameters:

filepath : str

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:

path : string

The directory to make

Returns:

none

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

Ask question with default answer provided. Return answer

Parameters:

question : str

Question to ask

default : str

Default answer to question

multichoice : str

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:

fname : string

The file name being downloaded.

Returns:

None

pyatomdb.util.switch_version(version)

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”

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:

s : list 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:

fname : string

The file to write

dat : list

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)

clobber : bool

Overwrite existing file if it exists.

Returns:

none

pyatomdb.util.write_develop_data(data, filemapfile, Z, z1, ftype, folder, froot)
pyatomdb.util.write_ec_file(fname, dat, clobber=False)

Write the data in list dat to fname

Parameters:

fname : string

The file to write

dat : list

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)

clobber : bool

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:

Te : array(float)

temperatures (in K)

dens : array(float)

electron densities (in cm^-3)

ionpop : dict of arrays

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

filename : str

filename to write to

Te_linear : bool

if true, temperature grid is linear

dens_linear : bool

if true, density grid is linear

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

Write the data in list dat to fname

Parameters:

fname : string

The file to write

dat : list

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)

clobber : bool

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:

fname : string

The file to write

dat : list

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)

clobber : bool

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:

fname : string

dat : list

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

clobber : bool

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”

adbroot : string

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

Returns:

None