MoleCool.System.System

MoleCool.System.System#

class MoleCool.System.System(description=None, load_constants='', verbose=True)[source]#

Bases: object

An instance of this class is the starting point for simulating any atomic or molecular dynamics simulations. Specficially, it defines an object to not only store all important information about the system but also to calculate any time evolution.

Parameters:

description (str, optional) – A short description of this System can be added. If not provided, the attribute is set to the name of the respective executed main python file.
load_constants (str, optional) – File name of a certain molecule, atom or more general system whose respective level constants to be loaded or imported by the class Levelsystem via the constants defined in the .json file. The default is ‘’.

Example

After initiating a System object, the instances of Lasersystem, Levelsystem, and Bfield can be accessed via:

system = System()
print(system.lasers)
print(system.levels)
print(system.Bfield)

Methods

`__init__`([description, load_constants, verbose])	An instance of this class is the starting point for simulating any atomic or molecular dynamics simulations.
`calc_OBEs`([t_int, t_start, dt, t_eval, ...])	Calculate the time evolution of the single level populations with the optical Bloch equations.
`calc_Rabi_freqs`([position_dep])	Calculate the (angular) pure Rabi frequencies for each transition and each laser component (with 2*pi included).
`calc_rateeqs`([t_int, t_start, dt, t_eval, ...])	Calculate the time evolution of the single level populations with rate equations.
`calc_trajectory`(F_profile[, t_int, t_start, ...])	Calculate Monte Carlo simulations of classical particles which are propagated through a provided pre-calculated force profile to be used as interpolated function
`check_config`([raise_Error])	Check System configuration for simulating internal dynamics.
`draw_levels`([GrSts, ExSts, branratios, ...])	Draw all levels of certain Electronic states sorted by certain Qunatum numbers.
`get_N`([return_sum])	Retrieve the time-dependent populations as results after calculating the dynamics.
`get_Nscatt`([sum_over_ElSts])	Calculate time dependent scatterd photon number.
`get_Nscattrate`([sum_over_ElSts])	Calculate time dependent scattering rate.
`get_photons`([sum_over_ElSts])	Calculate totally scattered photon number.
`initialize_N0`([return_densitymatrix, random])	Initialize initial populations as a starting point for the OBEs or rate equations using pre-defined population attribute `N0` of the electronic states `ElectronicState`.
`plot_F`([figname, axes])	plot the Force over time for all three axes 'x','y', and'z'.
`plot_FFT`([only_sum, start_time])	plot the fast Fourier transform (FFT) of the time-dependent populations.
`plot_N`([figname, figsize, smallspacing])	plot populations of all levels over time.
`plot_Nscatt`([sum_over_ElSts])	plot the scattered photon number over time (integral of Nscattrate).
`plot_Nscattrate`([sum_over_ElSts])	plot the photon scattering rate over time (derivative of Nscatt).
`plot_Nsum`()	plot the population sum of all levels over time to ensure a small numerical deviation of the ODE solver.
`plot_all`()
`plot_dt`()	plot the time steps at which the populations are calculated.
`plot_r`()	plot the position over time for all three axes 'x','y', and'z'.
`plot_spectrum`([wavelengths, lasers, ...])	Plot the spectrum of `Laser` objects and transition spectra with their respective intensities.
`plot_v`()	plot the velocity over time for all three axes 'x','y', and'z'.
`reset_N0`()	Reset (last created) initial population self.N0 and initial populations for all electronic states
`set_r0`([r0, direction])	Set initial position of the particle(s).
`set_v0`([v0, direction])	Set initial velocity of the particle(s).

Attributes

`F`	calculate the force over time.
`Nscatt`	time dependent scattering number
`Nscattrate`	time dependent scattering rate
`hbarkG2`	Calculate \(\hbar k \Gamma /2\) using the wave vector defined in the laser system and natural lifetime defined in the first excited electronic state.
`photons`	totally scattered photons
`r0`	dictionary for parameters specifying the steady state conditions.
`v0`	initial velocity of the particle
`steadystate`	dictionary for parameters specifying the multiprocessing of calculations.

