diatom package

Submodules

diatom.calculate module

diatom.calculate.dipole(Nmax, I1, I2, d, M)

Generates the induced dipole moment operator for a Rigid rotor. Expanded to cover state vectors in the uncoupled hyperfine basis.

Parameters

  • Nmax (int) –

  • I1 (float) –

  • I2 (float) –

  • d (float) –

  • M (float) –

Returns

Dmat (numpy.ndarray) - dipole matrix

diatom.calculate.electric_moment(States, Nmax, Consts)

Returns the electric dipole moments of each eigenstate

Parameters

  • States (numpy.ndarray) – matrix for eigenstates of problem output from numpy.linalg.eig

  • Nmax (int) – Maximum rotational quantum number in original calculations

  • Consts – Dictionary of constants for the molecular to be calculated

diatom.calculate.label_states_F_MF(states, Nmax, I1, I2, locs=None)

Label states by F,MF

This function returns two lists: the input states labelled by F and MF in the order that they are provided. The returned numbers will only be good if the state is well -represented in the decoupled basis.

Optionally can return the quantum numbers for a subset if the locs kwarg is provided. Each element in the list locs corresponds to the index for the states to label.

Parameters

  • States (Numpy.ndarray) –

  • Nmax (int) –

  • I1 (float) –

  • I2 (float) –

kwargs:

locs (list of ints) - list of indices of states to label

Returns

Flabels,MFlabels (list of ints) - list of values of F,MF

diatom.calculate.label_states_I_MI(states, Nmax, I1, I2, locs=None)

Label states by I,MI

This function returns two lists: the input states labelled by I and MI in the order that they are provided. The returned numbers will only be good if the state is well -represented in the decoupled basis.

Optionally can return the quantum numbers for a subset if the locs kwarg is provided. Each element in the list locs corresponds to the index for the states to label.

Parameters

  • States (Numpy.ndarray) –

  • Nmax (int) –

  • I1 (float) –

  • I2 (float) –

kwargs:

locs (list of ints) - list of indices of states to label

Returns

Ilabels,MIlabels (list of ints) - list of values of I,MI

diatom.calculate.label_states_N_MN(states, Nmax, I1, I2, locs=None)

Label states by N,MN

This function returns two lists: the input states labelled by N and MN in the order that they are provided. The returned numbers will only be good if the state is well -represented in the decoupled basis.

Optionally can return the quantum numbers for a subset if the locs kwarg is provided. Each element in the list locs corresponds to the index for the states to label.

Parameters

  • States (Numpy.ndarray) –

  • Nmax (int) –

  • I1 (float) –

  • I2 (float) –

kwargs:

locs (list of ints) - list of indices of states to label

Returns

Nlabels,MNlabels (list of ints) - list of values of N,MN

diatom.calculate.magnetic_moment(States, Nmax, Consts)

Returns the magnetic moments of each eigenstate

Parameters

  • States (numpy.ndarray) – matrix for eigenstates of problem output from numpy.linalg.eig

  • Nmax (int) – Maximum rotational quantum number in original calculations

  • Consts – Dictionary of constants for the molecular to be calculated

diatom.calculate.solve_quadratic(a, b, c)

Solve a quadratic equation

for a*x^2+b*x+c=0 this is a simple function to solve the quadratic formula for x. returns the most positive value of x supported.

Parameters

  • a (floats) –

  • b (floats) –

  • c (floats) –

Returns

x (float) - maximum value of x supported by equation

diatom.calculate.sort_by_state(energies, states, Nmax, Consts)

Sort states by (N, M_F)_k where k is an index labelling states of a given N, MF in ascending energy. k is determined for the last element in the array, this is usually the highest value of the varied parameter.

Parameters

  • energies (numpy.ndarray) – eigenvalues output from numpy.linalg.eigh

  • states (numpy.ndarray) – eigenstates output from numpy.linalg.eigh

  • Nmax – Maximum rotational quantum number in original calculations

  • Consts – Molecular constants used in original calculations

Output:

energies_sorted, states_sorted: eigenenergies and eigenvalues sorted by the ordering of states given in labels. labels: labels of the states in order

diatom.calculate.sort_smooth(energy, states)

Sort states to remove false avoided crossings.

This is a function to ensure that all eigenstates plotted change adiabatically, it does this by assuming that step to step the eigenstates should vary by only a small amount (i.e. that the step size is fine) and arranging states to maximise the overlap one step to the next.

