src

Submodules

amespahdb class

class amespahdbpythonsuite.amespahdb.AmesPAHdb(**keywords)

Bases: object

AmesPAHdbPythonSuite main class. Contains methods to parse the database, perform search based on query, and retrieve UIDs. Calls classes: amespahdbpythonsuite.transitions.Transitions, amespahdbpythonsuite.laboratory.Laboratory, amespahdbpythonsuite.species.Species, amespahdbpythonsuite.geometry.Geometry, to retrieve the respective instances.

checkversion(version: str) → bool

Method to check against a PAHdb version.

Returns:

Boolean whether a provided version matched the PAHdb version.

extenddatabase(**keywords) → None

Method to extend the database.

Returns:

None

getdatabaseref() → dict

Method to retrieve the database.

Returns:

Dictionary containing the parsed database.

getgeometrybyuid(uids: list[int] | int) → Geometry

Retrieve and return geometry instance based on UIDs input. UIDs should be a list, e.g. the output of search method. Calls the amespahdbpythonsuite.geometry.Geometry class and amespahdbpythonsuite.amespahdb.__getkeybyuids() method.

Parameters:

uidslist of integers

List of UIDs.

Returns:

geometry instance

getlaboratorybyuid(uids: list[int] | int) → Laboratory | None

Retrieve and return laboratory database instance based on UIDs input. UIDs should be a list, e.g. the output of search method. Calls the amespahdbpythonsuite.laboratory.Laboratory class.

Parameters:

uidslist of integers

List of UIDs.

Returns:

laboratory database instance

getspeciesbyuid(uids: list[int] | int) → Species

Retrieve and return species instance based on UIDs input. UIDs should be a list, e.g. the output of search method. Calls the amespahdbpythonsuite.species.Species class.

Parameters:

uidslist of integers

List of UIDs.

Returns:

species instance

gettransitionsbyuid(uids: list[int] | int) → Transitions

Retrieve and return transitions instance based on UIDs input. UIDs should be a list, e.g. the output of search method. Calls the amespahdbpythonsuite.transitions.Transitions class.

Parameters:

uidslist of integers

List of UIDs.

Returns:

transitions instance

gettype() → str

Method to retrieve the PAHdb type.

Returns:

String of PAHdb type.

getversion() → str

Method to retrieve the PAHdb version.

Returns:

String of PAHdb version.

static message(text, space: int = 55) → None

A method to print terminal message.

Parameters:

textstring or list of strings.

Text to be displayed.

spaceinteger

Number to indent the text.

parsefile(filename: str, **keywords) → None

Method to parse or restore the database from cache. Called by amespahdbpythonsuite.amespahdb.__init__() method.

Parameters:

filnamestr

String of the PAHdb filename and path.

keywords

Arbitrary keyword arguments.

search(query: str) → list | None

Search the database based on query input.

Parameters:

querystr

String containing search query.

Returns:

List of UIDs

Example:

search('magnesium=0 oxygen=0 iron=0 silicium=0 chx=0 ch2=0 c>20 h>0')

data class

class amespahdbpythonsuite.data.Data(d: dict | None = None, **keywords)

Bases: object

AmesPAHdbPythonSuite data class

difference(uids: list[int]) → None

Updates data to the difference with provided UIDs.

Parameters:

uidslist of integers

List of UIDs.

get() → dict

Return data dictionary with expected keywords.

getuids() → list

Return uid list.

intersect(uids: list[int]) → None

Updates data to the intersection with provided UIDs.

Parameters:

uids : list of integers

set(d: dict | None = None, **keywords) → None

Populate data dictionary.

xmlparser class

xmlparser.py

Parse a NASA Ames PAH IR Spectroscopic Database XML library file, with or without schema checking.

class amespahdbpythonsuite.xmlparser.XMLparser(filename: str | None = None, validate: bool = False)

Bases: object

Parse a NASA Ames PAH IR Spectroscopic library XML-file.

Optional behavior includes validating against a schema.

Attributes:

filename (str): XML filename. validate (bool): Whether to validate the XML schema or not. library (dict): Dictionary containing the parsed data.

Examples:

parser = XMLparser(filename=”xml_file.xml”) parser.verify_schema() dict = parser.to_pahdb_dict()

parser = XMLparser(filename=”xml_file.xml”, validate=True) dict = parser.to_pahdb_dict()