steadystate#: dictionary for parameters specifying the multiprocessing of calculations.

calc_rateeqs(t_int=2e-05, t_start=0.0, dt=None, t_eval=[], magn_remixing=False, magn_strength=8, position_dep=False, trajectory=False, verbose=True, return_fun=<function return_fun_default>, **kwargs)[source]#

Calculate the time evolution of the single level populations with rate equations.

Parameters:

t_int (float, optional) – interaction time in which the molecule is exposed to the lasers. The default is 20e-6.
t_start (float, optional) – starting time when the ode_solver starts the calculation. Useful for the situation when e.g. all cooling lasers are shut off at a specific time t1, so that a new calculation with another laser configuration (e.g. including only a probe laser) can be started at t_start=t1 to continue the simulation. The default is 0.0.
dt (float, optional) – time step of the output data. So in this case the ODE solver will decide at which time points to calculate the solution. The default is None.
t_eval (list or numpy array, optional) – If it desired to get the solution of the ode solver only at specific time points, the t_eval argument can be used to specify these points. If _eval is given, the dt argument is ignored. The default is [].
magn_remixing (bool, optional) – if True, the adjacent ground hyperfine levels are perfectly mixed by a magnetic field. The default is False.
magn_strength (float, optional) – measure of the magnetic field strength (i.e. the magnetic remixing matrix is multiplied by 10^magn_strength). Reasonable values are between 6 and 9. The default is 8.
position_dep (bool, optional) – determines whether to take the Gaussian intensity distribution of the laser beams into account. The default is False.
trajectory (bool, optional) – determines whether a trajectory of the molecule is calculated using simple equations of motion. This yields the additional time-dependent parameters v and r for the velocity and position. So, the force which is acting on the molecule changes the velocity which in turn can alter the Doppler shift. Further, the position_dep parameter determines if either a uniform unitensity or complex intensity distribution due to the Gaussian beam shapes is assumed through which the particle is propagated. The default is False.
verbose (bool, optional) – whether to print additional information like execution time or the scattered photon number. The default is True.
return_fun (function-type, optional) – if mp == True, the returned dictionary of this function determines the quantities which are save for every single parameter configuration. The default is None.
**kwargs (keyword arguments, optional) – other options of the solve_ivp scipy function can be specified (see homepage of scipy for further information).

Note

function creates attributes

N : solution of the time dependent populations N,
Nscatt : time dependent scattering number,
Nscattrate : time dependent scattering rate,
photons: totally scattered photons
args: input arguments of the call of this function
t : times at which the solution was calculated
v : calculated velocities of the molecule at times t (only given if trajectory == True)
r : calculated positions of the molecule at times t (only given if trajectory == True)

plot_all()[source]#

plot_N(figname=None, figsize=(12, 5), smallspacing=0)[source]#: plot populations of all levels over time.

plot_Nscatt(sum_over_ElSts=False)[source]#: plot the scattered photon number over time (integral of Nscattrate).

plot_Nscattrate(sum_over_ElSts=False)[source]#: plot the photon scattering rate over time (derivative of Nscatt).

plot_Nsum()[source]#: plot the population sum of all levels over time to ensure a small numerical deviation of the ODE solver.

plot_dt()[source]#: plot the time steps at which the populations are calculated. If no dt argument is given for the calulations they are chosen from the ODE solver.

plot_v()[source]#: plot the velocity over time for all three axes ‘x’,’y’, and’z’.

plot_r()[source]#: plot the position over time for all three axes ‘x’,’y’, and’z’.

plot_FFT(only_sum=True, start_time=0.0)[source]#

plot the fast Fourier transform (FFT) of the time-dependent populations.

Parameters:

only_sum (bool, optional) – if True the sum of the FFTs of all populations is plottet. Otherwise the distinct FFTs for all levels are shown. The default is True.
start_time (float between 0 and 1, optional) – starting time in units of the interaction time t_int at which the FFT is calculated. The default is 0.0.

calc_Rabi_freqs(position_dep=False)[source]#

Calculate the (angular) pure Rabi frequencies for each transition and each laser component (with 2*pi included).

Parameters:: position_dep (bool, optional) – Whether the intensity for the calculation is evaluated at a certain position within the Gaussian laser beam profiles (True) or at the maximum (False). The default is False.
Returns:: Angular Rabi frequencies for each combination of laser, excited states, and ground state.
Return type:: np.ndarray((lNum,uNum,pNum))

plot_F(figname=None, axes=['x', 'y', 'z'])[source]#: plot the Force over time for all three axes ‘x’,’y’, and’z’.

plot_spectrum(wavelengths=[], lasers=True, transitions=True, unit='MHz', exs=[], relative_to_wavelengths=False, axs=[], subplot_sep=200, laser_spectrum_kwargs={}, transitions_kwargs={})[source]#

Plot the spectrum of Laser objects and transition spectra with their respective intensities. This method cleverly combines plot_spectrum() and Levelsystem.plot_transition_spectrum() methods.

Parameters:

wavelengths (list, optional) – wavelengths that should be plotted within the range subplot_sep. By default all available laser wavelengths are used.
lasers (bool, optional) – Whether to include the laser spectrum. The default is True.
transitions (bool, optional) – Whether to include the transition spectrum. The default is True.
unit (str, optional) – Unit of the x-axis to be plotted. Can be one of ['GHz','MHz','kHz','Hz','Gamma']. Default is ‘MHz’.
exs (list(str), optional) – See exs in Levelsystem.plot_transition_spectrum().
relative_to_wavelengths (bool, optional) – Whether the x-axis should be plotted in absolute frequency units or relative to wavelengths.
axs (list of matplotlib.pyplot.axis objects, optional) – axis objects to put the plot(s) on. The default is [].
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 ElectronicState.Gamma. Default is 200.
laser_spectrum_kwargs (kwargs, optional) – Additional keyword arguments (see Lasersystem.plot_spectrum()). The default is dict().
transitions_kwargs (kwargs, optional) – Additional keyword arguments (see Levelsystem.plot_transition_spectrum()). The default is dict().

Returns:

axs – Axes of the subplot(s).

Return type:

list of matplotlib.pyplot.axis.

property hbarkG2#: Calculate \(\hbar k \Gamma /2\) using the wave vector defined in the laser system and natural lifetime defined in the first excited electronic state.

property F#

calculate the force over time.

Returns:: F – Force array for all <ntimes> time points and three axes ‘x’,’y’,’z’.
Return type:: np.ndarray, shape(3,ntimes)

calc_trajectory(F_profile, t_int=2e-05, t_start=0.0, dt=None, t_eval=None, verbose=True, force_axis=None, interpol_kind='linear', save_scipy_sols=False, **kwargs)[source]#: Calculate Monte Carlo simulations of classical particles which are propagated through a provided pre-calculated force profile to be used as interpolated function

calc_OBEs(t_int=2e-05, t_start=0.0, dt=None, t_eval=[], magn_remixing=False, freq_clip_TH=500, steadystate=False, position_dep=False, rounded=False, verbose=True, return_fun=<function return_fun_default>, **kwargs)[source]#

Calculate the time evolution of the single level populations with the optical Bloch equations.

Parameters:

t_int (float, optional) – interaction time in which the molecule is exposed to the lasers. The default is 20e-6.
t_start (float, optional) – starting time when the ode_solver starts the calculation. Useful for the situation when e.g. all cooling lasers are shut off at a specific time t1, so that a new calculation with another laser configuration (e.g. including only a probe laser) can be started at t_start=t1 to continue the simulation. The default is 0.0.
dt (float, optional) – time step of the output data. So in this case the ODE solver will decide at which time points to calculate the solution. If dt=’auto’, an appropriate time step is chosen by using the smallest Rabi frequency between a single transition and single laser component. The default is None.
t_eval (list or numpy array, optional) – If it desired to get the solution of the ode solver only at specific time points, the t_eval argument can be used to specify these points. If _eval is given, the dt argument is ignored. The default is [].
magn_remixing (bool, optional) – if True, the magnetic field, which is defined in the instance Bfield contained in this class, is considered in the calculation. Otherwise, the magnetic field is set to zero. The default is False.
freq_clip_TH (float or string, optional) – determines the threshold frequency at which the coupling of a single transition detuned by a frequency from a specific laser component is neglected. If a float is provided, only the transitions with detunings smaller than freq_clip_TH times Gamma[0] are driven by the light field. If freq_clip_TH == ‘auto’, the threshold frequencies for all transitions are chosen seperately by considering the transition strengths and intensities of each laser component. The default is 500.
steadystate (bool, optional) – determines whether the equations are propagated until a steady state or periodic quasi-steady state is reached. The dictionary steadystate of this class specifies the steady state conditions. The default is False.
position_dep (bool, optional) – determines whether to take position of the particle in an Gaussian intensity distribution of the laser beams into account. The default is False.
rounded (float, optional) – if specified, all frequencies and velocities are rounded to the frequency rounded in units of max(Gamma). The default is False.
verbose (bool, optional) – whether to print additional information like execution time or the scattered photon number. The default is True.
return_fun (function-type, optional) – if mp == True, the returned dictionary of this function determines the quantities which are save for every single parameter configuration. The default is None.
**kwargs (keyword arguments, optional) – other options of the solve_ivp scipy function can be specified (see homepage of scipy for further information).

Note

function creates attributes

N : solution of the time dependent populations N,
Nscatt : time dependent scattering number,
Nscattrate : time dependent scattering rate,
photons: totally scattered photons
args: input arguments of the call of this function
t : times at which the solution was calculated

reset_N0()[source]#: Reset (last created) initial population self.N0 and initial populations for all electronic states

initialize_N0(return_densitymatrix=False, random=False)[source]#

Initialize initial populations as a starting point for the OBEs or rate equations using pre-defined population attribute N0 of the electronic states ElectronicState.

Parameters:

return_densitymatrix (bool, optional) – Whether the populations should be transformed into density matrix or one-dimensional population array. The default is False.
random (bool, optional) – Whether the popultions are sampled from a random distirbution. The default is False.

Returns:

N0mat – density matrix with populations on the diagonal.

Return type:

numpy.ndarray

get_N(return_sum=True, **QuNrs)[source]#

Retrieve the time-dependent populations as results after calculating the dynamics. Can be used to either obtain the populations of all individual levels or to conveniently combine the populations for only a subset of levels with specific Quantum numbers.

Parameters:

return_sum (bool, optional) – Whether to sum up of all levels. The default is True.
**QuNrs (kwargs) – Keyword arguments as Quantum numbers can be provided for only a subset of levels with specific Quantum numbers, e.g. v=0. If empty, all levels are considered. If only a specific ground or excited electronic state should be included, add e.g. gs=’X’ or exs=’A’ as a first QuNr keyword.

Returns:

Time-dependent population(s).

Return type:

np.ndarrays

get_Nscattrate(sum_over_ElSts=False)[source]#

Calculate time dependent scattering rate.

Parameters:: sum_over_ElSts (bool, optional) – Whether to sum over multiple electronic excited states. The default is False.
Returns:: Time dependent scattering rate.
Return type:: numpy.ndarray

get_Nscatt(sum_over_ElSts=False)[source]#

Calculate time dependent scatterd photon number.

Parameters:: sum_over_ElSts (bool, optional) – Whether to sum over multiple electronic excited states. The default is False.
Returns:: Time dependent scattered photon number.
Return type:: numpy.ndarray

