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.

evaluate_expression(expression)

Method to extract range of jpi depending on ENSDF definition

get_properties()

Method to retrieve the optional properties.

Returns:

dict: The dictionary of current properties.

set_parity(p)

Method to transform partity from +/- string to +/- 1 integer

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.

fill_missing_transitions(a)

Method to fill in transitions between levels using a Weisskopf estimate. Parity must be set as a property, otherwise method would return wrong estimates

Args:

a (int) Mass number of the species

Returns:

Upon successful return, the species will have an updated list of transitions based on Weisskopf estimate

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.

update_name(name)

Change the name of the species.

Args:

name (string) The new name of the species

Return:

On successful return, the species’ name has been updated

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.

lvlspy.io module

A submodule of lvlspy to handle input and output

lvlspy.io.xml

Module to handle XML input and output

lvlspy.io.xml._xml.update_from_xml(coll, file, xpath='')

Method to update a species collection from an XML file.

Args:

coll (obj) The collection to be read from the XML file

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.

lvlspy.io.xml._xml.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.

lvlspy.io.xml._xml.write_to_xml(coll, file, pretty_print=True, units='keV')

Method to write the collection to XML.

Args:

coll (:obj: obj’) The collection to be written to the XML file ``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.

lvlspy.io.ensdf

Module to handle ENSDF input and output

lvlspy.io.ensdf._ensdf.fill_missing_ensdf_transitions(sp, a)

Method to fill in missing transitions from either not listed in ENSDF or level with useable property flagged as false due to unclear J^pi

Args:

sp (lvlspy.species.Species) The species read in from ENSDF to fill in missing transitions

a (int) Mass number of species

Returns:

Upon successful return, the species would be updated with all transitions

lvlspy.io.ensdf._ensdf.remove_undefined_levels(sp, all_levs=False)

Method that removes levels read from ensdf where j^pi is left blank or unclear. This feature Wfacilitates calculations made in the isomer module

Args:

sp (lvlspy.species.Species) The species of which the levels are to be trimmed

all (bool) A flag to remove all undefined levels which have j^pi set blank or a range of values. Defaults to False so only the blanks are removed

Returns:

Upon successful return, the levels with blank j^pi from the ENSDF record will be removed

lvlspy.io.ensdf._ensdf.update_from_ensdf(coll, file, sp)

Method to update a species collection from an ENSDF file.

Args:

coll (obj) The collection to be read from the ENSDF file

file (str) The file name to update from.

sp (str): The species to be read from file.

Returns:

On successful return, the species collection has been updated.

lvlspy.io.ensdf._ensdf.update_reduced_matrix_coefficient(sp, a, t, rmc, mr=0)

Method to update a transition’s reduced matrix coefficient and Einstein A coefficient

Args:

sp (lvlspy.species) The species where the transition is found

a (int) The species mass number

t (lvlspy.transition) The transition to be updated

rmc (list) A list of tuples containing the new updated reduced matrix coefficients.

A sample would be [(‘BM1W’,0.05)]

mr (float,optional) An updated mixing ratio

Returns:

On successful return, the transition’s Einstein A coefficient will be updated based on the new coefficients.

lvlspy.io.ensdf._ensdf.write_to_ensdf(coll, file)

Method that writes a collection of species to ENSDF format

Args:

coll (lvlspy.spcoll.SpColl) The collection to be written to file. Each species in the collection must have the species’ name, level and gamma properties must be within ENSDF spec

Returns:

On successful return, the species collection has been written

lvlspy.calculate module

A subdirectoy of lvlspy to handle calculations

lvlspy.calculate.evolve

Module to handle the evolution of the level system based on temperature

lvlspy.calculate.evolve._evolve.csc(sp, temp, y0, time)

Evolves a system using sparse solver

Args:

sp (lvlspy.species.Species): The species containing the levels to be evolved

temp (float): The temperature in K to evolve the system at.

y0 (numpy.array): Array containing the initial condition.

time (numpy.array): An array containing the time stamps to evolve the system

Returns:

sol_expm_solver (numpy.array): A 2D array containing the evolved system

fug (numpy.array) 2D array containing the fugacities as a function of time

lvlspy.calculate.evolve._evolve.newton_raphson(sp, temp, y0, time, tol=1e-06)

Evolves a system using the Newton-Raphson method

Args:

sp (lvlspy.species.Species): The species containing the levels to be evolved

temp (float): The temperature in K to evolve the system at.

y0 (numpy.array): 1D array containing the initial distribution.

time (numpy.array,optional): An array containing the time steps. tol (float): The convergence condition for the method. Defaults to 1e-6.

Returns:

y (numpy.array): 2D array of size n_levels*n_time containing the evolved system.

fug (numpy.array) 2D array containing the fugacities as a function of time

lvlspy.calculate.weisskopf

Module to handle weisskopf calculations

class lvlspy.calculate.weisskopf._weisskopf.Weisskopf

Bases: object

A class for handling Weisskopf related calculations

