Operators

Operators#

class diatomic.operators.HalfInt(*, of)#: Container to encapsulate half-integer spin & projection lengths. Values will be automatically downcast to an integer if the numerator of <of>/2 is an even number as soon as possible, even upon initialisation.

diatomic.operators.T2_C(Nmax, I1, I2, *, Nmin=0)#

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

Parameters:

Nmax (int) – Maximum rotational state to include
I1,I2 (float) – The nuclear spins of nucleus 1 and 2
Nmin (int, optional) – Minimum rotational state to include. Defaults to 0.

Returns:

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

Return type:

T (list of np.ndarray)

diatomic.operators.ac_ham(mol, a02, beta=0)#

Computes the AC Stark Hamiltonian per unit light intensity for linear polarisation.

The function combines the isotropic and anisotropic AC Stark operators for the specified electric-field polarization.

Parameters:

mol – A molecule object containing the necessary attributes for calculation.
a02 (tuple) – Two-element tuple (alpha0, alpha2) containing the isotropic and anisotropic polarizabilities.
beta (float, optional) – The polarization angle of the electric field in radians. Defaults to 0.

Returns:

The AC Stark Hamiltonian matrix per unit intensity.

Return type:

np.ndarray

diatomic.operators.ac_ham_ellip(mol, a02, omega, gamma, delta)#

Computes the AC Stark Hamiltonian per unit light intensity for arbitrary polarisation.

The function combines the isotropic and anisotropic AC Stark operators. See unit_ac_aniso_ellip for the polarisation convention.

Parameters:

mol – A molecule object containing the necessary attributes for calculation.
a02 (tuple) – Two-element tuple (alpha0, alpha2) containing the isotropic and anisotropic polarizabilities.
omega (float) – quantisation axis, with the wave vector in the x-z plane.
gamma (float) – parametrizes the relative amplitudes of the two transverse components.
delta (float) – first transverse component.

Returns:

The AC Stark Hamiltonian matrix per unit intensity.

Return type:

np.ndarray

diatomic.operators.convert_poincare_to_jones(chi, phi)#

Convert Poincare-sphere angles to Jones-vector parameters.

This public helper is reserved for a future convenience conversion. For now, pass omega, gamma, and delta directly to unit_ac_aniso_ellip.

diatomic.operators.crop_by_indices(op, indices)#

Crop any operator/Hamiltonian in the full uncoupled basis to the MN-restricted subspace.

Parameters:

op (ndarray) – Operator or Hamiltonian with shape (…, basis, basis).
indices (ndarray | None) – Basis indices to keep. If None, op is returned unchanged.

Returns:

Cropped operator with shape (…, cropped_basis, cropped_basis).

Return type:

ndarray

diatomic.operators.dc_ham(mol)#

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:: mol – Molecule object containing the permanent electric dipole moment, nuclear spins, and the rotational basis bounds.
Returns:: H (np.ndarray) - DC Stark Hamiltonian in joules

diatomic.operators.electric_gradient(Nmax, *, Nmin=0)#

Calculates the electric field gradient at the nucleus for rotational states.

Constructs a spherical tensor representing the electric field gradient at the nucleus, which depends on the rotational states but not the nuclear spin states.

Parameters:

Nmax (int) – The maximum rotational state to include.
Nmin (int, optional) – The minimum rotational state to include. Defaults to 0.

Returns:

A length-5 list of arrays representing the electric field: gradient tensor components.

Return type:

list of np.ndarray

diatomic.operators.expanded_electric_gradient(mol)#

Expands the electric gradient tensor to include nuclear spin states.

Uses the Kronecker product to expand the electric gradient tensor calculated for rotational states into a basis that also includes nuclear spin states.

Parameters:: mol – A molecular object with Nmax and nuclear spins (Ii) attributes.
Returns:: The expanded electric gradient tensor.
Return type:: np.ndarray

diatomic.operators.expanded_quad_moment(mol, nucleus)#

Expands the quadrupole moment tensor into the full hyperfine basis.

Parameters:

mol – A molecular object with Nmax and nuclear spins (Ii) attributes.
nucleus (int) – Index of the nucleus (0 or 1) for which to calculate the quadrupole moment tensor.

Returns:

The expanded nuclear quadrupole moment tensor.

Return type:

np.ndarray

diatomic.operators.expanded_unit_dipole_operator(mol, h)#

Expands a dipole operator originally the spherical harmonic basis to cover states in the uncoupled hyperfine basis of the molecule.