Parameters

  • Energy (numpy.ndarray) – numpy.ndarray containing the eigenergies, as from numpy.linalg.eig

  • States (numpy.ndarray) – numpy.ndarray containing the states, in the same order as Energy

Returns

numpy.ndarray containing the eigenergies, as from numpy.linalg.eig States (numpy.ndarray): numpy.ndarray containing the states, in the same order as Energy E[x,i] -> States[x,:,i]

Return type

Energy (numpy.ndarray)

diatom.calculate.transition_dipole_moment(Nmax, I1, I2, M, states, gs, locs=None)

calculate TDM between gs and States

Function to calculate the Transition Dipole Moment between a state gs and a range of states. Returns the TDM in units of the permanent dipole moment (d0).

Parameters

  • Nmax (int) – Maximum rotational quantum number in original calculations

  • I1 (float) – nuclear spin quantum numbers

  • I2 (float) – nuclear spin quantum numbers

  • M (float) – Helicity of Transition, -1 = S+, 0 = Pi, +1 = S-

  • States (numpy.ndarray) – matrix for eigenstates of problem output from numpy.linalg.eig

  • gs (int) – index of ground state.

kwargs:
locs (list of ints): optional argument to calculate for subset of States, should be an

array-like.

Outputs:

TDM(list of floats) - transition dipole moment between gs and States

diatom.hamiltonian module

diatom.hamiltonian.DebyeSI = 3.33564e-30

Conversion factor from debyes to J/V/m

diatom.hamiltonian.T2_C(Nmax, I1, I2)

The irreducible spherical tensors for the spherical harmonics in the rotational basis.

Parameters

  • Nmax (int) – Maximum rotational state to include

  • I1 (float) – The nuclear spins of nucleus 1 and 2

  • I2 (float) – The nuclear spins of nucleus 1 and 2

Returns

spherical tensor T^2(C). Each element is a spherical operator

Return type

T (list of numpy.ndarray)

diatom.hamiltonian.ac_aniso(Nmax, a2, Beta, I1, I2)

Calculate anisotropic ac stark shift.

Generates the effect of the anisotropic AC Stark shift for a rigid-rotor like molecule.

This term is calculated differently to all of the others in this work and is based off Jesus Aldegunde’s FORTRAN 77 code. It iterates over N,MN,N’,MN’ to build a matrix without hyperfine structure then uses kronecker products to expand it into all of the hyperfine states.

Parameters

  • Nmax (int) –

  • a2 (float) –

  • Beta (float) –

  • I1 (float) –

  • I2 (float) –

Returns

Hamiltonian in joules

Return type

H (numpy.ndarray)

diatom.hamiltonian.ac_iso(Nmax, a0, I1, I2)

Calculate isotropic Stark shifts

Generates the effect of the isotropic AC Stark shift for a rigid-rotor like molecule.

This term is calculated differently to all of the others in this work and is based off Jesus Aldegunde’s FORTRAN 77 code. It iterates over N,MN,N’,MN’ to build a matrix without hyperfine structure then uses kronecker products to expand it into all of the hyperfine states.

Parameters

  • Nmax (int) - maximum rotational quantum number to calculate (int) –

  • a0 (float) –

  • I1 (float) –

  • I2 (float) –

Returns

H (numpy.ndarray) - isotropic AC Stark Hamiltonian

diatom.hamiltonian.build_hamiltonians(Nmax, constants, zeeman=False, Edc=False, ac=False)

Return the hyperfine hamiltonian.

This function builds the hamiltonian matrices for evaluation so that the user doesn’t have to rebuild them every time and we can benefit from numpy’s ability to do distributed multiplication.

Parameters

  • Nmax (int) –

  • I1_mag (float) –

  • I2_mag (float) –

  • Constants (Dictionary) –

  • zeeman (Boolean) –

  • EDC (Boolean) –

  • AC (Boolean) –

  • required (can save significant time on calculations where DC and AC fields are not) –

  • loops (due to nested for) –

Returns

Each of the terms in the Hamiltonian.

Return type

H0,Hz,HDC,HAC (numpy.ndarray)

diatom.hamiltonian.dc(Nmax, d0, I1, I2)

calculate HDC for a diatomic molecule

Generates the effect of the dc Stark shift for a rigid-rotor like molecule.