parser = XMLparser() parser.filename = “xml_file.xml” parser.validate = True dict = parser.to_pahdb_dict()

to_pahdb_dict(validate: bool = False) → dict

Parses the XML, with or without validation.

Args:

validate (bool). Defaults to self.valdiate value, but can be overridden.

Note:

Sets the attribute self.library when successful.

Returns: library (dict): Dictionary, with the UIDs as keys,

containing the transitions, geometry data, as well as UID metadata, references, comments, and laboratory.

verify_schema() → bool

Validate against linked schema.

Note:

Requires that self.filename is set.

It sets the internal attributes: _tree (etree.ElementTree): parsed XML file. _root: root element of ElementTree tree.

Returns:

True if successful, otherwise False.

transitions class

class amespahdbpythonsuite.transitions.Transitions(d: dict | None = None, **keywords)

Bases: Data

AmesPAHdbPythonSuite transitions class. Contains methods to create and apply an emission model.

static absorption_cross_section(f: ndarray) → ndarray

Calculates the PAH absorption cross-section per Li & Draine 2007, ApJ, 657:810-837.

Params f:

frequencies in wavenumber

Returns:

float array

static approximate_attained_temperature(T: float) → float

Calculate a PAH’s temperature after absorbing a given amount of energy using an approximation.

Parameters:

T (float) – Excitation temperature in Kelvin.

static approximate_feature_strength(T: float)

Calculate a feature’s strength convolved with a blackbody using an approximation from Bakes, Tielens & Bauschliher, ApJ, 556:501-514, 2001.

: Param T: Excitation temperature in Kelvin.

static attained_temperature(T: float) → float

Calculate a PAH’s temperature after absorbing a given amount of energy.

Parameters:

T (float) – Excitation temperature in Kelvin.

calculated_temperature(e: float | dict | None, **keywords) → None

Applies the Calculated Temperature emission model.

Parameters:

e (float) – Excitation energy in erg or temperature in Kelvin.

cascade(e: float, **keywords) → None

Applies the Cascade emission model.

Parameters:

e – Excitation energy in erg.

Type:

float

convolve(**keywords) → Spectrum

Convolve transitions with a line profile. Calls class: amespahdbpythonsuite.spectrum.Spectrum to retrieve the respective instance.

static feature_strength(T: float) → float

Calculate a feature’s strength covolved with a blackbody.

Parameters:

T (float) – Excitation temperature in Kelvin.

fixed_temperature(t: float) → None

Applies the Fixed Temperature emission model.

Parameters:

t (float) – Excitation temperature in Kelvin.

get() → dict

Calls class: amespahdbpythonsuite.data.Data.get to get keywords.

static heat_capacity(T: float) → float

Calculate heat capacity.

Parameters:

T (float) – Excitation temperature in Kelvin.

static isrf(f: ndarray) → ndarray | float

Callback function to calculate the absorption cross-section times the interstellar radiation field per Mathis et al. 1983, A&A, 128:212.

Params f:

frequencies in wavenumber

Returns:

float array

static isrf_approximate_feature_strength_convolved(f: ndarray) → ndarray

Calculate a feature’s strength convolved with the interstellar radiation field using an approximation.

Param f:

frequencies in wavenumber

Returns:

float

static isrf_feature_strength_convolved(f: ndarray) → ndarray

Calculate a feature’s strength convolved with the interstellar radiation field.

Param f:

frequencies in wavenumber

Returns:

float

static isrf_number_of_photons(f: ndarray) → ndarray | float

Callback function to calculate the number of photons per Mathis et al. 1983, A&A, 128:212.

Params f:

frequencies in wavenumber

Returns:

float array

static isrf_squared(f: ndarray) → ndarray | float

Callback function to calculate the absorption cross-section times the interstellar radiation field per Mathis et al. 1983, A&A, 128:212.

Params f:

frequencies in wavenumber

Returns:

float array

static mean_energy(**keywords)

Callback function to calculate the mean energy in erg for a given blackbody temperature.

Returns:

float array

static mean_energy_squared(**keywords)

Callback function to calculate the mean energy in erg^2 for a given blackbody temperatyre.

Returns:

float array

static number_of_photons(**keywords)

Calculate the number of photons given a blacbody radiation field.

static planck(f: ndarray) → ndarray