The dipole matrix is expanded to the basis including nuclear spin states by taking the Kronecker product with the identity matrix of the appropriate size.

Parameters:

mol – A molecular object with Nmax and nuclear spins (Ii) attributes.
h (float) – The helicity of the dipole field.

Returns:

The expanded dipole operator matrix.

Return type:

np.ndarray

diatomic.operators.generate_vecs(Nmax, I1, I2, *, Nmin=0)#

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,I2 (float) – Nuclear spins of nuclei 1 and 2
Nmin (int, optional) – minimum rotational level to include. Defaults to 0.

Returns:

length-3 list of: square arrays with width num_proj_with_below(Nmax, Nmin=Nmin) * (2I1 + 1) * (2I2 + 1)

Return type:

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

diatomic.operators.hyperfine_ham(mol)#

Calculate the field-free Hyperfine hamiltonian

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

Parameters:: mol – Molecule object containing rotational constants, hyperfine constants, nuclear spins, and the rotational basis bounds.
Returns:: Hamiltonian for the hyperfine structure in joules
Return type:: H0

diatomic.operators.makeT2(I1_vec, I2_vec)#

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

Parameters:

I1,I2 (list of np.ndarray) – Length-3 list of cartesian angular momentum operators: the output of makevecs

Returns:

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

Return type:

T (list of np.ndarray)

diatomic.operators.mn_crop_indices(Nmax, I1, I2, *, Nmin=0, MNmin=None, MNmax=None)#

Indices to keep from the full uncoupled basis after restricting MN.

The returned indices refer to the basis ordering produced by uncoupled_basis_iter(Nmax, I1, I2, Nmin=Nmin).

Parameters:

Nmax (int) – Maximum rotational quantum number in the full basis.
I1,I2 (float) – Nuclear spins of nuclei 1 and 2.
Nmin (int, optional) – Minimum rotational quantum number in the full basis. Defaults to 0.
MNmin,MNmax (float | None, optional) – Inclusive MN bounds. If both are None, no cropping is requested.

Returns:

One-dimensional integer basis indices, or None if both MN: bounds are None.

Return type:

ndarray | None

diatomic.operators.num_proj(angmom)#

Computes the number of possible projection quantum numbers for a given angular momentum quantum number.

Parameters:

angmom (int | HalfInt | float) – The angular momentum quantum number for which to calculate the number of possible projections.

Returns:

The number of possible projection quantum numbers for the specified: angular momentum.

Return type:

int

diatomic.operators.num_proj_with_below(Nmax, *, Nmin=0)#

Calculates the total number of projection quantum numbers for all angular momentum quantum numbers from Nmin up to a specified maximum value, Nmax.

The function sums analytically the number of possible projections for each angular momentum quantum number, which follows the formula 2 * N + 1. i.e. sum 2n + 1, n = Nmin to Nmax

Parameters:

Nmax (int) – The maximum angular momentum quantum number to include in the sum.
Nmin (int, optional) – The minimum angular momentum quantum number to include in the sum. Defaults to 0.

Returns:

The cumulative number of projection quantum numbers for each angular: momentum Nmin to Nmax.

Return type:

int

diatomic.operators.proj_iter(angmom)#

Generator function that yields the projections of angular momentum quantum numbers.

This function takes an angular momentum value (angmom) and generates a sequence of projection quantum numbers (m) from +angmom to -angmom in steps of 1 angular momentum unit, represented as HalfInt objects.

Parameters:

angmom (int | HalfInt | float) – The angular momentum quantum number, which can be an integer, HalfInt, or float.

Yields:

HalfInt –

A projection quantum number of the angular momentum starting from: +angmom to -angmom in decrements of 1 (in terms of angular momentum units).

diatomic.operators.proj_iter_bounded(j, mmin=None, mmax=None)#: Like proj_iter(j) but restricted to m in [mmin, mmax] (inclusive), intersected with the physical range [-j, +j]. Works for int/HalfInt/float j.

diatomic.operators.quad_moment(I_nuc)#

Calculates the nuclear electric quadrupole moments of nuclear spin.

Constructs a spherical tensor representing the nuclear quadrupole moment, which depends on the nuclear spin states, not the rotational states.

Parameters:

I_nuc (float) – The nuclear spin quantum number.

Returns:

A length-5 list of arrays representing the nuclear: quadrupole moment tensor components.

Return type:

list of np.ndarray

