MoleCool.spectra

MoleCool.spectra#

Module for calculating the eigenenergies and eigenstates of diatomic molecules exposed to external fields. Therefore molecular constants which are measured and fitted in spectroscopic experiments must be provided to build up the effective Hamiltonian terms. Finally, the transition probabilities between two given electronic state manifolds can be determined to simulate a complete spetrum.

Example

Example for calculating and plotting a spectrum of 138BaF:

from MoleCool.spectra import ElectronicStateConstants, Molecule, plt

# defining spectroscopic constants
const_gr = ElectronicStateConstants(const={
    'B_e' : 0.2159,   'D_e' : 1.85e-7,  'gamma' : 0.0027,
    'b_F' : 0.0022,   'c'   : 0.00027,
})
const_ex = ElectronicStateConstants(const={
    'B_e' : 0.2117,   'D_e' : 2.0e-7,   'A_e' : 632.2818,
    'p'   : -0.089545,'q'  : -0.0840,
    "g'_l": -0.536,   "g'_L":0.980,
    'T_e' : 11946.31676963,
})

# initiating empty Molecule instance and adding electronic states
# with all quantum states up to a certain quantum number F
BaF = Molecule(I1 = 0.5, mass = 157, temp = 4)
BaF.add_electronicstate('X', 2, 'Sigma', const=const_gr)
BaF.add_electronicstate('A', 2, 'Pi', Gamma=2.84, const=const_ex)
BaF.build_states(Fmax=8)

# calculating branching ratios and molecular spectrum
BaF.calc_branratios()
E, I = BaF.calc_spectrum(limits=(11627.0, 11632.8))

# plotting
plt.figure()
plt.plot(E, I)
plt.xlabel('Frequency (cm$^{-1}$)')
plt.ylabel('Intensity (arb. u.)')

Tip

The instances of all classes Molecule, ElectronicState, Hcasea and ElectronicStateConstants can be printed:

print(BaF)
print(BaF.X)
print(BaF.X.states[0])
print(const_gr_138) # is the same as: print(BaF.X.const)

Module Attributes

cm2MHz

Constant for converting a unit in wavenumbers (cm^-1) into MHz.

Functions

`H_Zeeman`(x, y, const, Bfield)	calculates and returns the matrix element of the Zeeman interaction between two states.
`H_d`(x, y)	calculates and returns the matrix element of the electric dipole operator between two states.
`H_tot`(x, y, const)	calculates and returns the matrix element of the total Hamiltonian without external fields between two states.
`addJ`(J1, J2)	adding two angular momenta.
`cb`(x)	curly brackets expression in the Hamiltonian
`eigensort`(x, y_arr)	sorts an eigenvalue matrix, e.g. eigenvalues as a function of a varying magnetic or eletric field.
`get_QuNr_keyval_pairs`(ElState, multiindex[, ...])	Calculated list of pairs of the name and value of certain Quantum numbers included in a MultiIndex object.
`get_QuNrvals_from_multiindex`(multiindex, QuNrs)	Extract lists with the values certain Quantum numbers from a pandas.MultiIndex object.
`get_unique_multiindex_names`(multiindex)	Calculate list of unique column names from a pandas.MultiIndex object.
`ishalfint`(x[, raise_err])	test if x is a half-integer value and raise an error if it's intended
`isint`(x[, raise_err])	test if x is an integer value and raise an error if it's intended
`kd`(x, y)	delta kronecker
`multiindex_filter`(DF[, rows, cols, drop_level])	Filter a DataFrame object only for few specific multiindex values.
`phs`(x)	phase expression '(-1)^(x) in the Hamiltonian
`sb`(x)	square brackets expression in the Hamiltonian
`w3j`(j_1, j_2, j_3, m_1, m_2, m_3)	returns Wigner 3j-symbol with arguments (j_1, j_2, j_3, m_1, m_2, m_3)
`w6j`(j_1, j_2, j_3, j_4, j_5, j_6)	returns Wigner 6j-symbol with arguments (j_1, j_2, j_3, j_4, j_5, j_6)

Classes

`ElectronicState`(label, Smultipl, L[, Hcase, ...])	This class represents an electronic ground or excited state manifold which are part of the molecular level structure.
`ElectronicStateConstants`([const, unit, nu])	An instance of this class represents an object which includes all molecular constants for evaluating the effective Hamiltonian yielding the molecular eigenstates and respective eigenenergies.
`Hcasea`(**kwargs)	Instance of the class represents a molecular state as Hund's case a.
`Hcasea_p`(**kwargs)	Instance of the class represents a molecular state as Hund's case a.
`Hcaseb`(**kwargs)	Instance of the class represents a molecular state as Hund's case a.
`Hcaseb_betaS`(**kwargs)	Instance of the class represents a molecular state as Hund's case a.
`Molecule`([I1, I2, Bfield, mass, ...])	This class represents a molecule containing all electronic and hyperfine states in order to calculate branching ratios and thus to plot the spectrum.
`NestedDict`	Nested dictionary class to handle multiple key with the corresponding `__getitem__` and `__setitem__` methods.
`QuState`(**kwargs)	Instance of the class represents a molecular state as Hund's case a.

MoleCool.spectra.cm2MHz = 29979.245799999997#: Constant for converting a unit in wavenumbers (cm^-1) into MHz.