Callback function to Calculate the absorption cross-section multiplied by Planck’s function.

Params f:

frequencies in wavenumber

Returns:

float array

static planck_approximate_feature_strength_convolved(f: ndarray) → ndarray

Calculate a feature’s strength convolved with a given blackbody using an approximation.

Param f:

frequencies in wavenumber

Returns:

float

static planck_feature_strength_convolved(f: ndarray) → ndarray

Calculate a feature’s strength convolved with a given blackbody radiation field.

Param f:

frequencies in wavenumber

Returns:

float

static planck_number_of_photons(f: ndarray) → ndarray

Callback function to Calculate the number of photons using Planck’s function.

Params f:

frequencies in wavenumber

Returns:

float array

static planck_squared(f: ndarray) → ndarray

Callback function to Calculate the absorption cross-section multiplied by Planck’s function squared.

Params f:

frequencies in wavenumber

Returns:

float array

plot(**keywords) → None

Plot the transitions absorption spectrum.

set(d: dict | None = None, **keywords) → None

Calls class: amespahdbpythonsuite.data.Data.set to parse keywords. Checks flavor of the database, i.e., theoretical or experimental

shift(shift: float) → None

Shifts transitions frequency by provided value.

static stellar_model_approximate_feature_strength_convolved(f: ndarray) → ndarray

Calculate a feature’s strength convolved with the interstellar radiation field using an approximation.

Param f:

frequencies in wavenumber

Returns:

float

static stellar_model_feature_strength_convolved(f: ndarray) → ndarray

Calculate a feature’s strength convolved with a given stellar model.

Param f:

frequencies in wavenumber

Returns:

float

write(filename: str = '') → None

Write the transitions to file as an IPAC-table.

amespahdbpythonsuite.transitions.Tstar: float

amespahdbpythonsuite.transitions.charge: int

amespahdbpythonsuite.transitions.energy: float | dict | ndarray | None

amespahdbpythonsuite.transitions.frequencies: ndarray

amespahdbpythonsuite.transitions.frequency: float

amespahdbpythonsuite.transitions.intensities: ndarray

amespahdbpythonsuite.transitions.nc: int

amespahdbpythonsuite.transitions.star_model: Any

spectrum class

class amespahdbpythonsuite.spectrum.Spectrum(d: dict | None = None, **keywords)

Bases: Transitions

AmesPAHdbPythonSuite spectrum class. Contains methods to fit and plot the input spectrum.

coadd(weights: dict = {}, average: bool = False) → Coadded

Co-add PAHdb spectra.

Parameters:

weights: dict

Dictionary of fit weights to use when co-adding.

average: bool

If True calculates the average coadded spectrum.

fit(y: Observation | Spectrum1D | list, yerr: list = [], notice: bool = True, **keywords) → Fitted | None

Fits the input spectrum.

get() → dict

Calls class: amespahdbpythonsuite.transitions.Transitions.get. Assigns class variables from inherited dictionary.

getgrid() → list

Return the grid.

mcfit(y: Observation | Spectrum1D | list, yerr: list = [], samples: int = 1024, uniform: bool = False, multiprocessing: bool = False, notice: bool = True, **keywords) → MCFitted | None

Monte Carlo sampling and fitting to the input spectrum.

Parameters

samplesNumber of samples.

int

normalize(all: bool = False) → float | dict

Normalize spectral data

plot(**keywords) → None

Plot the spectrum.

resample(grid: ndarray) → None

Resample the spectral data.

set(d: dict | None = None, **keywords) → None

Calls class: amespahdbpythonsuite.transitions.Transitions.set to parse keywords.

write(filename: str = '') → None

Write the spectra to file as an IPAC-table.

coadd class

class amespahdbpythonsuite.coadded.Coadded(d: dict | None = None, **keywords)

Bases: Spectrum

AmesPAHdbPythonSuite coadded class

get() → dict

Calls class: amespahdbpythonsuite.spectrum.Spectrum.get. Assigns class variables from inherited dictionary.

plot(**keywords) → None

Plot the spectrum.

set(d: dict | None = None, **keywords) → None

Calls class: amespahdbpythonsuite.Spectrum.spectrum.set to parse keywords.

write(filename: str = '') → None

Write the coadded spectrum to file as an IPAC-table.

species class