get_photons(sum_over_ElSts=False)[source]#

Calculate totally scattered photon number.

Parameters:: sum_over_ElSts (bool, optional) – Whether to sum over multiple electronic excited states. The default is False.
Returns:: Totally scattered photon number.
Return type:: numpy.ndarray

property Nscattrate#: time dependent scattering rate

property Nscatt#: time dependent scattering number

property photons#: totally scattered photons

check_config(raise_Error=False)[source]#: Check System configuration for simulating internal dynamics.

set_v0(v0=[0, 0, 0], direction=[])[source]#

Set initial velocity of the particle(s).

Parameters:

v0 (list or np.ndarray, optional) – Velocity array. Can be either a one-dimensional array with three entries for the x, y and z component, a two dimensional array where the first dimension corresponds to different particles’ velocities, or a one dimensional array with absolute velocity values while the argument direction defines the direction. The default is [0,0,0].
direction (str, list or np.ndarray, optional) – Direction of the absolute velocity values defined as the argument v0. Can be either a str (x,y,z) or list / array of length 3. The default is [].

Returns:

velocity array (1 or 2-dimensional with the shape (number of particles, 3) in cartesian coordinates.

Return type:

np.ndarray

set_r0(r0=[0, 0, 0], direction=[])[source]#

Set initial position of the particle(s).

Parameters:

r0 (list or numpy.ndarray, optional) – Position array. Can be either a one-dimensional array with three entries for the x, y and z component, a two dimensional array where the first dimension corresponds to different particles’ positions, or a one dimensional array with absolute position values while the argument direction defines the direction. The default is [0,0,0].
direction (str, list or numpy.ndarray, optional) – Direction of the absolute position values defined as the argument r0. Can be either a str (x,y,z) or list / array of length 3. The default is [].

Returns:

position array (1 or 2-dimensional with the shape (number of particles, 3) in cartesian coordinates.

Return type:

numpy.ndarray

property v0#: initial velocity of the particle

property r0#: dictionary for parameters specifying the steady state conditions.

draw_levels(GrSts=None, ExSts=None, branratios=True, lasers=True, QuNrs_sep=[], br_fun='identity', br_TH=0.01, freq_clip_TH='auto', cmap='viridis', yaxis_unit='MHz')[source]#

Draw all levels of certain Electronic states sorted by certain Qunatum numbers. Additionally, the branching ratios and the transitions addressed by the lasers can be added.

Parameters:

GrSts (list of str, optional) – list of labels of ground electronic states to be displayed. The default is None which corresponds to all ground states.
ExSts (list of str, optional) – list of labels of excited electronic states to be displayed. The default is None which corresponds to all excited states.
branratios (bool, optional) – Whether to show the branching ratios. The default is True.
lasers (bool, optional) – Whether to show the transitions addressed by the lasers. By default it is set to True when lasers are defined.
QuNrs_sep (list of str or tuple of two lists of str, optional) – Quantum numbers for separating all levels into subplots. For example the levels can be grouped into subplots by the vibrational Quantum number, i.e. [‘v’] or ([‘v’],[‘v’]) for ex. and gr. states.
br_fun (str or callable, optional) – Function to be applied onto the branching ratios. Can be either ‘identity’, ‘log10’, ‘sqrt’, or a custom defined function. The default is ‘identity’.
br_TH (float, optional) – Threshold for the branching ratios to be shown. The default is 0.01.
freq_clip_TH (TYPE, optional) – Same argument as in OBE’s calculation method ‘calc_OBEs(). The default is ‘auto’.
cmap (str, optional) – Colormap to be applied to the branching ratios. The default is ‘viridis’.
yaxis_unit (str or float, optional) – Unit of the y-axis. Can be either ‘MHz’,’1/cm’, or ‘Gamma’ for the natural linewidth. Alternatively, an arbitrary unit (in MHz) can be given as float. Default is ‘MHz’.

MoleCool.System.System

Contents

MoleCool.System.System#