diatomic.operators.quadrupole(mol)#

Calculates the nuclear electric quadrupole interaction energy.

Computes the quadrupole interaction terms for the full hyperfine Hamiltonian using spherical tensor algebra. Requires the nuclear quadrupole moments and electric field gradients.

Parameters:: mol – A molecular object with necessary attributes like nuclear quadrupole moments (Qi), nuclear spins (Ii), and maximum rotational quantum number (Nmax).
Returns:: The quadrupole interaction term of the hyperfine Hamiltonian.
Return type:: np.ndarray

diatomic.operators.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+ (np.ndarray)

diatomic.operators.rotational(N, Brot, Drot)#

Calculates the hyperfine-free rotational Hamiltonian for a rigid rotor molecule.

Includes both the rotational constant (Brot) and the centrifugal distortion (Drot).

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

Parameters:

N (list of np.ndarray) – length 3 list representing the Angular momentum vector for rotation.
Brot (float) – Rotational constant in joules.
Drot (float) – Centrifugal distortion constant in joules.

Returns:

The rotational Hamiltonian in the N, MN basis.

Return type:

np.ndarray

diatomic.operators.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,J2 (list of np.ndarray)

Returns:

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

diatomic.operators.sph_iter(Nmax, *, Nmin=0)#

Generator function that yields tuples of spherical harmonic angular momentum quantum numbers up to a specified maximum angular momentum Nmax.

Parameters:

Nmax (int) – The maximum (inclusive) angular momentum quantum number to iterate up to.
Nmin (int, optional) – Minimum rotational quantum number (inclusive). Defaults to 0.

Yields:

tuple –

A tuple of two elements where the first element is the angular momentum: quantum number (N) and the second element is the projection quantum number (MN) as yielded by the proj_iter function for that N.

diatomic.operators.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 np arrays that represent the spherical tensors lists are indexed from lowest m to highests

Parameters:: T1,T2 (list of np.ndarray)
Returns:: X (np.ndarray) - scalar product of spherical tensors

diatomic.operators.tensor_nuclear(C3, I1_vec, I2_vec, I1_val, I2_val, Nmax, *, Nmin=0)#

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,I2 (float)
Nmax (int)
Nmin (int, optional)

Returns:

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

diatomic.operators.uncoupled_basis_iter(Nmax, I1, I2, *, Nmin=0)#

Generator function that yields a Cartesian product of tuples representing the uncoupled basis states for two angular momenta up to a specified maximum angular momentum.

Parameters:

Nmax (int) – The maximum angular momentum quantum number for the orbital angular momentum.
I1 (int | HalfInt | float) – The angular momentum quantum number for the first intrinsic angular momentum of the nucleus.
I2 (int | HalfInt | float) – The angular momentum quantum number for the second intrinsic angular momentum of the nucleus.
Nmin (int, optional) – Minimum rotational quantum number. Defaults to 0.

Yields:

tuple –

A tuple of four elements (N, MN, M1, M2), where N is an angular momentum: quantum number from Nmin to Nmax (inclusive), MN is the projection of N, and M1 and M2 are the projections of I1 and I2, respectively.

diatomic.operators.uncoupled_basis_pos(N, MN, MI1, MI2, I1, I2, *, Nmin=0)#

Calculates the position (index) of a given uncoupled basis state in a linear array that would be produced by uncoupled_basis_iter.

Parameters:

N (int | HalfInt | float) – The angular momentum quantum number for the first component of the basis state.
MN (int | HalfInt | float) – The projection quantum number of N.
MI1 (int | HalfInt | float) – The projection quantum number of the first intrinsic angular momentum I1.
MI2 (int | HalfInt | float) – The projection quantum number of the second intrinsic angular momentum I2.
I1 (int | HalfInt | float) – The angular momentum quantum number for the first intrinsic angular momentum.
I2 (int | HalfInt | float) – The angular momentum quantum number for the second intrinsic angular momentum.
Nmin (int, optional) – Minimum rotational quantum number of the basis. Defaults to 0.

Returns:

The index position of the uncoupled basis state in a linear array.

Return type:

int

diatomic.operators.unit_ac_aniso(Nmax, I1, I2, Beta, *, Nmin=0)#

Calculate the unit anisotropic AC Stark operator for linear polarisation.

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

Parameters:

Nmax (int)
I1,I2 (float)
Beta (float)
Nmin (int, optional) – Defaults to 0.

Returns:

Unit anisotropic AC Stark operator in the full uncoupled: basis. Multiply by the anisotropic polarizability and light intensity to obtain the Hamiltonian contribution in joules.

Return type:

H (np.ndarray)

diatomic.operators.unit_ac_aniso_ellip(Nmax, I1, I2, omega, gamma, delta, *, Nmin=0)#

Calculate the unit anisotropic AC Stark operator for arbitrary polarisation.

The light wave vector lies in the x-z plane, k = (sin(omega), 0, cos(omega)), where z is the quantisation axis. The transverse complex Jones vector is:

epsilon = (
    cos(omega) * cos(gamma),
    exp(1j * delta) * sin(gamma),
    -sin(omega) * cos(gamma),
)

so epsilon . k = 0. Defining polarisation is convention-heavy; the notes used for this implementation are here: https://gist.github.com/tomhepz/bbd3975aa8893d325d3facb76b902655

Some useful equivalences with the linear-polarisation version are:

beta = 0     <==>  omega = pi/2, gamma = 0,    delta = 0
beta = pi/2  <==>  omega = pi/2, gamma = pi/2, delta = 0

For a beam propagating along +z, the circular-polarisation conventions are:

sigma+ light: omega = 0, gamma = pi/4, delta = pi/2
sigma- light: omega = 0, gamma = pi/4, delta = -pi/2

Parameters:

Nmax (int)
I1,I2 (float)
omega (float) – quantisation axis, with the wave vector in the x-z plane.
gamma (float) – parametrizes the relative amplitudes of the two transverse components.
delta (float) – first transverse component.
Nmin (int, optional) – Defaults to 0.

Returns:

Unit anisotropic AC Stark operator in the full uncoupled: basis. Multiply by the anisotropic polarizability and light intensity to obtain the Hamiltonian contribution in joules.

Return type:

H (np.ndarray)

diatomic.operators.unit_ac_iso(Nmax, I1, I2, *, Nmin=0)#

Calculate the unit isotropic AC Stark operator.

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

Parameters:

Nmax (int) - maximum rotational quantum number to calculate (int)
I1,I2 (float)
Nmin (int, optional) – Defaults to 0.

Returns:

Unit isotropic AC Stark operator in the full uncoupled: basis. Multiply by the scalar polarizability and light intensity to obtain the Hamiltonian contribution in joules.

Return type:

H (np.ndarray)

diatomic.operators.unit_dipole_operator(Nmax, h, *, Nmin=0)#

Generates the induced dipole moment operator for a rigid rotor molecule in the spherical harmonic basis.

This function constructs the dipole moment matrix by iterating over spherical harmonics for rotational states up to Nmax. It uses the Wigner 3j symbols to calculate the matrix elements, which represent transitions between rotational states induced by an external dipole field of specified helicity (h).

Parameters:

Nmax (int) – The maximum rotational quantum number to include.
h (float) – The helicity of the dipole field.
Nmin (int, optional) – The minimum rotational quantum number to include. Defaults to 0.

Returns:

The induced dipole moment matrix for transitions between: rotational states up to Nmax.

Return type:

np.ndarray

diatomic.operators.vector_dot(A, B)#

Cartesian dot product of two vectors of (matrix) operators A, B

Parameters:: A,B (np.ndarray) – Cartesian length-3 vectors of operators (3xNxN)
Returns:: result of the dot product, NxN array.
Return type:: np.ndarray

diatomic.operators.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,beta,gamma (float) – x,z,x Euler angles in radians

Returns:

Value of the wigner-D matrix

Return type:

D (float)

diatomic.operators.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 np array
Return type:: Jx (np.ndarray)

diatomic.operators.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 np array
Return type:: Jy (np.ndarray)

diatomic.operators.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 np array
Return type:: Jz (np.ndarray)

diatomic.operators.zeeman(Cz, J)#

Calculates the Zeeman effect Hamiltonian for a magnetic field along the z-axis.

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

Parameters:

Cz (float) – Zeeman coefficient/magnetic moment.
J (list of np.ndarray) – Angular momentum operator vector.

Returns:

The Zeeman Hamiltonian.

Return type:

np.ndarray

diatomic.operators.zeeman_ham(mol)#

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:: mol – Molecule object containing magnetic moments, nuclear spins, and the rotational basis bounds.
Returns:: Hamiltonian for the zeeman effect
Return type:: Hz (np.ndarray)

Operators

Contents

Operators#