class amespahdbpythonsuite.species.Species(d: dict | None = None, **keywords)

Bases: object

AmesPAHdbPythonSuite species class. Contains methods to work with PAH species.

comments() → dict

Return dict with comments.

Returns:

dict

difference(uids: list[int]) → None

Updates data to the difference with provided UIDs.

Parameters:

uidslist of integers

List of UIDs.

geometry() → Geometry

Return geometry instance. Calls the amespahdbpythonsuite.geometry.Geometry class.

Returns:

geometry instance

get() → dict

Return data dictionary with expected keywords.

getuids() → list[int]

Return uid list.

intersect(uids: list[int]) → None

Updates data to the intersection with provided UIDs.

Parameters:

uids : list of integers

laboratory() → Laboratory | None

Return laboratory instance. Calls the amespahdbpythonsuite.laboratory.Laboratory class.

Returns:

laboratory instance

references() → dict

Return dict with references.

Returns:

dict

set(d: dict | None = None, **keywords) → None

Populate properties.

transitions() → Transitions

Return transitions instance. Calls the amespahdbpythonsuite.transitions.Transitions class.

Returns:

transitions instance

amespahdbpythonsuite.species.formatformula(formula: str) → str

Make the formulae look pretty by embedding LaTeX formatting commands.

geometry class

class amespahdbpythonsuite.geometry.Geometry(d: dict | None = None, **keywords)

Bases: Data

AmesPAHdbPythonSuite geometry class

area() → dict

Computes the area.

bec() → dict

Convert PAH carbon and hydrogen positions to a boundary-edge code. Only makes sense to use this for regular PAHs. Return of a tuple with a list of boundary carbons traversed in order and the boundary-edge code. By Dr. Joseph E. Roser <Joseph.E.Roser@nasa.gov>

diagonalize(full: bool = False, equal: bool = False) → None

Diagonalize the moment of inertia and align structure with the x-y plane

get() → dict

Assigns class variables from inherited dictionary.

inertia() → dict

Compute the moment of inertia.

mass() → dict

Computes molecular mass.

plot(uid: int, **keywords) → None

Plot the structure

rings() → dict

Computes the number of rings per type.

set(d: dict | None = None, **keywords) → None

Calls class: amespahdbpythonsuite.data.Data.set to parse keywords.

structure(uid: int, **keywords) → vtkAssembly | None

Render the 3D structure.

laboratory class

class amespahdbpythonsuite.laboratory.Laboratory(d: dict | None = None, **keywords)

Bases: Data

AmesPAHdbPythonSuite laboratory class. Contains methods to work with a laboratory spectrum.

get() → dict

Assigns class variables from inherited dictionary.

plot(**keywords) → None

Plot the spectrum.

set(d: dict | None = None, **keywords) → None

Calls class: amespahdbpythonsuite.data.Data.set to parse keywords.

write(filename: str = '') → None

Write the laboratory spectra to file as an IPAC-table.

fitted class

class amespahdbpythonsuite.fitted.Fitted(d: dict | None = None, **keywords)

Bases: Spectrum

AmesPAHdbPythonSuite fitted class

get() → dict

Calls class: amespahdbpythonsuite.spectrum.Spectrum.get. Assigns class variables from inherited dictionary.

getbreakdown(**keywords) → dict | None

Retrieves the breakdown of the fitted PAHs.

getchisquared() → float | None

Calculates the chi-squared of the fit.

getclasses(**keywords) → dict | None

Retrieves the spectra of the different classes of the fitted PAHs.

geterror() → dict | None

Calculates the PAHdb fitting uncertainty as the ratio of the residual over the total spectrum area.

getfit() → ndarray | Literal[0]

Retrieves the sum of fit values.

getmethod() → str

Retrieves the method used for the fit.

getnorm() → float

Retrieves the Norm of the fit.

getobservation() → Spectrum1D

Retrieves the ordinate values of the observation.

getresidual() → ndarray

Retrieves the residual of the fit.

getsizedistribution(nbins: int = 0, min: float | None = None, max: float | None = None) → tuple

Retrieves the size distribution of the fitted PAHs.

getweights() → dict

Retrieves the weights of the fitted PAHs.

plot(**keywords) → None

Plotting method for the fitted spectrum and breakdown components.

set(d: dict | None = None, **keywords) → None

