MoleCool.Levelsystem.Levelsystem

MoleCool.Levelsystem.Levelsystem#

class MoleCool.Levelsystem.Levelsystem(load_constants=None, verbose=True)[source]#

Bases: object

Levelsystem consisting of ElectronicState instances and methods to add them properly. These respective objects can be retrieved and also deleted by using the normal item indexing of a Levelsystem’s object:

from MoleCool import Levelsystem
levels = Levelsystem()

# define as ground state ('gs')
levels.add_electronicstate('S12', 'gs')
levels.S12.add(J=1/2,F=[1,2])

state1 = levels.S12[0]
print(state1)

del levels.S12[-1] # delete last added State instance
del levels['S12']  # delete complete electronic state

Parameters:

load_constants (str, optional) – the constants of the levelsystem can be imported from an .json file. If this is desired provide the respective filename without the .json extension. The default is None.
verbose (bool, optional) – Specifies if additional warnings should be printed during the level construction. The default is True.

Tip

When arbitrary custom level systems want to be defined, first all levels have to be added.

Then the default constants and properties can be nicely viewed with the function print_properties(). Afterwards the values in these pandas.DataFrames (here: vibrational branchings, transition wavelength, and g-factor) can be easily modified via <DataFrame>.iloc[<index>].

Tip

Important properties within an instance Levelsystem can be accessed with the get_<property>() methods or directly via the properties without get_ in their names, like:

dMat # electric dipole matrix
dMat_red # reduced electric dipole matrix
vibrbranch # vibrational branching ratios
wavelengths # wavelengths (in nm) between the transitions

Methods