MoleCool.spectra.w3j(j_1, j_2, j_3, m_1, m_2, m_3)[source]#: returns Wigner 3j-symbol with arguments (j_1, j_2, j_3, m_1, m_2, m_3)

MoleCool.spectra.w6j(j_1, j_2, j_3, j_4, j_5, j_6)[source]#: returns Wigner 6j-symbol with arguments (j_1, j_2, j_3, j_4, j_5, j_6)

class MoleCool.spectra.Molecule(I1=0, I2=0, Bfield=0.0, mass=0, load_constants=None, temp=5.0, naturalabund=1.0, label='BaF', verbose=True, mF_states=False)[source]#

Bases: object

This class represents a molecule containing all electronic and hyperfine states in order to calculate branching ratios and thus to plot the spectrum.

Parameters:

I1 (float, optional) – nuclear spin of one atom of the molecule. The default is 0.
I2 (float, optional) – If the first nuclear spin I1 is non-zero, a second smaller nuclear spin can be provided via I2. The default is 0.
Bfield (float, optional) – strength of a external magnetic field in T. The default is 0.0.
mass (float, optional) – mass of the molecule in atomic mass units. The default is None.
load_constants (string, optional) – if provided the molecular constants are loaded from an external file. The default is None.
temp (float, optional) – temperatur of the molecule in K. The default is 5.0.
naturalabund (float, optional) – natural abundance in the range from 0.0 to 1.0 of different isotopes of a molecule in order to weight the spectra for different isotopes. The default is 1.0.
label (string, optional) – label or name of the molecule. The default is ‘BaF’.
verbose (bool, optional) – specifies if additional information and warning should be printed during the calculations. The default is True.

add_electronicstate(*args, **kwargs)[source]#

adds an electronic state (ground or excited state) as instance of the class ElectronicState to this Molecule.

Parameters:

args – arguments and keyword arguments for the eletronic state (see ElectronicState for the required arguments)
kwargs – arguments and keyword arguments for the eletronic state (see ElectronicState for the required arguments)

build_states(Fmax, Fmin=None)[source]#

Builds the individual Quantum states within all electronic states defined within the Molecule’s instance in the range from Fmin to Fmax in units of the total angular momentum quantum number. See ElectronicState.build_states() for details.

Parameters:

Fmax (float) – maximum angular momentum quantum number.
Fmin (float, optional) – minimum angular momentum quantum number. The default is None.

calc_branratios(threshold=0.0, include_Boltzmann=True, grstate=None, exstate=None)[source]#

calculates the linestrengths (by evaluating the electric dipole matrix) and energies of all transitions between a ground and excited electronic state in order to obtain the branching ratios weighted by a Boltzmann factor.

Note

This method creates the attributes (as numpy.ndarrays):

dipmat : electric dipole matrix of the eigenstates in the same order as the eigenstates are stored in the respective electronic states ElectronicState which can be printed via the method get_eigenstates().
E : transition energies between the eigenstates in the same order
branratios : respective branching ratios

Parameters:

threshold (float, optional) – all branching ratios below the threshold in the range from 0.0 to 1.0 are set to zero. The default is 0.0.
include_Boltzmann (bool, optional) – determines if the Boltzmann factor is included weighting ground state levels with different energy dependent on the temperature. The default is True.
grstate (string, optional) – label of the electronic excited state which should be used for the calculation of the branching ratios. By default the last added ground state is used. The default is None.
exstate (string, optional) – label of the electronic excited state which should be used for the calculation of the branching ratios. By default the last added excited state is used. The default is None.

calc_spectrum(limits=[], sigma=None, plotpoints=40000)[source]#

calculates the spectrum in a certain frequency range using the branching ratios previously calculated in the method calc_branratios(). The resulting frequency and intensity arrays are not only returned but also stored as variables Eplt and I in the Molecule instance. The widths of the single transitions are determined by the natural linewidth Gamma of the respective ElectronicState instance (Lorentzian profile) and the temperature (Gaussian profile). The convolution of both profiles is then given by the Voigt profile.

Parameters:

limits (list, optional) – defines the frequency limits for the plotting the spectrum as list or tuple of size 2 in units of wavenumbers 1/cm. By default the complete range containing all transitions is chosen. The default is None.
sigma (float, optional) – if desired, one can manually define the width of the Doppler-broadening, which would actually arise due to a non-zero temperature (by default), to a specific value (in cm^-1). The default is None.
plotpoints (int, optional) – integer number specifying the number of intervals for the plotting frequency range, i.e. the plot resolution. The default is 40000.

Returns:

numpy.ndarray – frequency array of the spectrum to be plotted.
numpy.ndarray – intensity array of the spectrum belonging to the frequency array.

which_eigenstates(Emin, Emax)[source]#

searches all eigenstates which are part of the transitions within the specified frequency range. These eigenstates are printed with their branching ratios and transitionenergies.

Parameters:

Emin (float) – lower limit of the frequency range.
Emax (float) – upper limit of the frequency range.

get_dMat_red(recalc_branratios=True, Hcasebasis=True, onlygoodQuNrs=True, index_filter=None, **kwargs)[source]#

Outputs the reduced electric dipole matrix in a nice readable format.

Parameters:

recalc_branratios (bool, optional) – Whether the branching ratios should be calculated again. The default is True.
Hcasebasis (bool, optional) – See ElectronicState.get_eigenstates(). The default is True.
onlygoodQuNrs (bool, optional) – See ElectronicState.get_eigenstates(). The default is True.
index_filter (tuple of dict) – Tuple or list including two dictionaries, i.e. see two arguments of multiindex_filter(). Default is no filtering.
**kwargs (kwargs) – Additional keyword arguments (see calc_branratios()). By default these keyword arguments are dict(threshold=0.0, include_Boltzmann=False).

Returns:

reduced electric dipole matrix.

Return type:

pandas.DataFrame

get_E(index_filter=None, **kwargs)[source]#

Similar method as get_dMat_red() but with the eigenenergies.

Parameters:

index_filter (tuple of dict) – Tuple or list including two dictionaries, i.e. see two arguments of multiindex_filter(). Default is no filtering.
**kwargs (kwargs) – keyword arguments from get_dMat_red().

Returns:

eigen energies.

Return type:

pandas.DataFrame

get_branratios(normalize=True, include_Boltzmann=False, threshold=0.0, index_filter=None, **kwargs)[source]#

Similar method as get_dMat_red() but with the branching ratios.

Parameters:

normalize (bool, optional) – Whether the columns of the branching ratios should be normalized to 1. The default is True.
include_Boltzmann (bool, optional) – See get_dMat_red(). The default is False.
threshold (float, optional) – See get_dMat_red(). The default is 0.0.
index_filter (tuple of dict) – Tuple or list including two dictionaries, i.e. see two arguments of multiindex_filter(). Default is no filtering.
**kwargs (kwargs) – Additional keyword arguments (see get_dMat_red()).

Returns:

branching ratios.

Return type:

pandas.DataFrame

export_OBE_properties(gs=None, exs=None, index_filter=({}, {}), fname='', HFfreq_offsets=[0, 0], Bmaxs=[0.0001, 0.0001], QuNrs_const=([], []), QuNrs_var=([], []), include_mF=False, vibr_values={}, rounded=None)[source]#

Export all the important properties connected to two electronic states to a dictionary in a proper format for the OBE simulation code to import the properties. This dictionary can also directly be saved as a .json file. This method uses the similar function ElectronicState.export_OBE_properties().

Parameters:

gs (str, optional) – label of the ground ElectronicState. The default is None meaning that it is automatically chosen.
exs (str, optional) – label of the excited ElectronicState. The default is None meaning that it is automatically chosen.
index_filter (tuple(dict), optional) – to filter the states of interest. The tuple with two dictionaries is used for ground and excited state see multiindex_filter(). The default is ({},{}).
fname (str, optional) – filename of the constants file. Should end with ‘.json’. The default is ‘’ meaning that no file will be saved.
HFfreq_offsets (list(float), optional) – offsets for the hyperfine frequencies of the two electronic states. See HFfreq_offset in ElectronicState.export_OBE_properties(). The default is [0,0].
Bmaxs (list(float), optional) – Determines how the gfactors of the two ElectronicStates are calculated (see ElectronicState.get_gfactors()). The default is [1e-4,1e-4].
QuNrs_const (tuple(list), optional) – constant Quantum numbers (see get_QuNr_keyval_pairs()). The default is ([],[]).
QuNrs_var (TYPE, optional) – Variable Quantum numbers (see ElectronicState.export_OBE_properties()). The default is ([],[]).
include_mF (bool, optional) – Whether to include mF Quantum numbers on top of the ones from QuNrs_var. The default is False.
vibr_values (dict, optional) – Dictionary to include the vibrational properties manually. Includes keys ‘vibrbranch’, ‘vibrfreq’, ‘QuNrs_rows’, ‘QuNrs_cols’ where the last two keys are optional as they will be generated automatically. The default is {}.
rounded (int, optional) – digit to round the frequencies and gfactors. The default is None meaning that no rounding is applied.

Returns:

Dictionary with the properly formatted level and transition properties.

Return type:

dict

plot_fortrat(QuNrs, ax=None, limits=None, branratio_TH=0.01, limits_unit='THz', markers=['+', 'x', '.', '1', '2', '3', '4'], legend=True, xaxis_func=<function Molecule.<lambda>>)[source]#

Plotting Quantum number values over transition frequencies. It makes sense to combine this plot with the actual spectrum.

Parameters:

QuNrs (list) – Quantum number names for which the values are plotted.
ax (matplotlib.axis, optional) – axis where to put the plot. The default is None meaning to use plt.gca().
limits (tuple or list, optional) – frequency limits which determine the minimum and maximum of the frequency axis. The default is None meaning the whole range is used.
branratio_TH (float, optional) – branching ratio threshold. Transitions with smaller branching ratios are ignored. The default is 1e-2.
limits_unit (str, optional) – Unit of the limits that are provided ([‘THz’,’cm-1’,’MHz’]). The default is ‘THz’.
markers (list(str), optional) – markers to be used for the plotted points for each Quantum number. The default is [‘+’,’x’,’.’,’1’,’2’,’3’,’4’].
legend (bool, optional) – Whether to use a legend. The default is True.
xaxis_func (func, optional) – function to convert the x axis. The default is lambda x: x.