Calls class: amespahdbpythonsuite.spectrum.Spectrum.set to parse keywords.

sort(flux: bool = False) → dict

Sort UIDs and weights by their contribution to the fit

write(filename: str = '') → None

Write the fitted spectra to file as an IPAC-table.

mcfitted class

class amespahdbpythonsuite.mcfitted.MCFitted(d: dict | None = None, **keywords)

AmesPAHdbPythonSuite mcfitted class. Contains methods to fit and plot the input spectrum using a Monte Carlo approach.

get() → dict

Calls class: amespahdbpythonsuite.transitions.Transitions.get. Assigns class variables from inherited dictionary.

getbreakdown() → dict

Retrieves the breakdown of the MC fitted PAHs.

getclasses() → dict

Retrieves the spectra of the different classes of the MC fitted PAHs.

geterror() → dict

Obtains the PAHdb fitting uncertainty from the fitted geterror method, as the ratio of the residual over the total spectrum area.

getfit() → dict

Retrieves the mean, std, skewness, and kurtosis spectra.

getobservation() → Spectrum1D

Retrieves the observation.

getresidual() → dict

Retrieves the statistics spectra for the residuals of the MC fits.

plot(**keywords)

Plot the MC sampled fit and breakdown components.

write(filename: str = '') → None

Write the spectra to file as an IPAC-table.

observation class

class amespahdbpythonsuite.observation.Observation(d: None = None, **keywords)

Bases: object

AmesPAHdbPythonSuite observation class. Contains methods to work with astronomical spectra.

abscissaunitsto(unit: Unit) → None

Convert abscissa units.

get() → dict

Assigns class variables to dictionary.

getgrid() → ndarray

Retreive the spectral axis.

plot(**keywords) → None

Plot the spectrum.

read(filename: Path | str) → None

Read a spectrum.

Parameters:

filename: str

Name of file to read.

rebin(x: ndarray | float, uniform=False, resolution=False) → None

Resample the spectral data.

set(d, **keywords) → None

Populate properties.

setgridrange(min: float, max: float | None = None) → None

Truncate the data to the given range.

write(filename: str = '') → None

Write the spectrum to file as an IPAC-table.

Module contents

The AmesPAHdbPythonSuite is developed by the NASA Ames PAH IR Spectroscopic Database team, asscociated with the Astrophysics & Astrochemistry Laboratory at NASA Ames Research Center. The NASA Ames PAH IR Spectroscopic Database and pypahdb are being supported through a directed Work Package at NASA Ames titled: “Laboratory Astrophysics - The NASA Ames PAH IR Spectroscopic Database”.

Additional information can be found at the NASA Ames PAH IR Spectroscopic Database website, which is located at https://www.astrochemistry.org/pahdb You are kindly asked to consider the following references for citation when using the AmesPAHdbPythonSuite:

• C.W. Bauschlicher, Jr., A. Ricca, C. Boersma, and L.J. Allamandola, “THE NASA AMES PAH IR SPECTROSCOPIC DATABASE: COMPUTATIONAL VERSION 3.00 WITH UPDATED CONTENT AND THE INTRODUCTION OF MULTIPLE SCALING FACTORS”, The Astrophysical Journal Supplement Series, 234, 32, 2018 https://doi.org/10.3847/1538-4365/aaa019

• C. Boersma, C.W. Bauschlicher, Jr., A. Ricca, A.L. Mattioda, J. Cami, E. Peeters, F. Sanchez de Armas, G. Puerta Saborido, D.M. Hudgins, and L.J. Allamandola, “THE NASA AMES PAH IR SPECTROSCOPIC DATABASE VERSION 2.00: UPDATED CONTENT, WEBSITE AND ON/OFFLINE TOOLS”, The Astrophysical Journal Supplement Series, 211, 8, 2014 https://doi.org/10.1088/0067-0049/211/1/8

• Mattioda, A. L., Hudgins, D. M., Boersma, C., Ricca, A., Peeters, E., Cami, J., Sanchez de Armas, F., Puerta Saborido, G., Bauschlicher, C. W., J., and Allamandola, L. J. “THE NASA AMES PAH IR SPECTROSCOPIC DATABASE: THE LABORATORY SPECTRA”, The Astrophysical Journal Supplement Series, 251, 22, 2020, https://doi.org/10.3847/1538-4365/abc2c8