estimate(e, j, p, a)

Calculates the Weisskopf estimate for a transition between two states.

Args:

e (list) An array containing the energies of the two levels

j (list) An array containing the angular momenta of the two levels

p (list) An array containing the parity of both levels

a (int) The mass number of the species

Returns:

ein_a (float) The Einstein A coefficient of the downwards transition

estimate_from_ensdf(t, a)

Calculates the Weisskopf estimate for a transition between two states based on the properties available from the ENSDF file.

Args:

lvs (lvlspy.level.Level) The levels of the species

tran (list) An array containing all the data from ENSDF regarding a single transition

Returns:

ein_a (float) The total estimate for the transition rate (in per second) using Weisskopf single particle estimate

rate_elec(e_i, e_f, j, a)

Calculates the transition rate between two levels where the transition is an electric multipole.

Args:

e_i (float) Energy of the initial state (in keV)

e_f (float) Energy of the final state (in keV)

j (int) Angular momentum of the gamma ray

a (int) Mass number

Returns:

The electric contribution to the Weisskopf estimate between the two states

rate_mag(e_i, e_f, j, a)

Calculates the transition rate between two levels where the transition is a magnetic multipole

Args:

e_i (float) Energy of the initial state (in keV)

e_f (float) Energy of the final state (in keV)

j (int) Angular momentum of the gamma ray

a (int) Mass number

Returns:

The magnetic contribution to the Weisskopf estimate between the two states

lvlspy.calculate.isomer

Module to handle isomer related calculations. Functions are built based on the method in Gupta and Meyer (2001)

lvlspy.calculate.isomer._isomer.cascade_probabilities(t, sp, level_low=0, level_high=1)

Method to calculate the cascace probability vectores (gammas)

Args:

t (float) The temperature in K

sp (lvlspy.species.Species) The species of which the probability vectors are to be calculated for

level_low (int, optional) The lower level the effective transition rates are calculated to. Defaults to 0; the ground state.

level_high (int, optional) The higher level the effective transtion rates are calculated to. Defaults to 1; the first excited state

Returns:

Upon successful return, the cascade probability vectors will be returned as an array

g1_out (numpy.array) cascade vector out of lower level g2_out (numpy.array) cascade vector out of higher level g1_in (numpy.array) cascade vector into lower level g2_in (numpy.array) cascade vector into higher level

lvlspy.calculate.isomer._isomer.effective_rate(t, sp, level_low=0, level_high=1)

Method to calculate the effective transition rates between the isomeric and ground states

Args:

t (float) The temperature in K.

sp (lvlspy.species.Species) The species of which the level system belongs to.

level_low (int, optional) The lower level the effective transition rates are calculated to. Defaults to 0; the ground state.

level_high (int, optional) The higher level the effective transtion rates are calculated to. Defaults to 1; the first excited state

Returns:

Upon successful return, the method returns the effective transition rates between the higher and lower level at temperature T

l_low_high (float) The effective transition rate from the lower level to the higher level

l_high_low (float) The effective transition rate from the higher level to the lower level

lvlspy.calculate.isomer._isomer.ensemble_weights(t, sp, level_low=0, level_high=1)

Method to calculate the ensemble weights

Args:

t (float) The temperature in K

sp (lvlspy.species.Species) The species of which the ensemble weights are to be calculated for

level_low (int, optional) The lower level the effective transition rates are calculated to. Defaults to 0; the ground state.

level_high (int, optional) The higher level the effective transtion rates are calculated to. Defaults to 1; the first excited state

Returns:

Upon successful return, the ensemble weights and their properties will be returned as an array

w_low (numpy.array) weight factor relative to the low level w_high (numpy.array) weight factor relative to the high level W_low (numpy.float) Enhancement of ensemble abundance over low level W_high (numpy.float) Enhancement of ensemble abundance over high level R_lowk (numpy.array) The reverse ratio relative to the low level R_highk (numpy.array) The reverse ratio relative to the high level G_low (numpy.float) Partition function associated with the low level G_high (numpy.float) Patition function associated with the high level

lvlspy.calculate.isomer._isomer.transfer_properties(rate_matrix, level_low, level_high)

Method that calculatest the transfer properties based on the rate matrix

Args:

rate_matrix (numpy.array) A 2D array containing the rate matrix of a species at a given temperature

level_low (int) Integer indicating the lower level the transition is moving to

level_high (int) Integer indicating the higher level the transition is moving from

Returns:

On successful return, an array containing the following variable is passed:

tpm (numpy.array) A 2D array containing the Transition Probability Matrix

f_low_in (numpy.array) An array containing the branching ratio from all the upper levels into the low level

f_low_out (numpy.array) An array containing the branching ratio from the lower levels into all the other levels

f_high_in (numpy.array) An array containing the branching ratio from all the levels into the high level

f_high_out (numpy.array) An containing the branching ration out of the high level into all the other levels

lambda_sum (numpy.array) An array containing the diagonal elements of the rate matrix