MoleCool.tools

This module contains all different kinds of tools to be used in the other main modules.

Functions

FWHM2sigma(FWHM)	Convert full width at half maximum (FWHM) to standard deviation of a Gaussian (sigma).
Ttov(T[, mass])	function to convert a temperatur in K to a velocity v in m/s.
auto_subplots(nplots[, ratio, axs, xlabel, ...])	Generate rows and cols for a subplot layout aiming for a given rows/cols ratio (default 2:1).
gaussian(x[, a, x0, std, y_off])	Standard Gaussian function \(a \exp(-0.5(x-x_0)^2/std^2)+y_{off}\).
get_constants_dict([name])	Load the level system constants / properties from a .json file and return it as a dictionary.
get_results(fname[, Z_keys, XY_keys, ...])	Extract Results_OBEs_rateeqs results from an .pkl file as observables of a high-dimensional parameter space in a certain order of parameters and their values as numpy arrays.
make_axes_invisible(axes[, xaxis, yaxis, ...])	For advanced plotting: This function makes certain properties of an matplotlib axes object invisible.
multiproc(obj, kwargs)
open_object(filename)	Open or load a saved python object from a .pkl file.
plot_results(fname[, Z_keys, XY_data_fmt, ...])	plot results for calculating one or multiple observables in a high-dimensional parameter space.
return_fun_default(system)	Default function defining which values are returned after an evaluation of calc_OBEs() or calc_rateeqs().
save_object(obj[, filename])	Save any python object as a .pkl pickle file.
sigma2FWHM(sigma)	Convert standard deviation of a Gaussian (sigma) to full width at half maximum (FWHM).
vtoT(v[, mass])	function to convert a velocity v in m/s to a temperatur in K.

Classes

Results_OBEs_rateeqs(vals, iters)

Create new instance of Results_OBEs_rateeqs(vals, iters)

class MoleCool.tools.Results_OBEs_rateeqs(vals, iters)

Bases: tuple

Create new instance of Results_OBEs_rateeqs(vals, iters)

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

iters

Alias for field number 1

vals

Alias for field number 0

MoleCool.tools.save_object(obj, filename=None)

Save any python object as a .pkl pickle file. This is especially suitable for saving the MoleCool.System.System object with all its attributes.

Parameters:

• obj (object) – The object you want to save.

• filename (str, optional) – the filename to save the data. The extension ‘.pkl’ will be added for saving the file. If no filename is provided, it is set to the attribute description of the object and if the object does not have this attribute, the filename is set to the name of the class belonging to the object.

MoleCool.tools.open_object(filename)

Open or load a saved python object from a .pkl file.

Parameters:

filename (str) – filename without the ‘.pkl’ extension.

Returns:

output

Return type:

Object

MoleCool.tools.return_fun_default(system)

Default function defining which values are returned after an evaluation of calc_OBEs() or calc_rateeqs(). This is especially important to collect important quantities when simulating these internal dynamics for many times configurations using multiprocessing module.

Parameters:

system (MoleCool.System.System) – instance of System after simulating the internal dynamics.

Returns:

dic – dictionary with important quantities, such as

• execution time exectime as system.exectime

• scattered photons photons as system.photons

• success message success as system.success

• mean force F

• mean excited state population Ne

Return type:

dict

MoleCool.tools.get_constants_dict(name='')

Load the level system constants / properties from a .json file and return it as a dictionary.

Parameters:

name (str, optional) – filename of the json file without the .json. The default is ‘’.

Returns:

dictionary with all constants / properties.

Return type:

dict

MoleCool.tools.make_axes_invisible(axes, xaxis=False, yaxis=False, invisible_spines=['top', 'bottom', 'left', 'right'])

For advanced plotting: This function makes certain properties of an matplotlib axes object invisible. By default everything of a new created axes object is invisible.

Parameters:

• axes (matplotlib.axes.Axes object or iterable of objects) – axes for which properties should be made inivisible.

• xaxis (bool, optional) – If xaxis is made invisible. The default is False.

• yaxis (bool, optional) – If yaxis is made invisible. The default is False.

• invisible_spines (list of strings, optional) – spines to be made invisible. The default is [‘top’,’bottom’,’left’,’right’].

MoleCool.tools.auto_subplots(nplots, ratio=2.0, axs=[], xlabel='', ylabel='', **subplots_kwargs)

Generate rows and cols for a subplot layout aiming for a given rows/cols ratio (default 2:1).

MoleCool.tools.multiproc(obj, kwargs)

MoleCool.tools.vtoT(v, mass=157)

function to convert a velocity v in m/s to a temperatur in K.

MoleCool.tools.Ttov(T, mass=157)

function to convert a temperatur in K to a velocity v in m/s.

MoleCool.tools.gaussian(x, a=1.0, x0=0.0, std=1.0, y_off=0)

Standard Gaussian function \(a \exp(-0.5(x-x_0)^2/std^2)+y_{off}\).