This term is calculated differently to all of the others in this work and is based off Jesus Aldegunde’s FORTRAN 77 code. It iterates over N,MN,N’,MN’ to build a matrix without hyperfine structure then uses kronecker products to expand it into all of the hyperfine states.

Parameters

  • Nmax (int) –

  • d0 (float) –

  • I1 (float) –

  • I2 (float) –

Returns

H (numpy.ndarray) - DC Stark Hamiltonian in joules

diatom.hamiltonian.electric_gradient(Nmax, I1, I2)

Calculate electric field gradient at the nucleus.

spherical tensor for the electric field gradient at nucleus i. Depends on the rotational states not the nuclear spin states. Returns a spherical tensor.

Parameters

  • Nmax (int) –

  • I1 (float) –

  • I2 (float) –

Returns

T (list of numpy.ndarray) - length-5 list of numpy.ndarrays

diatom.hamiltonian.generate_vecs(Nmax, I1, I2)

Build N, I1, I2 angular momentum vectors

Generate the vectors of the angular momentum operators which we need to be able to produce the Hamiltonian

Parameters

  • Nmax (float) – maximum rotational level to include in calculations

  • I1 (float) – Nuclear spins of nuclei 1 and 2

  • I2 (float) – Nuclear spins of nuclei 1 and 2

Returns

length-3 list of (2Nmax+1)*(2I1+1)*(2I2+1) square numpy arrays

Return type

N_vec,I1_vec,I2_vec (list of numpy.ndarray)

diatom.hamiltonian.hyperfine_ham(Nmax, I1_mag, I2_mag, consts)

Calculate the field-free Hyperfine hamiltonian

Wrapper to call all of the functions that are appropriate for the singlet-sigma hyperfine hamiltonian.

Parameters

  • Nmax (int) –

  • I1_mag (float) –

  • I2_mag (float) –

  • Consts (Dictionary) – Dict of molecular constants

Returns

Hamiltonian for the hyperfine structure in joules

Return type

H0

diatom.hamiltonian.makeT2(I1, I2)

Construct the spherical tensor T2 from two cartesian vectors of operators.

Parameters

  • I1 (list of numpy.ndarray) – the output of makevecs

  • I2 (list of numpy.ndarray) – the output of makevecs

Returns

T (list of numpy.ndarray) - T^2(I1,I2) length-5 list of spherical angular momentum operators

diatom.hamiltonian.quad_moment(Nmax, I1, I2)

Calculate the nuclear electric quadrupole moments of nuclei 1 and 2.

spherical tensor for the nuclear quadrupole moment of both nuclei. Depends on the nuclear spin states not the rotational states. :param Nmax: :type Nmax: int :param I1: :type I1: float :param I2: :type I2: float

Returns

T (list of numpy.ndarray) - length-5 list of numpy.ndarrays

diatom.hamiltonian.quadrupole(Q, I1, I2, Nmax)

Calculate Hquad, the nuclear electric quadrupole interaction energy

Calculates the Quadrupole terms for the hyperfine Hamiltonian using spherical tensor algebra. Requires the nuclear quadrupole moments and electric field gradients.

Parameters

  • Q (tuple of floats) –

  • Nmax (int) –

  • I1 (float) –

  • I2 (float) –

Returns

Hquad (numpy.ndarray) - numpy array with shape (2I1+1)*(2I2+1)*sum([(2*x+1) for x in range(Nmax+1)])

diatom.hamiltonian.raising_operator(j)

Creates the angular momentum raising operator for j

In the j,mj basis running from max(mj) to min (mj) creates a matrix that represents the operator j+|j,mj> = |j,mj+1>

Parameters

j (float) – value of the angular momentum

Returns

Array representing the operator J+, has shape ((2j+1),(2j+1))

Return type

J+ (numpy.ndarray)

diatom.hamiltonian.rotational(N, Brot, Drot)

Rigid rotor rotational structure

Generates the hyperfine-free hamiltonian for the rotational levels of a rigid-rotor like molecule. Includes the centrifugal distortion term.

Matrix is returned in the N,MN basis with MN going from maximum to minimum.

Parameters

  • N (list of numpy.ndarray) –

  • Brot (float) –

  • Drot (float) –

Returns

Hrot (numpy.ndarray) - hamiltonian for rotation in the N,MN basis

diatom.hamiltonian.scalar_nuclear(Ci, J1, J2)