class MoleCool.spectra.ElectronicStateConstants(const={}, unit='1/cm', nu=0, **kwargs)[source]#

Bases: object

An instance of this class represents an object which includes all molecular constants for evaluating the effective Hamiltonian yielding the molecular eigenstates and respective eigenenergies.

After the provided constants are loaded into the instance they can simply be modified or returned via:

const = ElectronicStateConstants()
const['B_e'] = 0.21
print(const['g_S'])

Parameters:

const (dict, optional) – dictionary of all constants in wave numbers (1/cm) required for the effective Hamiltonian. See the predefined constant attributes of this class, e.g. const_vib or const_rot, containing all possible names of the constants which are set to zero initially. The values of the provided dictionary const are then loaded into the class’ new instance. The default is {}.
unit (str, optional) – unit of the provided constants. Can either be ‘1/cm’ for wave numbers or ‘MHz’ for frequency. The default is ‘1/cm’.
nu (int, optional) – vibrational quantum number for the vibrational levels. The default is 0.
**kwargs (optional) – the values of the provided dictionary const can also be given as normal keyword arguments, e.g. B_e = 0.21, which will overwrite the ones from the dictionary.

Tip

Such instance can nicely export the defined constants as a HTML file (see show()) or can be saved with all its properties via the function save_object() and can be loaded later using the function open_object().

Raises:: KeyError – if the dictionary const or the keyword arguments kwargs contains some values for which the respective key is not defined.

const_elec = ['T_e']#: electronic energy offset constant (this constant equals the transition frequency if no vibrational constants are given. (see ElectronicStateConstants.electrovibr_energy()).)

const_vib = ['w_e', 'w_e x_e', 'w_e y_e']#: vibrational constants

const_rot = ['B_e', 'D_e', 'H_e', 'alpha_e', 'gamma_e', 'beta_e']#: rotation constants

const_sr = ['gamma', 'gamma_D']#: spin-rotation constants

const_so = ['A_e', 'alpha_A', 'A_D']#: spin-orbit constants

const_HFS = ['a', 'b_F', 'c', 'd', 'c_I', 'a_2', 'b_F_2', 'c_2', 'd_2']#: hyperfine constants

const_eq0Q = ['eq0Q']#: electric quadrupol interaction

const_LD = ['o', 'p', 'q']#: Lambda-doubling constants

const_Zeeman = ['g_l', "g'_l", 'g_S', "g'_L"]#: (magnetic) Zeeman constants. g_S and g’_L are initially set to 2.002 and 1. respectively.

const_all = ['T_e', 'w_e', 'w_e x_e', 'w_e y_e', 'B_e', 'D_e', 'H_e', 'alpha_e', 'gamma_e', 'beta_e', 'gamma', 'gamma_D', 'A_e', 'alpha_A', 'A_D', 'a', 'b_F', 'c', 'd', 'c_I', 'a_2', 'b_F_2', 'c_2', 'd_2', 'eq0Q', 'o', 'p', 'q', 'g_l', "g'_l", 'g_S', "g'_L"]#: sum of all constant names

constants_zero = {'A_D': 0.0, 'A_e': 0.0, 'B_e': 0.0, 'D_e': 0.0, 'H_e': 0.0, 'T_e': 0.0, 'a': 0.0, 'a_2': 0.0, 'alpha_A': 0.0, 'alpha_e': 0.0, 'b_F': 0.0, 'b_F_2': 0.0, 'beta_e': 0.0, 'c': 0.0, 'c_2': 0.0, 'c_I': 0.0, 'd': 0.0, 'd_2': 0.0, 'eq0Q': 0.0, "g'_L": 1.0, "g'_l": 0.0, 'g_S': 2.002, 'g_l': 0.0, 'gamma': 0.0, 'gamma_D': 0.0, 'gamma_e': 0.0, 'o': 0.0, 'p': 0.0, 'q': 0.0, 'w_e': 0.0, 'w_e x_e': 0.0, 'w_e y_e': 0.0}#: dictionary of all predefined constants which are set to zero initially

show(formatting='all', createHTML=False)[source]#

returns a pandas.DataFrame object which shows the defined constants in a nice format. This table can then be saved as a .html file.

Parameters:

formatting (str, optional) – Can either be ‘all’ for printing all constants or ‘non-zero’ for printing only the non-zero constants. The default is ‘all’.
createHTML (bool or str, optional) – if True the returned table with the specific formatting is saved as a HTML file ElectronicStateConstants.html. If str the HTML file is saved with this filename. The default is False.

Returns:

DF – table of all constants with further explanatory comments.

Return type:

pandas.DataFrame

get_isotope_shifted_constants(masses, masses_isotope, g_N=0, g_N_isotope=0, inplace=False)[source]#

calculates new isotope-shifted constant set. –> see https://www.lfd.uci.edu/~gohlke/molmass/ for precise masses.

Parameters:

masses (list or ndarray) – masses of the two atoms of the molecule for which the constants are given, e.g. [137.9052, 18.9984] for 138BaF.
masses_isotope (list or ndarray) – masses of the two atoms of the molecule for which the constants should be calculated
inplace (bool) – determines if the current constants are replaced inplace.

Returns:

Copy of the current ElectronicStateConstants instance with isotope-shifted constants.

Return type:

ElectronicStateConstants