MoleCool.tools.FWHM2sigma(FWHM)

Convert full width at half maximum (FWHM) to standard deviation of a Gaussian (sigma).

MoleCool.tools.sigma2FWHM(sigma)

Convert standard deviation of a Gaussian (sigma) to full width at half maximum (FWHM).

MoleCool.tools.get_results(fname, Z_keys='F', XY_keys=[], Z_data_fmt={}, XY_data_fmt={}, XYY_inds=[], add_v0=False, add_flip_v=False, add_I0=False, scale_F='N')

Extract Results_OBEs_rateeqs results from an .pkl file as observables of a high-dimensional parameter space in a certain order of parameters and their values as numpy arrays. Optionally, one can add e.g. zero force values, manually.

Parameters:

• fname (str or System) – filename where the instance of System is saved or the instance itself.

• Z_keys (str, optional) – Observable calculated in the results. The default is ‘F’.

• XY_keys (list of str, optional) – Parameters that the results are dependent on, e.g. ['v0','I']. The default is [].

• Z_data_fmt (dict of func, optional) – Dictionary with the observables as keys and functions as their respective values. The argument of these functions is the individual calculated value from the result Results_OBEs_rateeqs object for each parameter combination. When the calculated value is e.g. a force array np.array([0,0,2.4]), then only the ‘z’ component can be exctracted using {'F': lambda x: x[2]}. The default is {}.

• XY_data_fmt (dict of func, optional) – Dictionary with iteration parameters as keys and functions as their respective values. These functions take the loaded system as argument to return the actual XY data of the iteration parameters to be plotted, e.g. {'strength': lambda system: system.Bfield.strength}. The default is {} and includes e.g. {'I': lambda x: x.lasers.I_sum, 'v0': lambda x: x.v0[:,2]}.

• XYY_inds (list of inds, optional) – list of indices to choose values of further parameters included in the results dataset for more than 3 dimensions. The default is [].

• add_v0 (bool, optional) – Manually adding velocity v=0 and zero force. The default is True.

• add_flip_v (bool, optional) – add a flip velocity axis to get the full range. The default is True.

• add_I0 (bool, optional) – adding intensity I=0 where the force is zero. The default is True.

• scale_F (str, optional) – scale F to either ‘N’ or ‘hbar*k*Gamma/2’. Do nothing if scale_F=='', The default is ‘N’.

Returns:

• Z (np.ndarray) – observables or results as shape of both axes of XY_keys.

• XY (dict) – names and data of X axis and Y axis as str and np.ndarray (length of both axis together equal the shape of Z).

• XYY (dict) – key and single values of the parameters of further parameters included in the results dataset for more than 3 dimensions.

MoleCool.tools.plot_results(fname, Z_keys=['F'], XY_data_fmt={}, scale_F='hbar*k*Gamma/2', XY_labels={}, Z_labels={}, cmap='RdBu', levels=12, Xlim=[], Ylim=[], Zlim={}, Z_percent=['F', 'Ne'], axs=[], figname='', savefig=False, **kwargs)

plot results for calculating one or multiple observables in a high-dimensional parameter space.

Parameters:

• fname (str or System) – see function get_results.

• Z_keys (str or list of str, optional) – names of calculated observables to be plotted (see function get_results). The default is [‘F’].

• XY_data_fmt (dict, optional) – see function get_results. The default is {}.

• XY_labels (dict, optional) – dictionary to convert the names of certain parameters to other more suitable axis labels. The default is {}.

• Z_labels (dict, optional) – dictionary to convert the names of the observables to other more suitable axis labels. The default is {}.

• cmap (str, optional) – color map from matplotlib. The default is ‘RdBu’.

• levels (int, optional) – number of color levels. The default is 12.

• Xlim (tuple, optional) – lower and upper limit. The default is [].

• Ylim (tuple, optional) – lower and upper limit. The default is [].

• Zlim (tuple, optional) – lower and upper limit. The default is {}.

• Z_percent (list, optional) – list with the names of observables to be plotted in percent. The default is [‘F’,’Ne’].

• axs (list of matplotlib.pyplot.axis objects, optional) – axis/axes to put the plot(s) on. The default is [].

• figname (str, optional) – name of the figure. The default is ‘’.

• savefig (bool or str, optional) – if True the figure is saved. If str, the figure is saved using the provided string. The default is False.

• **kwargs (keyword arguments) – keyword arguments for the function get_results.

Modules

ODEs	This module contains the definitions of all ordinary differential equations (ODEs) which are used in scipy's scipy.integrate.solve_ivp(), e.g. within the rate model and optical Bloch equations (see calc_rateeqs() and calc_OBEs()).
dict2DF	This module contains several functions as tools for converting the .json files with all the specific constants of a certain atom, molecule into pandas.DataFrames.
diststraj	This Module contains different type of functions and classes, e.g. to calculate simple linear trajectories through multiple apertures and to evaluate trajectories as solutions of the Monte Carlo simulations.