`Isat_eff`(GrSt, ExSt)	Calculate the effective multi-level saturation intensity in W/m^2 between two electronic states whose states are all coupled together.
`__init__`([load_constants, verbose])	Levelsystem consisting of `ElectronicState` instances and methods to add them properly. These respective objects can be retrieved and also deleted by using the normal item indexing of a `Levelsystem`'s object::.
`add_all_levels`(v_max)	Add all ground and excited states of a molecule conveniently with a loss state.
`add_electronicstate`(label, gs_exs[, ...])	Add an electronic state (ground or excited state) as instance of the class `ElectronicState` to this instance of `Levelsystem`.
`calc_Gamma`()	Calculate the natural decay rate Gamma (in angular frequency) for each single excited state.
`calc_M_indices`()	Calculate the indices determining all hyperfine states within a specific F or F' of the ground or excited state.
`calc_all`()	Calculate all level properties once in the beginning, so that they are stored and calling the method `calc_OBEs()` multiple times doesn't require additional computation time.
`calc_branratios`()	Calculate fully normalized branching ratios using the dipole matrix calculated in the function `calc_dMat()` (see for more details).
`calc_dMat`()	Calculate matrix elements of the electric dipole moment operator.
`calc_freq`()	Calculate the angular absolute frequency differences between all levels included in this class using the wavelengths and frequencies specified by the function `get_freq()`.
`calc_muMat`()	Calculate the magnetic dipole moment operator matrix for all levels included in this class using the g-factors specified by the function `get_gfac()`.
`check_config`([raise_Error])	Check the configuration of the Levelsystem to be used in calculating laser cooling dynamics.
`get_dMat`([gs, exs])	Return the electric dipole matrix.
`get_dMat_red`([gs, exs])	Return the reduced electric dipole matrix.
`get_transdipmoms`()	Return transition dipole moments between electronic states.
`get_vibrbranch`([gs, exs])	Return a matrix for the vibrational branching ratios between vibrational excited levels with \(\nu\) and ground levels wth \(\nu'\).This matrix is either simply loaded from the .json file or constructed with the same branching ratios for all transitions.
`get_wavelengths`([gs, exs])	Return a list of matrices for nicely displaying the wavelengths between the vibrational transitions and the frequencies between hyperfine transitions to conveniently specifying or modifying all participating transitions.
`index_ElSt`(ElSt[, gs_exs, include_Ngrs_for_exs])	Return the total index of the first state belonging to a certain electronic state.
`plot_transition_spectrum`([std, xaxis, ...])	Plot the transition spectrum with Voigt profiles using the energies and strengths from `transitions_energies_strengths()`.
`print_properties`()	Print all relevant constants and properties of the composed levelsystem in a convenient way to modify them if needed afterwards.
`reset_properties`()	Reset and initialize all property objects (e.g. dMat, dMat_red, vibrbranch, wavelengths, muMat, Mindices, Gamma).
`transitions_energies_strengths`([...])	Yield the transition strengths and energies without including all mF levels.
`val_state_in_DF`(st, DF)
`val_states_in_DF`(st1, st2, DF)

Attributes

`Isat`	Calculate the two-level saturation intensity in W/m^2 for all transitions.
`N`	Return the total number of unique states defined in all electronic states as an integer, i.e. N = `lNum()` + `uNum()` - `iNum()`.
`dMat`	electric dipole matrix
`dMat_red`	reduced electric dipole matrix
`description`	Display a short description with the number of included state objects.
`electronic_states`	Return a list containing all defined instances of electronic states, i.e. stacking list of `grstates()` and `exstates()`.
`exstates`	Return a list containing all defined instances of excited electronic states (`ElectronicExState`).
`exstates_labels`	Return a list containing the labels of all excited electronic states
`grstates`	Return a list containing all defined instances of ground electronic states (`ElectronicGrState`).
`grstates_labels`	Return a list containing the labels of all ground electronic states
`iNum`	Return the total number of states defined in all intermediate electronic states as an integer.
`lNum`	Return the total number of states defined in the ground electronic states as an integer.
`states`	Return a combined list of all state objects defined in the individual electronic states.
`transdipmoms`	transition dipole moments
`uNum`	Return the total number of states defined in the excited electronic states as an integer.
`vibrbranch`	vibrational branching ratios
`wavelengths`	transition wavelengths and frequencies

add_all_levels(v_max)[source]#

Add all ground and excited states of a molecule conveniently with a loss state.

Parameters:: v_max (int) – all ground states with vibrational levels \(\nu\le\) v_max and respectively all excited states up to (v_max-1) are added to the subclasses Groundstates and Excitedstates.

add_electronicstate(label, gs_exs, load_constants=None, **kwargs)[source]#

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

Parameters:

label (str) – label or name of the electronic state so that this electronic state will be accessible via levels.<label>.
gs_exs (str) – determines whether an electronic ground or excited state should be added. Therefore, gs_exs can be either ‘gs’ or ‘exs’.
load_constants (str, optional) – the constants of the levelsystem can be imported from an .json file. If this is desired provide the respective filename without the .json extension. The default is None.
**kwargs (kwargs) – keyword arguments for the eletronic state (see ElectronicState for the specific parameters)

Returns:

Initialized electronic state instance.

Return type:

ElectronicState

get_dMat(gs=None, exs=None)[source]#

Return the electric dipole matrix. This matrix is either simply loaded from the .json file or constructed with the reduced electric dipole matrix given by the function get_dMat_red().

Parameters:: calculated_by (str, optional) – Additional parameter if multiple different matrices are available for one system. The default is ‘YanGroupnew’.
Returns:: Electric dipole matrix.
Return type:: pandas.DataFrame

get_dMat_red(gs=None, exs=None)[source]#

Return the reduced electric dipole matrix. This matrix is either simply loaded from the .json file or constructed with the electric dipole matrix given by the function dMat_red(). If no dipole matrix or a reduced one is available a new reduced matrix is constructed with only ones for each transition which can be adjusted afterwards.

Returns:: Reduced electric dipole matrix.
Return type:: pandas.DataFrame

get_vibrbranch(gs=None, exs=None)[source]#

Return a matrix for the vibrational branching ratios between vibrational excited levels with \(\nu\) and ground levels wth \(\nu'\).This matrix is either simply loaded from the .json file or constructed with the same branching ratios for all transitions.

Returns:: vibrational branching ratios matrix.
Return type:: pandas.DataFrame

get_transdipmoms()[source]#

Return transition dipole moments between electronic states.

Returns:: Transition dipole moments.
Return type:: pandas.DataFrame

get_wavelengths(gs=None, exs=None)[source]#

Return a list of matrices for nicely displaying the wavelengths between the vibrational transitions and the frequencies between hyperfine transitions to conveniently specifying or modifying all participating transitions. These wavelengths and frequencies are loaded from the .json file if available. Otherwise all wavelengths are set to 860e-9 and all other hyperfine frequencies to zero to be adjusted.

Returns:: list of matrices specifying the frequencies of the participating transitions.
Return type:: list of pandas.DataFrame and pandas.Series entries.

property dMat#: electric dipole matrix

property dMat_red#: reduced electric dipole matrix

property vibrbranch#: vibrational branching ratios

property wavelengths#: transition wavelengths and frequencies

property transdipmoms#: transition dipole moments

calc_dMat()[source]#

Calculate matrix elements of the electric dipole moment operator. In contrast to the other functions get_dMat() or get_dMat_red(), this method calculates the normalized electric dipole matrix as numpy.ndarray ready to be directly called and used for the methods calc_rateeqs() and calc_OBEs(). This matrix includes also the vibrational branching ratios and handles the loss state in a correct way and is not meant to be modified.

Returns:: fully normalized electric dipole matrix.
Return type:: numpy.ndarray

calc_branratios()[source]#

Calculate fully normalized branching ratios using the dipole matrix calculated in the function calc_dMat() (see for more details).

Returns:: fully normalized branching ratios.
Return type:: numpy.ndarray

calc_freq()[source]#

Calculate the angular absolute frequency differences between all levels included in this class using the wavelengths and frequencies specified by the function get_freq(). These values are returned as numpy array ready to be directly called and used for the functions calc_rateeqs() and calc_OBEs().

Returns:: angular frequency array.
Return type:: numpy.ndarray

val_states_in_DF(st1, st2, DF)[source]#

val_state_in_DF(st, DF)[source]#

calc_muMat()[source]#

Calculate the magnetic dipole moment operator matrix for all levels included in this class using the g-factors specified by the function get_gfac(). These values are returned as numpy array ready to be directly called and used for the function calc_OBEs().

Returns:: magnetic moment operator matrix.
Return type:: tuple of numpy.ndarray

calc_M_indices()[source]#

Calculate the indices determining all hyperfine states within a specific F or F’ of the ground or excited state. These values are used in the function calc_OBEs() when looping through all hyperfine states in conjunction with the g-factors for calculation the effect of a magnetic field.

Returns:: indices of the magnetic sublevels belonging to a certain F or F’ of the ground or excited state.
Return type:: tuple of tuple of lists

calc_Gamma()[source]#

Calculate the natural decay rate Gamma (in angular frequency) for each single excited state.

Returns:: Gamma array of length uNum as angular frequency [Hz].
Return type:: numpy.ndarray

calc_all()[source]#: Calculate all level properties once in the beginning, so that they are stored and calling the method calc_OBEs() multiple times doesn’t require additional computation time.

transitions_energies_strengths(include_forbidden=False, gs=None, exs=None, use_calc_props=True)[source]#

Yield the transition strengths and energies without including all mF levels. This is e.g. used by the method plot_transition_spectrum(). The strengths are solely calculated using the property dMat_red().

Parameters:

include_forbidden (bool, optional) – Whether to include also the transitions with vanishing branchings. The default is False.
gs (str, optional) – Electronic ground state label. The default is None.
exs (str, optional) – Electronic excited state label. The default is None.
use_calc_props (bool, optional) – If True, the properties like the dipole matrix and all transition energies are calculated and then used to plot the spectrum with exactly the values that are used for the simulation. If False, the reduced dipole matrix property is directly used and the wavelengths property is not taken into account.

Returns:

Es (np.ndarray) – Energies in MHz.
branchings (np.ndarray) – reduced branching ratios.
states (list(tuple)) – list of tuple pairs containing the ground and excited state for each transition energy and branching.

plot_transition_spectrum(std=0, xaxis=[], xaxis_ext=5, N_points=500, wavelengths=[], relative_to_wavelengths=False, kwargs_single={}, kwargs_sum={'color': 'k', 'ls': '-'}, plot_single=True, plot_sum=True, ax=None, legend=True, QuNrs=[['F'], ['F']], exs=[], subplot_sep=200.0, E_unit='MHz', E_offset=0, kwargs_trans_ener_stre={})[source]#

Plot the transition spectrum with Voigt profiles using the energies and strengths from transitions_energies_strengths().

Parameters:

std (float, optional) – Standard deviation resulting in the Gaussian broadening of the voigt profile in MHz. The Lorentzian broadening is always given by the natural linewidth of the electronic excited state. The default is 0.
xaxis (list or np.ndarray, optional) – xaxis data points. The default is [].
xaxis_ext (float, optional) – if not xaxis is given, the range of the xaxis, given by the lowest and highest transition frequency, is extended by this factor multiplied by the sum of the Gaussian and Lorentzian broadening. The default is 5.
N_points (int, optional) – number of points plotted. The default is 500.
wavelengths (list, optional) – wavelengths that should be plotted within the range subplot_sep. By default all available transition wavelengths are used.
relative_to_wavelengths (bool, optional) – Whether the x-axis should be plotted in absolute frequency units or relative to wavelengths.
kwargs_single (dict, optional) – keyword arguments used in plt.plot() for the single transition lines. The default is dict().
kwargs_sum (dict, optional) – same as kwargs_single but for the sum. The default is dict(ls=’-’, color=’k’).
plot_single (bool, optional) – Whether to plot single transition lines. The default is True.
plot_sum (bool, optional) – Whether to plot the sum of all transition lines. The default is True.
ax (matplotlib.pyplot.axis or list of axis, optional) – axis or multiple axes to put the plot(s) on. The default is None.
legend (bool, optional) – Whether to show legend. The default is True.
QuNrs (list(list), optional) – QuNrs of ground and excited state used for labelling and legend. The default is [[‘J’,’F’],[‘F’]].
exs (list(str), optional) – List of excited states to be plotted (see transitions_energies_strengths()). By default only the first excited electronic state is used.
subplot_sep (float, optional) – Defines the range of the plotted x-axis and the separation for the automatic inclusion of all wavlengths (see parameter wavelengths) in units of ElectronicExState.Gamma(). Default is 200.
E_unit (str, optional) – Unit of the x-axis to be plotted. Can be one of ['GHz','MHz','kHz','Hz','Gamma']. Default is ‘MHz’.
E_offset (float, optional) – Energy offset on the xaxis. The default is 0.
kwargs_trans_ener_stre (dict, optional) – keyword arguments for transitions_energies_strengths(), e.g. gs as label used for the electronic ground state.

Returns:

ax (matplotlib.pyplot.axes or list for multiple plots) – axis of the plot.
data (dict(np.ndarray) or list for multiple plots) – raw data thats plotted. Includes the single transitions, the sum and the x axis data.

print_properties()[source]#: Print all relevant constants and properties of the composed levelsystem in a convenient way to modify them if needed afterwards.

check_config(raise_Error=False)[source]#

Check the configuration of the Levelsystem to be used in calculating laser cooling dynamics. E.g. involves to check whether the states are correctly defined.

Parameters:: raise_Error (bool, optional) – If the configuration is not perfect, this method raises an error message or only prints a warning depending on raise_Error. The default is False.

reset_properties()[source]#: Reset and initialize all property objects (e.g. dMat, dMat_red, vibrbranch, wavelengths, muMat, Mindices, Gamma).

property description#

Display a short description with the number of included state objects.

Type:: str

property states#: Return a combined list of all state objects defined in the individual electronic states.

property lNum#: Return the total number of states defined in the ground electronic states as an integer.

property uNum#: Return the total number of states defined in the excited electronic states as an integer.

property iNum#: Return the total number of states defined in all intermediate electronic states as an integer.

property N#: Return the total number of unique states defined in all electronic states as an integer, i.e. N = lNum() + uNum() - iNum().

property grstates#: Return a list containing all defined instances of ground electronic states (ElectronicGrState).

property exstates#: Return a list containing all defined instances of excited electronic states (ElectronicExState).

property electronic_states#: Return a list containing all defined instances of electronic states, i.e. stacking list of grstates() and exstates().

property grstates_labels#: Return a list containing the labels of all ground electronic states

property exstates_labels#: Return a list containing the labels of all excited electronic states

property Isat#: Calculate the two-level saturation intensity in W/m^2 for all transitions.

Isat_eff(GrSt, ExSt)[source]#: Calculate the effective multi-level saturation intensity in W/m^2 between two electronic states whose states are all coupled together. This quantity can be derived by rearranging the rate equations into a general approximate expression for the scattering rate. Here, the assumptions that all detunings are equal, all intensities are equal, and all excited states are equally populated are used.

index_ElSt(ElSt, gs_exs=None, include_Ngrs_for_exs=False)[source]#

Return the total index of the first state belonging to a certain electronic state. For example for two electronic excited states with each 3 single states defined, the method gives 0 and 3 for the first and second electronic excited state, respectively.

Parameters:

ElSt (str or ElectronicState) – Electronic state.
gs_exs (str, optional) – specify whether ElSt is a ground or excited state. The default is None so that its type is automatically inferred.
include_Ngrs_for_exs (bool, optional) – specifies whether the total number of ground state levels is added for an excited state. Default is False.

Returns:

total index of first level state defined in the ElectronicState ElSt

Return type:

int

MoleCool.Levelsystem.Levelsystem

Contents

MoleCool.Levelsystem.Levelsystem#