lvlspy package

A package of python routines to handle quantum-level system data.

lvlspy.level module

Module to handle levels in species.

class lvlspy.level.Level(energy, multiplicity, units='keV')

Bases: Properties

A class for storing and retrieving data about a level.

Args:

energy (float): The energy of the level. It is in units given by the keyword units.

multiplicity (int): The multiplicity of the level.

units (str, optional): A string giving the units for the energy. Possible values are ‘eV’, ‘keV’ (the default), ‘MeV’, or ‘GeV’.

compute_boltzmann_factor(temperature)

Method to compute the Boltzmann factor for a level.

Args:

temperature (float): The temperature in K at which to compute the factor.

Returns:

float: The computed Boltzmann factor multiplicity * exp(-Energy/kT).

get_energy(units='keV')

Method to retrieve the energy for a level.

Args:

units (str, optional): A string giving the units for the energy.

Returns:

float: The energy in units given by the units keyword. The default is ‘keV’.

get_multiplicity()

Method to retrieve the multiplicity for a level.

Returns:

int: The multiplicity.

update_energy(energy, units='keV')

Method to update the energy for a level.

Args:

energy (float): The new energy for the level.

units (str, optional): A string giving the units for the energy.

Returns:

On successful return, the energy has been updated.

update_multiplicity(multiplicity)

Method to update the multiplicity for a level.

Args:

multiplicity (int): The new multiplicity for the level.

Returns:

On successful return, the multiplicity has been updated.

lvlspy.properties module

Base class for handling properties for all classes.

class lvlspy.properties.Properties

Bases: object

A class for storing and retrieving optional properties.

get_properties()

Method to retrieve the optional properties.

Returns:

dict: The dictionary of current properties.

update_properties(properties)

Method to update the optional properties.

Args:

properties (dict): A dictionary of properties. New properties are added. Old properties are updated.

Returns:

On successful return, the properties have been updated.

lvlspy.transition module

Module for handling transitions.

class lvlspy.transition.Transition(upper_level, lower_level, einstein_a)

Bases: Properties

A class for storing and retrieving data about a transition.

Args:

upper_level (lvlspy.level.Level) The level from which there is a spontaneous decay.

lower_level (lvlspy.level.Level) The level to which there is a spontaneous decay.

einstein_A (float): The Einstein A coefficient (the spontaneous decay rate per second from upper_level to lower_level).

compute_lower_to_upper_rate(temperature, user_func=None)

Method to compute the total rate for transition from the lower level to upper level.

Args:

temperature (float) The temperature in K at which to compute the rate.

user_func (optional): A function that computes the lower level to upper level transition rate. If supplied, the routine will use this function in place of the default one, which computes the rate from the appropriate Einstein coefficient and the blackbody spectrum. The function must take one float argument giving the temperature. Other data can be bound to the function.

Returns:

float: The rate (per second).

compute_upper_to_lower_rate(temperature, user_func=None)

Method to compute the total rate for transition from the upper level to to lower level.

Args:

temperature (float) The temperature in K at which to compute the rate.

user_func (optional): A function that computes the upper level to lower level transition rate. If supplied, the routine will use this function in place of the default one, which computes the rate from the appropriate Einstein coefficients and the blackbody spectrum. The function must take one float argument giving the temperature. Other data can be bound to the function.

Returns:

float: The rate (per second).

get_einstein_a()

Method to retrieve the Einstein A coefficient for the transition.

Returns:

float: The spontaneous rate (per second) for the transition.

get_einstein_b_lower_to_upper()

Method to get the Einstein B coefficient for the lower level to upper level transition (induced absorption).

Returns:

float: The Einstein coefficient in cm ² steradian per erg per s.

get_einstein_b_upper_to_lower()

Method to get the Einstein B coefficient for the upper level to lower level transition (induced emission).

Returns:

float: The Einstein coefficient in cm ² steradian per erg per s.

get_frequency()

Method to compute the frequency of the transition.

Returns:

float: The frequency (in Hz) of the transition.

get_lower_level()

Method to retrieve the lower_level for the transition.

Returns:

lvlspy.level.Level: The lower_level for the transition.

get_upper_level()

Method to retrieve the upper_level for the transition.

Returns:

lvlspy.level.Level: The upper_level for the transition.

update_einstein_a(einstein_a)

Method that updates the Einstein A coefficient of a transition.

Args:

transition (lvlspy.transition.Transition) The transition to be modified.