to_dict(include_vdep_consts=True, exclude_default=False)[source]#

Converts the defined constants to a dictionary which can also include calculated values, e.g. B_v() and D_v().

Parameters:

include_vdep_consts (bool, optional) – whether the dictionary includes also the calculated values, e.g. B_v(), D_v(), and A_v(). The default is True.
exclude_default (bool, optional) – whether the dictionary includes all possible constants (False) or only the constants which differ from the default values (True). The default is False.

Returns:

dic – dictionary with all defined constants.

Return type:

dict

update(const, exclude_default=True, use_consts=[])[source]#

Update the constants defined in the current constants instance (ElectronicStateConstants) with the ones from another one.

Parameters:

const (ElectronicStateConstants) – the instance including the constants values for updating the current constants instance.
exclude_default (bool, optional) – Same keyword argument as in to_dict(). The default is True.
use_consts (list, optional) – If it is desired to only update a certain set of constants, one can specify these constants in a list of strings, e.g. [‘b_F’,’c’]. The default is [].

DunhamCoeffs()[source]#: Handling the Dunham coefficients. Under construction..

property b#

property b_2#

property A_v#

returns the vibrational-state-dependent spin-orbit constant A_v.

\(A_v = A_e + \alpha_A (v + 1/2)\).

property B_v#

returns the vibrational-state-dependent rotational constant B_v.

\(B_v = B_e - \alpha_e (v + 1/2) + \gamma_e (v + 1/2)^2\).

property D_v#

returns the vibrational-state-dependent rotational constant D_v.

\(D_v = D_e + \beta_e (v + 1/2)\).

property electrovibr_energy#

returns the sum of the electronic and vibrational energy.

\(E = T_e + \omega_e (v + 1/2) - \omega_e \chi_e (v+1/2)^2 + \omega_e y_e (v+1/2)^3\).

class MoleCool.spectra.ElectronicState(label, Smultipl, L, Hcase='a', nu=0, const={}, Gamma=None)[source]#

Bases: object

This class represents an electronic ground or excited state manifold which are part of the molecular level structure. After an electronic state is created with certain constants of the effective Hamiltonian all the single hyperfine states can be added in order to calculate the eigenstates and eigenenergies (see calc_eigenstates() and get_eigenstates()).

Parameters:

label (str) – label of the electronic state: the first character of this string has to be specified as ‘X’ for a ground state or as ‘A’, ‘B’, ‘C’, … for an excited state.
Smultipl (int) – spin mulitplicity, i.e. \(2S+1\).
L (int) – orbital angular momentum which defines the type of the electronic state as well as the absolute value of the quantum number Lambda. Can either be provided as integer \(0,1,2,3,...\) or as the respective Greek symbol \(\Sigma,\Pi,\Delta,\Phi,...\).
Hcase (str, optional) – Hund’s case describing the states within the electronic state manifold. Possible values: ‘a’ for pure Hund’s case a, ‘a_p’ for parity conserved case a, and ‘b’ for case b. The default is ‘a’.
nu (int, optional) – vibrational quantum number for the vibrational levels. The default is 0.
const (dict or ElectronicStateConstants, optional) – dictionary of all constants in wave numbers (1/cm) required for the effective Hamiltonian or directly an instance of the class ElectronicStateConstants (see for further documentation). During initialization of the class ElectronicState an attribute const as an instance of ElectronicStateConstants is created. The default is {}.
Gamma (float, optional) – if the electronic state has the function of an excited state, the natural linewidth \(\Gamma\) must be given for generating a spectrum. The natural linewidth Gamma must be given in MHz as an non-angular frequency (i.e. Gamma = 1/(2*pi*lifetime)*1e-6. The default is None.

states#: list for storing the pure states which can be added after class initialization

get_energy_casea(J, Omega, p)[source]#

calculate the energy of the electronic state as Hund’s case (a). The energy is evaluated with an approximate analytic expression and returned in units of wave numbers (1/cm).

Parameters:

J (float) – total angular momentum quantum number without nuclear spin.
Omega (float) – absolute value of the quantum number \(\Omega = \Lambda + \Sigma\).
p (int) – parity of the excited state. Either +1 or -1.

Returns:

E – energy of the state in wave numbers (1/cm).

Return type:

float

get_energy_caseb(N, sr)[source]#

calculate the energy of the electronic state as Hund’s case (b). The energy is evaluated with an approximate analytic expression and returned in units of wave numbers (1/cm).

Parameters:

N (int) – rotational quantum number N.
sr (int) – Can be either +1 or -1 for the two energy states which are shifted up or down in energy respectively due to the spin-rotation interaction.

Returns:

E – energy of the state in wave numbers (1/cm).

Return type:

float

build_states(Fmax, Fmin=None)[source]#

builds all the states within an electronic state manifold in the range from Fmin to Fmax in units of the total angular momentum quantum number. These states are stored in the variable states in the instance of this class ElectronicState. Every time this method is called potentially already included states are deleted.

Parameters:

Fmax (float) – upper limit of the total angular momentum quantum number to which all states are added into this instance of ElectronicState.
Fmin (float, optional) – respective lower limit of the total ang. mom. quantum number. By default this number is set to the smallest possible number which is either 0 or 0.5. The default is None.

Note

If Fmax or Fmin is not properly specified (e.g. when F can only take integer values and Fmax=3.5 is provided), it is adjusted to good values instead.

calc_eigenstates()[source]#: calculates the matrix elements of the various terms of the total Hamiltonian and determines the eigenvalues and eigenstates which are sorted by energy and stored in the variables Ew and Ev in the current instace of the class ElectronicState. The eigenstates can be nicely printed via get_eigenstates().

Warning

The total diagonalized Hamiltonian excludes the electronic and vibrational constants since the vibrational motion can be decoupled completely from the smaller interactions like rotation, hyperfine, spin-orbit,… . So, the electronic and vibrational part of the molecular eigenenergies are not included in the obtained eigenenergies of this function Ew but they can simply be added as an energy offset (what is done in the method Molecule.calc_branratios()).

get_eigenstates(rounded=None, onlygoodQuNrs=True, createHTML=False, Hcasebasis=True, mixed_states=False)[source]#

returns the sorted eigenenergies and respective eigenstates determined by the method calc_eigenstates() in a nice format via the datatype pandas.DataFrame in order to be printed.

Parameters:

rounded (int, optional) – rounded to which the values of the eigenstates are rounded. The default is 4.
onlygoodQuNrs (bool, optional) – specifies if only the good Quantum numbers are included for getting a better overview of the printed DataFrame. The default is True.
createHTML (bool or str, optional) – if True a Html file eigenstates.html with the DataFrame is generated for a better view of the eigenstates. If a string is given, the file will be saved as the respective filename. The default is False.
Hcasebasis (bool, optional) – If the basis of the eigenenergies is given in pure Hund’s case a states (False) or in the specified Hund’s case basis. The default is True.

Returns:

the rounded DataFrame comprising the eigenvalues and eigenstates to be nicely printed

Return type:

pandas.DataFrame

get_states_as_DF(onlygoodQuNrs=False, Hcasebasis=False)[source]#

returns the states included in the instance ElectronicState in a nice format via the datatype pandas.DataFrame in order to be printed. But at first any states have to be added via build_states().

Parameters:

onlygoodQuNrs (bool, optional) – specifies if only the good Quantum numbers are included for getting a better overview of the printed DataFrame. The default is False.
Hcasebasis (bool, optional) – specifies whether the pure states or the states in the respective Hund’s case basis are shown.

Returns:

the rounded DataFrame comprising the pure states to be nicely printed

Return type:

pandas.DataFrame

calc_basis_change()[source]#

Calculates the Hund’s case states from the pure case a states and determines the transformation matrix from the pure state basis to another Hund’s case basis.

Returns:: Transformation matrix from pure to Hund’s case basis.
Return type:: np.ndarray

get_gfactors(Bmax=0.0001)[source]#

calculates the mixed g-factors for every hyperfine level eigenstate. These g-factors are returned as an array with the same order as the eigenstates for zero magnetic field which can be printed via get_eigenstates(). The gfactor pd.DataFrame is also stored in the attribute gfactors.

Parameters:: Bmax (float, optional) – maximum magnetic field strength in T to which the mixed g-factors are calculated. This value should be in the small region where the Zeeman shifts possess only linear behavior. The default is 1e-4.
Returns:: array containing the mixed g-factors ordered by energy of the eigenstates.
Return type:: pandas.DataFrame

plot_Zeeman(Bfield)[source]#

plots the Zeeman-splitted levels versus a magnetic field. In the plot the eigenvalues are sorted such that the energy crossings between different magnetic hyperfine levels are assigned to the right curves using the function eigensort().

Parameters:: Bfield (array-type or float) – When Bfield is of array-type the eigenenergies are calculated for every single value. Otherwise, if Bfield is a float, the Zeeman Hamiltonian is evaluated for 20 values from 0.0 to Bfield. This input parameter has to be provided in units of Tesla.

export_OBE_properties(index_filter={}, rounded=None, QuNrs=[], HFfreq_offset=0, Bmax=0.0001, nested_dict=False, get_QuNr_keyval_pairs_kwargs={})[source]#

Export all the important properties connected to a single electronic state to a dictionary in a proper format for the OBE simulation code to import the properties from the corresponding json file. This method is e.g. used in the similar function Molecule.export_OBE_properties() from the Molecule.Molecule class to also save the whole json file with all properties.

Parameters:

index_filter (dict, optional) – to filter the states of interest. See rows argument of multiindex_filter(). The default is {}.
rounded (int, optional) – digit to round the frequencies and gfactors. The default is None meaning that no rounding is applied.
QuNrs (list(str), optional) – Which Quantum numbers should be exported into the output dictionary. The default is [] meaning that only the necessary unique Quantum numbers are used (see get_unique_multiindex_names()).
HFfreq_offset (float, optional) – applying an offset to the whole array of hyperfine frequencies (MHz) whose lowest eigenvalue is always normalized to 0. The default is 0.
Bmax (float, optional) – Determines how the gfactors are calculated (see get_gfactors()). The default is 1e-4.
nested_dict (bool, optional) – Whether the raw dictionary with the data or properties should be nested into other dictionaries required by the json file. See get_QuNr_keyval_pairs(). The default is False.
get_QuNr_keyval_pairs_kwargs (kwargs, optional) – keyword arguments for get_QuNr_keyval_pairs(). The default is {}.

Returns:

Dictionary with the properly formatted ElectronicState level properties.

Return type:

dict

property nu#: vibrational quantum number for the vibrational levels. Can be called and changed.

property N#

returns the number of states in the current instance of ElectronicState.

Returns:: number of states
Return type:: int

class MoleCool.spectra.QuState(**kwargs)[source]#

Bases: object

Instance of the class represents a molecular state as Hund’s case a.

Parameters:: **kwargs (float) – quantum numbers of the Hund’s case a.

goodQuNrs = []#

description = 'State without certain Hunds case'#

DF(onlygoodQuNrs=False)[source]#

return a DataFrame as nice representation of the state with all quantum numbers.

Parameters:: onlygoodQuNrs (bool, optional) – if all quantum numbers or only the good ones are shown. The default is False.
Returns:: DataFrame showing the quantum numbers.
Return type:: pandas.DataFrame

QuNrs_default()[source]#

class MoleCool.spectra.Hcasea(**kwargs)[source]#

Bases: QuState

Instance of the class represents a molecular state as Hund’s case a.

Parameters:: **kwargs (float) – quantum numbers of the Hund’s case a.

goodQuNrs = ['L', 'Si', 'Om', 'J']#: good QuNrs for a pure Hund’s case a

description = 'Hunds case a (pure state)'#

to_Hcase(Hcase='b', printing=False)[source]#

transforms the pure Hund’s case a state into another Hund’s case basis.

Parameters:

Hcase (str, optional) – Hund’s case basis for transformation. The default is ‘b’.
printing (bool, optional) – if the linear combination of the states of the new basis is printed. The default is False.

Returns:

linear combination of the states of the new Hund’s case basis as a dictionary with the keys prefacs and states.

Return type:

dict

DF(onlygoodQuNrs=False)#

return a DataFrame as nice representation of the state with all quantum numbers.

Parameters:: onlygoodQuNrs (bool, optional) – if all quantum numbers or only the good ones are shown. The default is False.
Returns:: DataFrame showing the quantum numbers.
Return type:: pandas.DataFrame

QuNrs_default()#

class MoleCool.spectra.Hcasea_p(**kwargs)[source]#

Bases: QuState

Instance of the class represents a molecular state as Hund’s case a.

Parameters:: **kwargs (float) – quantum numbers of the Hund’s case a.

goodQuNrs = ['P', 'Om', 'J']#: good QuNrs for a Hund’s case a (parity conserved)

description = 'Hunds case a (parity conserved)'#

DF(onlygoodQuNrs=False)#

return a DataFrame as nice representation of the state with all quantum numbers.

Parameters:: onlygoodQuNrs (bool, optional) – if all quantum numbers or only the good ones are shown. The default is False.
Returns:: DataFrame showing the quantum numbers.
Return type:: pandas.DataFrame

QuNrs_default()#

class MoleCool.spectra.Hcaseb(**kwargs)[source]#

Bases: QuState

Instance of the class represents a molecular state as Hund’s case a.

Parameters:: **kwargs (float) – quantum numbers of the Hund’s case a.

goodQuNrs = ['L', 'N', 'J']#: good QuNrs for a pure Hund’s case b

description = 'Hunds case b_betaJ'#

to_Hcase(Hcase='b_betaS', printing=False)[source]#

transforms the pure Hund’s case a state into another Hund’s case basis.

Parameters:

Hcase (str, optional) – Hund’s case basis for transformation. The default is ‘b_betaS’.
printing (bool, optional) – if the linear combination of the states of the new basis is printed. The default is False.

Returns:

linear combination of the states of the new Hund’s case basis as a dictionary with the keys prefacs and states.

Return type:

dict

DF(onlygoodQuNrs=False)#

return a DataFrame as nice representation of the state with all quantum numbers.

Parameters:: onlygoodQuNrs (bool, optional) – if all quantum numbers or only the good ones are shown. The default is False.
Returns:: DataFrame showing the quantum numbers.
Return type:: pandas.DataFrame

QuNrs_default()#

class MoleCool.spectra.Hcaseb_betaS(**kwargs)[source]#

Bases: QuState

Instance of the class represents a molecular state as Hund’s case a.

Parameters:: **kwargs (float) – quantum numbers of the Hund’s case a.

goodQuNrs = ['L', 'N', 'G']#

description = 'Hunds case b_betaS'#

DF(onlygoodQuNrs=False)#

return a DataFrame as nice representation of the state with all quantum numbers.

Parameters:: onlygoodQuNrs (bool, optional) – if all quantum numbers or only the good ones are shown. The default is False.
Returns:: DataFrame showing the quantum numbers.
Return type:: pandas.DataFrame

QuNrs_default()#

MoleCool.spectra.H_tot(x, y, const)[source]#

calculates and returns the matrix element of the total Hamiltonian without external fields between two states.

Parameters:

x (Hcasea) – first state.
y (Hcasea) – second state.
const (dict) – dictionary of all constants required for the effective Hamiltonian. When this function is called by the method ElectronicState.calc_eigenstates(), the method ElectronicStateConstants.to_dict() of the attribute const within ElectronicState is used to create a proper dictionary.

MoleCool.spectra.H_Zeeman(x, y, const, Bfield)[source]#

calculates and returns the matrix element of the Zeeman interaction between two states.

Parameters:

x (Hcasea) – first state.
y (Hcasea) – second state.
const (dict) – dictionary of all constants required for the effective Hamiltonian. When this function is called by the method ElectronicState.calc_eigenstates(), the method ElectronicStateConstants.to_dict() of the attribute const within ElectronicState is used to create a proper dictionary.
Bfield (float) – magnetic field strength in T.

MoleCool.spectra.H_d(x, y)[source]#

calculates and returns the matrix element of the electric dipole operator between two states.

Parameters:

x (Hcasea) – first state.
y (Hcasea) – second state.

MoleCool.spectra.addJ(J1, J2)[source]#: adding two angular momenta. Returns an array of all possible total angular momenta.

MoleCool.spectra.cb(x)[source]#: curly brackets expression in the Hamiltonian

MoleCool.spectra.sb(x)[source]#: square brackets expression in the Hamiltonian

MoleCool.spectra.phs(x)[source]#: phase expression ‘(-1)^(x) in the Hamiltonian

MoleCool.spectra.kd(x, y)[source]#: delta kronecker

MoleCool.spectra.isint(x, raise_err=False)[source]#: test if x is an integer value and raise an error if it’s intended

MoleCool.spectra.ishalfint(x, raise_err=False)[source]#: test if x is a half-integer value and raise an error if it’s intended

MoleCool.spectra.eigensort(x, y_arr)[source]#

sorts an eigenvalue matrix, e.g. eigenvalues as a function of a varying magnetic or eletric field. This is especially useful since crossing curves of eigenvalues are rearanged in the right order.

Parameters:

x (1D numpy array and length N) – x array, e.g. for the varying magnetic of electric field.
y_arr (2D numpy array of shape(N,M)) – Array containing all eigenvalues for each value of x.

Returns:

y_arr – ordered array.

Return type:

2D numpy array of shape(N,M)

MoleCool.spectra.multiindex_filter(DF, rows={}, cols={}, drop_level=True)[source]#

Filter a DataFrame object only for few specific multiindex values.

Parameters:

DF (pd.DataFrame) – DataFrame which is going to be filtered.
rows (dict, optional) – rows to be retained, i.e. dict(N=1). The default is dict().
cols (dict, optional) – columns to be retained, i.e. dict(P=1,Om=0.5,J=0.5). The default is dict().
drop_level (bool, optional) – If redundant index levels should be dropped. The default is True.

Returns:

DF – filtered DataFrame.

Return type:

pd.DataFrame

MoleCool.spectra.get_QuNrvals_from_multiindex(multiindex, QuNrs)[source]#

Extract lists with the values certain Quantum numbers from a pandas.MultiIndex object.

Parameters:

multiindex (pandas.MultiIndex) – MultiIndex with one or multiple columns corresponding to Quantum numbers.
QuNrs (list(str)) – names of the Quantum number for which the values should be extracted.

Returns:

d – dictionary with Quantum number names as keys and the Quantum number values as lists.

Return type:

dict

MoleCool.spectra.get_QuNr_keyval_pairs(ElState, multiindex, QuNrs_names=[], include_v=True)[source]#

Calculated list of pairs of the name and value of certain Quantum numbers included in a MultiIndex object.

Parameters:

ElState (ElectronicState) – ElectronicState for which the vibrational and ground or excited data is extracted.
multiindex (pandas.MultiIndex) – MultiIndex object which includes multiple rows of Quantum number values for multiple Quantum number names columns.
QuNrs_names (list(str), optional) – all Quantum number names to be ectraced. The default is [].
include_v (bool, optional) – Whether to include the vibrational Quantum numbers. The default is True.

Example

>>> get_QuNr_keyval_pairs(Mol.A, Mol.A.get_eigenstates().iloc[:10].index, QuNrs_names=['Om'])
Out: ['exs=A', 'v=0', 'Om=0.5']

Returns:: list of Quantum number key and value pairs, e.g. [‘gs=X’, ‘v=0’, ‘N=1’].
Return type:: list(str)

MoleCool.spectra.get_unique_multiindex_names(multiindex)[source]#: Calculate list of unique column names from a pandas.MultiIndex object.

class MoleCool.spectra.NestedDict[source]#

Bases: dict

Nested dictionary class to handle multiple key with the corresponding __getitem__ and __setitem__ methods.

Example

>>> f1 = NestedDict()
>>> f1
{}
>>> f1[['a','b','c']]
>>> f1
{'a': {'b': {'c': {}}}}
>>> f1[['a2','b2','c2']] =1234
>>> f1
{'a': {'b': {'c': {}}}, 'a2': {'b2': {'c2': 1234}}}
>>> f1[['a','b']].update(dict(c2=1234))
>>> f1
{'a': {'b': {'c': {}, 'c2': 1234}}, 'a2': {'b2': {'c2': 1234}}}

clear() → None. Remove all items from D.#

copy() → a shallow copy of D#

fromkeys(value=None, /)#: Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)#: Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items#

keys() → a set-like object providing a view on D's keys#

pop(k[, d]) → v, remove specified key and return the corresponding value.#: If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()#

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)#

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None. Update D from dict/iterable E and F.#: If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values#

MoleCool.spectra

Contents

MoleCool.spectra#