Calculate the scalar spin-spin interaction term

Returns the scalar spin-spin term of the HF Hamiltonian

Parameters

  • Ci (float) –

  • J1 (list of numpy.ndarray) –

  • J2 (list of numpy.ndarray) –

Returns

H (numpy.ndarray) - Hamiltonian for spin-spin interaction

diatom.hamiltonian.tensor_dot(T1, T2)

Product of two rank-2 spherical tensors T1, T2

A function to calculate the scalar product of two spherical tensors T1 and T2 are lists or numpy arrays that represent the spherical tensors lists are indexed from lowest m to highests

Parameters

  • T1 (list of numpy.ndarray) –

  • T2 (list of numpy.ndarray) –

Returns

X (numpy.ndarray) - scalar product of spherical tensors

diatom.hamiltonian.tensor_nuclear(C3, I1, I2, Nmax)

Calculate the tensor spin-spin interaction.

This function is to calculate the tensor spin-spin interaction. This version uses spherical tensors to calculate the correct off-diagonal behaviour.

Parameters

  • C3 (float) –

  • I1 (float) –

  • I2 (float) –

  • Nmax (int) –

Returns

Hss (numpy.ndarray) - Hamiltonian for tensor spin-spin interaction

diatom.hamiltonian.vector_dot(x, y)

Cartesian dot product of two vectors of operators x,y

A function that can do the dot product of a vector of matrices default behaviour of numpy.dot does the elementwise product of the matrices.

Parameters

  • x (numpy.ndarray) – length-3 Vectors of Angular momentum operators, each element is a JxJ arrays

  • y (numpy.ndarray) – length-3 Vectors of Angular momentum operators, each element is a JxJ arrays

Returns

result of the dot product, JxJ array

Return type

Z (numpy.ndarray)

diatom.hamiltonian.wigner_D(l, m, alpha, beta, gamma)

The Wigner D matrix with labels l and m.

Calculates the Wigner D Matrix for the given Alpha,beta,gamma in radians. The wigner-D matrices represent rotations of angular momentum operators. The indices l and m determine the value of the matrix. The second index (m’) is always zero.

The input angles are the x-z-x euler angles

Parameters

  • l (int) – order of wigner Matrix

  • m (float) – first index of Wigner Matrix

  • alpha (float) – x,z,x Euler angles in radians

  • beta (float) – x,z,x Euler angles in radians

  • gamma (float) – x,z,x Euler angles in radians

Returns

Value of the wigner-D matrix

Return type

D (float)

diatom.hamiltonian.x_operator(J)

operator for X component of J

Creates the Cartesian operator Jx for a given J

Parameters

J (float) – Magnitude of angular momentum

Returns

2J+1 square numpy array

Return type

Jx (numpy.ndarray)

diatom.hamiltonian.y_operator(J)

operator for Y component of J

Creates the Cartesian operator Jy for a given J

Parameters

J (float) – Magnitude of angular momentum

Returns

2J+1 square numpy array

Return type

Jy (numpy.ndarray)

diatom.hamiltonian.z_operator(J)

operator for Z component of J

Creates the Cartesian operator Jz for a given J. This is diagonal in the j,mj basis such that jz|j,mj> = mj|j,mj>

Parameters

J (float) – Magnitude of angular momentum

Returns

2J+1 square numpy array

Return type

Jz (numpy.ndarray)

diatom.hamiltonian.zeeman(Cz, J)

Calculate the Zeeman effect for a magnetic field along z

Linear Zeeman shift, fixed magnetic field along z so only need the last component of the angular momentum vector.

Parameters

  • Cz (float) –

  • J (list of numpy.ndarray) –

Returns

Hz (numpy.ndarray) - Zeeman Hamiltonian

diatom.hamiltonian.zeeman_ham(Nmax, I1_mag, I2_mag, consts)

Assembles the Zeeman term and generates operator vectors

Calculates the Zeeman effect for a magnetic field on a singlet-sigma molecule. There is no electronic term and the magnetic field is fixed to be along the z axis.

Parameters

  • Nmax (int) –

  • I1_mag (float) –

  • I2_mag (float) –

  • Consts (Dictionary) – Dict of molecular constants

Returns

Hamiltonian for the zeeman effect

Return type

Hz (numpy.ndarray)

diatom.plotting module