einstein_A (float) The new value for the Einstein A coefficient.

Returns:

On successful return, the transition Einstein A coefficient has been updated.

lvlspy.species module

Module to handle species.

class lvlspy.species.Species(name, levels=None, transitions=None)

Bases: Properties

A class for storing and retrieving data about a species.

Args:

name (str): The name of the species.

levels (list, optional): A list of individual lvlspy.level.Level objects.

transitions (list, optional): A list of individual lvlspy.transition.Transition objects.

units (str, optional): A string giving the units for the energy.

add_level(level)

Method to add a level to a species.

Args:

level (lvlspy.level.Level) The level to be added.

Return:

On successful return, the level has been added. If the level previously existed in the species, it has been replaced with the new level.

add_transition(transition)

Method to add a transition to a species.

Args:

transition (lvlspy.transition.Transition) The transition to be added.

Return:

On successful return, the transition has been added. If the transition previously existed in the species, it has been replaced with the new transition.

compute_equilibrium_probabilities(temperature)

Method to compute the equilibrium probabilities for levels in a species.

Args:

temperature (float): The temperature in K at which to compute the equilibrium probabilities.

Returns:

numpy.array: A numpy array of the probabilities of the levels. The levels are sorted in ascending energy.

compute_rate_matrix(temperature)

Method to compute the rate matrix for a species.

Args:

temperature (float): The temperature in K at which to compute the rate matrix.

Returns:

numpy.array: A 2d numpy array giving the rate matrix.

get_level_to_level_transition(upper_level, lower_level)

Method to retrieve the downward transition from a particular upper level to a particular lower level.

Args:

upper_level (lvlspy.level.Level) The level from which the transition originates.

lowerlevel (lvlspy.level.Level) The level to which the transition goes.

Return:

lvlspy.transition.Transition: The transition, or None if the transition is not found.

get_levels()

Method to retrieve the levels for a species.

Returns:

list: A list of the levels. The levels are sorted in ascending energy.

get_lower_linked_levels(level)

Method to retrieve the lower-energy levels linked to the input level by transitions in the species.

Args:

level (lvlspy.level.Level) The level for which the linked levels are sought.

Return:

list: A list of the lower-energy levels linked to the input level by transitions.

get_name()

Retrieve the name of the species.

Return:

The str giving the species name.

get_transitions()

Method to retrieve the transitions for a species.

Returns:

list: A list of the transitions.

get_upper_linked_levels(level)

Method to retrieve the higher-energy levels linked to the input level by transitions in the species.

Args:

level (lvlspy.level.Level) The level for which the linked levels are sought.

Return:

list: A list of the higher-energy levels linked to the input level by transitions.

remove_level(level)

Method to remove a level from a species.

Args:

level (lvlspy.level.Level) The level to be removed.

Return:

On successful return, the level and all connected transitions have been removed.

remove_transition(transition)

Method to remove a transition from a species.

Args:

transition (lvlspy.transition.Transition) The transition to be removed.

Return:

On successful return, the transition has been removed.

lvlspy.spcoll module

Module to handle a collection of species.

class lvlspy.spcoll.SpColl(species=None)

Bases: Properties

A class for storing and retrieving data about a species collection.

Args:

species (list, optional): A list of individual lvlspy.species.Species objects.

add_species(species)

Method to add a species to a collection.

Args:

species (lvlspy.species.Species) The species to be added.

Return:

On successful return, the species has been added. If the species previously existed in the collection, it has been replaced with the new species.

get()

Method to retrieve the species collection as a dictionary.

Returns:

dict: A dictionary of the species.

remove_species(species)

Method to remove a species from a species collection.

Args:

species (lvlspy.species.Species) The species to be removed.

Return:

On successful return, the species has been removed.

update_from_xml(file, xpath='')

Method to update a species collection from an XML file.

Args:

file (str) The name of the XML file from which to update.

xpath (str, optional): XPath expression to select species. Defaults to all species.

Returns:

On successful return, the species collection has been updated.

validate(file)

Method to validate a species collection XML file.

Args:

file (str) The name of the XML file to validate.

Returns:

An error message if invalid and nothing if valid.

write_to_xml(file, pretty_print=True, units='keV')

Method to write the collection to XML.

Args:

file (str) The output file name.

pretty_print (bool, optional): If set to True, routine outputs the xml in nice indented format.

units (str, optional): A string for the energy units.

Return:

On successful return, the species collection data have been written to the XML output file.