diatom.plotting.colorline(x, y, z=None, cmap=<matplotlib.colors.LinearSegmentedColormap object>, norm=<matplotlib.colors.Normalize object>, linewidth=3, alpha=1.0, legend=False, ax=None)

Plot a line shaded by an extra value.

Plot a colored line with coordinates x and y Optionally specify colors in the array z Optionally specify a colormap, a norm function and a line width

Parameters

  • x (list-like) – x and y coordinates to plot

  • y (list-like) – x and y coordinates to plot

kwargs:

z (list): Optional third parameter to colour lines by cmap (matplotlib.cmap): colour mapping for z norm (): Normalisation function for mapping z values to colours linewidth (float): width of plotted lines (default =3) alpha (float): value of alpha channel (default = 1) legend (Bool): display a legend (default = False) ax (matplotlib.pyplot.axes): axis object to plot on

Returns

lc (Collection) - collection of lines

diatom.plotting.export_energy(fname, energy, fields=None, labels=None, headers=None, dp=6, format=None)

Export Energies in spreadsheet format.

This exports the energy of the states for a calculation in a human-readable spreadsheet format.

Currently only saves .csv files.

Parameters

  • fname (string) –

  • Energy (numpy.ndarray) –

Kwargs:

Fields (numpy.ndarray) - Field variables used in calculation labels (numpy.ndarray) - labels for states headers (list of strings) - header for each of the labels in labels dp (float) - number of decimal places to use for output (default =6) format (list of strings) - list of formats passed to numpy.savetxt for labels

diatom.plotting.export_state_comp(fname, Nmax, I1, I2, states, labels=None, headers=None, dp=6, format=None)

function to export state composition in a human-readable format along the first row are optional headers and the labels for the basis States in the uncoupled basis.

the user can supply optional labels for the states in a (x,y) list or array where y is the number of states and x is the number of unique labels, for instance a list of the N quantum number for each state.

they can also (optionally) supply a (x,1) list to include custom headers in the first row. If the labels kwarg is included and headers is not, then non-descriptive labels are used to ensure correct output.

by default the output is given to 6 decimal places (truncated) this can be adjusted using the kwarg dp

Parameters

  • fname (string) – the filename and path to save the output file

  • Nmax (int/float) – the maximum value of N used in the calculation

  • I1 (float) – the nuclear spin quantum numbers of nucleus 1 and 2

  • I2 (float) – the nuclear spin quantum numbers of nucleus 1 and 2

  • States (N,M) – eigenstates stored in an (N,M) ndarray, N is the number of eigenstates. M is the number of basis states.

kwargs:

labels (N,X) ndarray : ndarray containing X labels for each of the N states headers (X) ndarray-like : Ndarray-like containing descriptions of the labels dp (int) : number of decimal places to output the file to [default = 6] format (list) : list of strings for formatting the headers. Defaults to 1 dp.

diatom.plotting.make_segments(x, y)

segment x and y points

Create list of line segments from x and y coordinates, in the correct format for LineCollection: an array of the form numlines x (points per line) x 2 (x and y) array

Parameters

  • x (numpy.ndarray -like) –

  • y (numpy.ndarray -like) –

Returns

segments (numpy.ndarray) - array of numlines by points per line by 2

diatom.plotting.transition_plot(energies, states, gs, Nmax, I1, I2, TDMs=None, pm=1, Offset=0, fig=<Figure size 640x480 with 0 Axes>, log=False, minf=None, maxf=None, prefactor=0.001, col=None)

Create a TDM plot

this function plots a series of energy levels and their transition dipole moments from a given ground state. In this version a lot of the plotting style is fixed.

Parameters

  • energies (numpy.ndarray) –

  • states (numpy.ndarray) – ,i]

  • gs (int) –

  • Nmax (int) –

  • I1 (float) –

  • I2 (float) –

Kwargs:

TDMs (list of numpy.ndarray) - optional precomputed transition dipole moments in [sigma-,pi,sigma+] order pm (float) - flag for if the transition increases or decreases N (default = 1) Offset (float) - yaxis offset (default = 0) fig (matplotlib.pyplot.figure) - figure object to draw on log (bool) - use logarithmic scaling for TDM plots minf (float) - minimum frequency to show maxf (float) - maximum frequency to show prefactor (float) - scaling factor for all energies col (list) - list of colours for lines (must be at least length 3 )

Module contents