Documentation
Matrix element computation
Toolkit to define photon modes
- class pyRET.multipole_scalar_angular.MP_SA(lmax)[source]
Class representing Scalar Multipole in angular coordinates
- C
Dictionary containing multipole coefficients. C[l][m] is the coefficient of the multipole with angular momentum l and m.
- lmax
integer value of max angular momentum. Here l = 0,1,2,…,lmax. m = -l, -l+1,…,l-1,l
- class pyRET.multipole_vector_angular.MP_VA(jmax)[source]
Class representing Vector Multipole in angular coordinates with definite l values (j = Total angular momentum, l = orbital angular momentum, M = projected total angular momentum)
- C
Dictionary containing multupole coefficients C[j][l][M]
- Type:
dict of dict of dict of complex
- jmax
integer value of max angular momentum
- Type:
int
- absMP(func)[source]
Absolute magnitude of sum of all (or specific angular components)
- Parameters:
func (callable) – A function that takes (j, l, M) and returns True if the component should be included.
- decompose(V, theta, phi, dtheta, dphi)[source]
Multipole decomposition of a given vector field :param V: Vector field over angular coordinates theta and phi. The first dimension is the vector component (r, theta, phi) :type V: array of shape (3, Ntheta, Nphi) :param theta: Theta coordinates :type theta: array of shape (Ntheta, Nphi) :param phi: Phi coordinates :type phi: array of shape (Ntheta, Nphi) :param dtheta: step size in theta :type dtheta: float :param dphi: step size in phi :type dphi: float
- class pyRET.multipole_vector_angular.MP_VA_Hansen(jmax)[source]
Class representing Hansen Vector Multipole (Angular only) in j , M basis (j = Total angular momentum, M = projected total angular momentum, lam = a parameter to determine which mode– longitudinal(-1), and two transverse (0, 1)
- C
Dictionary containing multupole coefficients C[j][M][lam]
- Type:
dict of dict of dict of complex
- jmax
integer value of max angular momentum
- Type:
int
- pyRET.multipole_vector_angular.addMP_VA(mps)[source]
Helper function to add vector multipoles in a list.
- pyRET.multipole_vector_angular.addMP_VA_Hansen(mps)[source]
Helper function to add Hansen vector multipoles in a list.
- Parameters:
mps (list of MP_VA_Hansen) – list of MP_VA_Hansen objects
- Returns:
combined MP_VA_Hansen object
- Return type:
- class pyRET.fields.SField(origin=array([0., 0., 0.]))[source]
Class representing a Scalar Multipolar Field. This class contains a multipolar scalar field that is stored as a sum of various multipolar components, each with specific value of wavevectors and radial functions. The multipolar (angular) components are stored as MP_SA objects
- origin
coordinates of the center.
- Type:
np.ndarray of shape (3,)
- ks
list of radial wavevectors corresponding to different components
- Type:
list of float
- rfuns
list of dictionary containing information on the radial function. must contain the key “type” = “J” or “H1” or “Atomic” optional keys: “order”, “n”,”Z” etc etc.
- Type:
list of dict
- Encode()[source]
Encodes the SField object to a jsonizable dictionary. The multipoles are encoded using their own Encode() method.
- add_component(kval, lmax, rfun)[source]
Adds a component- one multipole mode with specific rfunc and specific value of the wavevector with specificed combination of multipoles
- Parameters:
kval (float) – value of the wavevector in 2pi/Angstrom unit
lmax (int) – maximum order of the multipole
rfun (dict) – dictionary containing information on the radial function
- class pyRET.fields.VField(origin=array([0., 0., 0.]))[source]
Class representing a Vector Field. This class contains a multipolar vector field that is stored as a sum of various multipolar components, each with specific value of wavevectors and radial functions. The multipolar (angular) components are stored as MP_VA or MP_VA_Hansen objects
- origin
origin of the field
- Type:
np.ndarray of shape (3,)
- ks
list of radial wavevectors corresponding to different components
- Type:
list of float
- mpvs
list of multipoles (MP_VA or MP_VA_Hansen)
- Type:
list of MP_VA or MP_VA_Hansen
- rfuns
list of dictionary containing information on the radial function. must contain the key “type” = “J” or “H1” or “Atomic” optional keys: “order”, “n”,”Z” etc etc.
- Type:
list of dict
- Decode(data)[source]
Decodes the VField object from a jsonizable dictionary. The multipoles are decoded using their own Decode() method.
- Encode()[source]
Encodes the VField object to a jsonizable dictionary. The multipoles are encoded using their own Encode() method.
- Farfield(theta, phi)[source]
Calculates the far field distribution of the vector field on a theta and phi grid.
- Parameters:
theta (np.ndarray of shape (N1, N2, ...)) – polar angle grid
phi (np.ndarray of shape (N1, N2, ...)) – azimuthal angle grid
- Returns:
far field vector field evaluated at the angles specified by theta and phi.
- Return type:
V (np.ndarray of shape (3, N1, N2, ..))
- add_component(kval, jmax, rfun, isHansen=False)[source]
Add a component. One multipole mode with specific rfunc and specific value of the wavevector with specificed combination of multipoles. The multipoles are initialized to zero and need to be filled in separately.
- Parameters:
kval (float) – value of the wavevector in 2pi/Angstrom unit
jmax (int) – maximum order of the multipole
rfun (dict) – dictionary containing information on the radial function must contain the key “type” = “J” or “H1” or “Atomic” optional keys: “order”, “n”,”Z” etc etc. isHansen(bool): whether the multipole is Hansen type or not. If True, the multipole will be initialized as MP_VA_Hansen, else it will be initialized as MP_VA.
- torgrid(rgrid)[source]
Project the vector field in a position grid.
- Parameters:
rgrid (np.ndarray of shape (3, N1, N2, ..)) – position grid where the field needs to be evaluated.
- Returns:
vector field evaluated at the positions specified by rgrid.
- Return type:
V (np.ndarray of shape (3, N1, N2, ..))
- pyRET.fields.curl(V)[source]
Computes curl of a vector field. Only applicable for rfun{“order”} = None or l; and rfun[“type”] = “J” or “H1”.
- pyRET.fields.divergence(V)[source]
Computes divergence of a vector field. Only applicable for rfun{“order”} = None or l; and rfun[“type”] = “J” or “H1”.
- pyRET.fields.gradient(S)[source]
Computes gradient of a scalar field. Only applicable for rfun{“order”} = None or l; and rfun[“type”] = “J” or “H1”.
- pyRET.emfieldtools.InitializeMultipole(Ls, Ms, Ps, Ws, lam, nIndex, jmax, C=None, radtype='J')[source]
Initiates a quantized photon multipole mode.
- Parameters:
Ls (list of int) – List of the total angular momentum quantum numbers of the multipole components
Ms (list of int) – List of the magnetic quantum numbers (J_z projections) of the multipole components
Ps (list of int) – List of the parity of the multipole components (-1)**L for electric type, (-1)**(L+1) for magnetic type
Ws (list of float) – List of the weights of the multipole components.
lam (float) – Wavelength of the mode in vacuum
nIndex (float) – Refractive index of the medium
jmax (int) – Maximum order of the spherical Bessel functions to be included in the expansion
C (float) – Gauge parameter, if None, the Lorenz gauge is used, otherwise the gauge is defined by the value of C.
- Returns:
Vector potential of the mode A0 (SField): Scalar potential of the mode Evect (VField): Electric field of the mode Hvect (VField): Magnetic field of the mode
- Return type:
Avect (VField)
Toolkit to define wavefunctions
- class pyRET.wavefunctions.WFunction[source]
Class representing a Wavefunction
- isGamma
True if the wavefuncton is at Gamma point
- Type:
bool
- Gs
numpy complex array shape (3, NG) denoting the G vectors for plane wave expansion
- Type:
numpy array
- evcCs
numpy complex array of shape (1, NG) - plane wave expansion coefficients for a specific KS state
- Type:
numpy array
- NG
int storing number of plane waves
- Type:
int
- isplanewave
True when the plane wave expansion exists.
- Type:
bool
- MPField
SField object storing the multipole expanded scalar field. can be empty, in that case isplanewave = True
- Type:
- readfromhdf5(self, filename, iKS, cpA)[source]
reads a specific KS state iKS into the plane wave basis from a hdf5 file generrated by quantum espresso. cpA = cell parameter block.
- readfromhdf5_parallel(self, filename, iKS, cpA, comm)[source]
reads a specific KS state iKS into the plane wave basis from a hdf5 file generrated by quantum espresso. cpA = cell parameter block. Uses parallel hdf5.
- torgrid(self, rgrid, istart=0, istep=1, kparity=1)[source]
Calculates values at coordinate space. istart and istep can be used to skip over plane waves. kparity is the parity in k-space- specifically relevant for calculating at Gamma point.
- getharmonics(self, lmax)[source]
Using the plane wave basis, analytically creates a Scalar Field object into the attr. MPField
- getharmonics(lmax)[source]
Computes multipole expansion of the wavefunction using the plane wave expansion coefficients. This is done by using the identity that a plane wave can be expanded in terms of spherical harmonics and spherical Bessel functions. The resulting multipole expansion is stored in the MPField attribute of the wavefunction object.
- Parameters:
lmax (int) – maximum angular momentum quantum number for the multipole expansion
- kpsitorgrid(rgrid, istart=0, istep=1, dr=None)[source]
Calculates k operating on psi over a specific position grid. This is useful for calculating the momentum matrix elements.
- Parameters:
rgrid (array-like) – 3 x N array of coordinates where the wavefunction needs to be evaluated.
istart (int, optional) – Starting index for plane wave summation. Defaults to 0.
istep (int, optional) – Step size for plane wave summation. Defaults to 1.
dr (float, optional) – Finite difference step size for numerical differentiation when plane wave basis is not available. Defaults to None, in which case a small value of 1e-12 is used.
- readfromdat(filename, iKS, cpA)[source]
Reads the plane waves from a .dat file
- Parameters:
filename (str) – path to the .dat file containing the plane wave expansion of the wavefunction
iKS (int) – index of the KS state to be read from the .dat file
cpA (array-like) – cell parameter block
- readfromhdf5(filename, iKS, cpA)[source]
Reads the plane waves from hdf5 file
- Parameters:
filename (str) – path to the hdf5 file containing the plane wave expansion of the wavefunction
iKS (int) – index of the KS state to be read from the hdf5
cpA (array-like) – cell parameter block
- readfromhdf5_parallel(filename, iKS, cpA, comm)[source]
Reads the plane waves from hdf5 file in parallel
- Parameters:
filename (str) – path to the hdf5 file containing the plane wave expansion of the wavefunction
iKS (int) – index of the KS state to be read from the hdf5
cpA (array-like) – cell parameter block
comm (MPI.Comm) – MPI communicator for parallel reading
- torgrid(rgrid, istart=0, istep=1, kparity=1)[source]
Project the wavefunction from the plane wave basis onto a user specified position grid.
- Parameters:
rgrid (array-like) – 3 x N array of coordinates where the wavefunction needs to be evaluated.
istart (int, optional) – Starting index for plane wave summation. Defaults to 0.
istep (int, optional) – Step size for plane wave summation. Defaults to 1.
kparity (int, optional) – Parity in k-space, relevant for Gamma point. Defaults to 1.
Helper functions for wavefunction processing.
Toolkit to calculate the matrix elements
- pyRET.Vtools.V12(wfr1, kwfr1, wfr2, kwfr2, rgrids, k, L, M, P, nIndex=1.0, Cgauge=0, Hint='Adotp', rshift=array([0., 0., 0.]), radtype='J', dV=None, etaeff=1.0)[source]
Computes the matrix elements with specific positions and wavefunctions. This is the core function that computes the V matrix elements for a given set of wavefunctions, multipole parameters, and positions. It can compute the matrix elements for both the “Adotp” and “Edotr” interaction Hamiltonians, and it can also handle different gauges and radial function types. The computed matrix elements are returned as a 2x2 matrix corresponding to the different spin configurations.
- Parameters:
wfr1 (numpy array of shape (N, N, N)) – Wavefunction of the initial state
kwfr1 (numpy array of shape (3, N, N, N)) – Gradient of the wavefunction of the initial state
wfr2 (numpy array of shape (N, N, N)) – Wavefunction of the final state
kwfr2 (numpy array of shape (3, N, N, N)) – Gradient of the wavefunction of the final state
rgrids (numpy array of shape (3,n1,n2,..nM, N, N, N)) – Radial grid for the computation of the matrix elements
k (float) – Wavevector of the emitted photon
L (int) – Orbital angular momentum
M (int) – projected total angular momentum
P (int) – Parity of the multipole
nIndex (float) – Refractive index of the medium. Defaults to 1.
Cgauge (int) – Gauge parameter. 0 for Coulomb gauge.
Hint (str) – Type of interaction Hamiltonian to use. Options are “Adotp” or “Edotr”. Defaults to “Adotp”.
rshift (numpy array of shape (3,)) – Additional shift in position. Optional.
radtype (str) – Type of radial function to use. Options are “J” for Bessel functions and “H1” for Hankel functions. Defaults to “J”.
dV (float) – Volume element for the integration. If None, it will be computed from the rgrids. Defaults to None.
etaeff (float) – Effective mass of electron in the Pauli-Fierz hamiltonian normalized to the free electron mass.
- Returns:
matrix elements. The first two dimensions correspond to the spin configurations (spin flip tag on initial and final states), and the remaining dimensions correspond to the spatial grid defined by rgrids.
- Return type:
V12 (numpy array of shape (2, 2, n1, n2, … nM))
- pyRET.Vtools.V12_ED(pEDs, rvects, k, L, M, P, nIndex=1.0, radtype='J', Cgauge=0, etaeff=1.0, includespin=True)[source]
Computes matrix element under the electric dipole approximation.
- Parameters:
pEDs (numpy array of shape (3,)) – The x, y, z components of the electric dipole moment vector.
rvects (numpy array of shape (3, n1, n2, ... nM)) – The x, y, z positions of the dipole.
k (float) – The wavevector.
L (int) – Multipole parameters.
M (int) – Multipole parameters.
P (int) – Multipole parameters.
nIndex (float) – Refractive index.
radtype (str) – Type of radial function.
Cgauge (int) – Gauge parameter.
etaeff (float) – Effective mass correction.
includespin (bool) – Whether to include spin effects.
- Returns:
The interaction matrix element under the electric dipole approximation.
- Return type:
V12 (numpy array of shape (2, 2, n1, n2, … nM))
- pyRET.Vtools.V12_MD(pMDs, rvects, k, L, M, P, nIndex=1.0, radtype='J', Cgauge=0, etaeff=1.0, includespin=True)[source]
Computes matrix element under the magnetic dipole approximation.
- Parameters:
pMDs (numpy array of shape (3,)) – The x, y, z components of the magnetic dipole moment vector.
rvects (numpy array of shape (3, n1, n2, ... nM)) – The x, y, z positions of the dipole.
k (float) – The wavevector.
L (int) – Multipole parameters.
M (int) – Multipole parameters.
P (int) – Multipole parameters.
nIndex (float) – Refractive index.
radtype (str) – Type of radial function.
Cgauge (int) – Gauge parameter.
etaeff (float) – Effective mass correction.
includespin (bool) – Whether to include spin effects.
- Returns:
The interaction matrix element under the magnetic dipole approximation.
- Return type:
V12 (numpy array of shape (2, 2, n1, n2, … nM))
- pyRET.Vtools.V12_par(wfr1, kwfr1, wfr2, kwfr2, rgrids, k, L, M, P, nIndex=1.0, Cgauge=0, Hint='Adotp', rshift=array([0., 0., 0.]), radtype='J', dV=None, etaeff=1.0, parallel=True)[source]
Parallely computes, using mpi4py, the matrix elements with specific positions and wavefunctions. This is the core function that computes the V matrix elements for a given set of wavefunctions, multipole parameters, and positions. It can compute the matrix elements for both the “Adotp” and “Edotr” interaction Hamiltonians, and it can also handle different gauges and radial function types. The computed matrix elements are returned as a 2x2 matrix corresponding to the different spin configurations. This function also supports serial implementation if parallel flag is set to False.
- Parameters:
wfr1 (numpy array of shape (N, N, N)) – Wavefunction of the initial state
kwfr1 (numpy array of shape (3, N, N, N)) – Gradient of the wavefunction of the initial state
wfr2 (numpy array of shape (N, N, N)) – Wavefunction of the final state
kwfr2 (numpy array of shape (3, N, N, N)) – Gradient of the wavefunction of the final state
rgrids (numpy array of shape (3,n1,n2,..nM, N, N, N)) – Radial grid for the computation of the matrix elements
k (float) – Wavevector of the emitted photon
L (int) – Orbital angular momentum
M (int) – projected total angular momentum
P (int) – Parity of the multipole
nIndex (float) – Refractive index of the medium. Defaults to 1.
Cgauge (int) – Gauge parameter. 0 for Coulomb gauge.
Hint (str) – Type of interaction Hamiltonian to use. Options are “Adotp” or “Edotr”. Defaults to “Adotp”.
rshift (numpy array of shape (3,)) – Additional shift in position. Optional.
radtype (str) – Type of radial function to use. Options are “J” for Bessel functions and “H1” for Hankel functions. Defaults to “J”.
dV (float) – Volume element for the integration. If None, it will be computed from the rgrids. Defaults to None.
etaeff (float) – Effective mass of electron in the Pauli-Fierz hamiltonian normalized to the free electron mass.
- Returns:
matrix elements. The first two dimensions correspond to the spin configurations (spin flip tag on initial and final states), and the remaining dimensions correspond to the spatial grid defined by rgrids.
- Return type:
V12 (numpy array of shape (2, 2, n1, n2, … nM))
- pyRET.Vtools.Veded(p1vec, p2vec, rvects, nIndex, omega)[source]
Compute dipole-dipole interaction.
- Parameters:
p1vec (numpy array of shape (3,)) – The x, y, z components of the first dipole moment vector.
p2vec (numpy array of shape (3,)) – The x, y, z components of the second dipole moment vector.
rvects (numpy array of shape (3, n1, n2, ... nM)) – The x, y, z positions of the dipoles.
nIndex (float) – Refractive index.
omega (float) – Angular frequency.
mode = “nearfield” or “general”
- Returns:
Dipole-dipole interaction energy in SI units.
- Return type:
Veded (numpy array of shape (n1, n2, … nM))
- pyRET.Vtools.computeV(absorber_id, emitter_id, absorber_transitions, ws, Lmax, Em_data, Pos_data, WF_data, radtype_abs='H1', parallel=True, Hint='Adotp')[source]
This function computes the V matrix elements for a given set of transitions and photon energies. It checks if the wavefunction data for the absorber is available in the WF_data, and if so, it uses the wavefunction data to compute the V matrix elements. If not, it uses known multipole moments to compute the V matrix elements. The function can also handle both self-interaction (where the emitter and absorber are the same) and distant interaction (where the emitter and absorber are different) cases. The computed V matrix elements are stored in a V_data object and returned at the end of the function.
- Parameters:
absorber_id (str) – Identifier for the absorber
emitter_id (str) – Identifier for the emitter
absorber_transitions (list) – List of transitions for the absorber
ws (numpy array) – Array of photon angular frequencies (rad/s)
Lmax (int) – Maximum multipole order to consider for the calculation of V
Em_data (Emitters_data) – Object of the Emitters_data class
Pos_data (Positions_data or Positions_data_1config) – Object of the Positions_data or Positions_data_1config class
WF_data (list of WFunctions_data) – List of objects of WFunctions_data class
radtype_abs (str, optional) – Type of radial function to use for the absorber. Options are “J” or “H1”. Defaults to “H1”.
parallel (bool, optional) – Whether to use parallel processing. Defaults to True.
Hint (str, optional) – Type of interaction Hamiltonian to use. Options are “Adotp” or “Edotr”. Defaults to “Adotp”.
- Returns:
Object of the V_data class containing the computed matrix elements.
- Return type:
Vdata (V_data)
- pyRET.Vtools.hasWF(em, WF_data)[source]
Check if the WF_data contains the wavefunction data for the emitter type em
- Parameters:
em (str) – Emitter type
WF_data (list) – List of wavefunction data objects
- Returns:
True if the wavefunction data for the emitter type em is found in WF_data, False otherwise
- Return type:
bool
- pyRET.Vtools.whichWF(em, statei, statef, WF_data)[source]
Find the indices of the Wavefunction data that corresponds to the states of a specific transition.
- Parameters:
em (str) – Emitter type
statei (str) – Initial state of the transition
statef (str) – Final state of the transition
WF_data (list) – List of wavefunction data objects
- Returns:
Index of the WF_data object that contains the wavefunction data for the initial state iemi (int): Index of the emitter type in the WF_data object that contains the wavefunction data for the initial state iwfdataf (int): Index of the WF_data object that contains the wavefunction data for the final state iemf (int): Index of the emitter type in the WF_data object that contains the wavefunction data for the final state
- Return type:
iwfdatai (int)
Data classes
- class pyRET.data_classes.Emitters_data[source]
Dataclass representing types and corresponding information on the emitters.
- EmType
dictionary with Emitter IDs as keys and emitter types as strings.
- Type:
dict
- T1
dictionary with Emitter IDs as keys and T1 values.
- Type:
dict
- w
dictionary with Emitter IDs as keys and transition frequencies (rad/s).
- Type:
dict
- k
dictionary with Emitter IDs as keys and wave numbers (1/m).
- Type:
dict
- nIndex
dictionary with Emitter IDs as keys and refractive indices of the medium the emitter sits in.
- Type:
dict
- pMPs
dictionary with Emitter IDs as keys– predefined multipole moments (if any) of the emitters.
- Type:
dict
- class pyRET.data_classes.Positions_data[source]
Dataclass representing relative positions of the emitters. The attributes are dictionaries with the convention of first key = absorber id and second key = emitter id. The values are arrays of the corresponding data.
- Rs
dictionary of dictionaries of radial positions of the emitters with respect to the absorber.
- Type:
dict of dict of numpy arrays
- Ts
dictionary of dictionaries of polar angles of the emitters with respect to the absorber.
- Type:
dict of dict of numpy arrays
- Ps
dictionary of dictionaries of azimuthal angles of the emitters with respect to the absorber.
- Type:
dict of dict of numpy arrays
- Rg
R in grid format.
- Type:
dict of dict of numpy arrays
- Tg
T in grid format.
- Type:
dict of dict of numpy arrays
- Pg
P in grid format.
- Type:
dict of dict of numpy arrays
- Rvects
each array has a shape of (3, Nr, Nt, Np) and represents the position vectors of the emitters with respect to the absorber in Cartesian coordinates over the position grid. The first index of the array is for the x, y, z components of the position vector.
- Type:
dict of dict of numpy arrays
- class pyRET.data_classes.Positions_data_1config[source]
Dataclass representing relative positions of the emitters. This is similar to the Positions_data class but is for a single configuration of emitter-absorber positions.
- Rs
radial positions of the emitters with respect to the absorber.
- Type:
numpy array
- Ts
polar angles of the emitters with respect to the absorber.
- Type:
numpy array
- Ps
azimuthal angles of the emitters with respect to the absorber.
- Type:
numpy array
- Rvects
position vectors of the emitters with respect to the absorber in Cartesian coordinates.
- Type:
numpy array
- class pyRET.data_classes.V_data[source]
Dataclass containing matrix elements computed in spherical multipolar basis.
- ws
dictionary with absorber IDs as keys and values as dictionaries with emitter IDs as keys and complex numbers as values.
- Type:
dict
- V
nested dictionary of the format V[absorber_id][emitter_id][absorber_transition][L][M][P] = complex ND Array absorber_transition is of the format “‘initial_state’-to-‘final_state’” L, M, P are the multipole order, multipole component and parity of the transition respectively.
- Type:
dict
- class pyRET.data_classes.WFunctions_data(emitterTypes=None, states=None, iKSs=None, rgridwf=None, Ns=None, pwout=None, wfs=None, kwfs=None, wfrs=None, kwfrs=None)[source]
Dataclass for handling wavefunctions.
- emitterTypes
list of emitter types.
- Type:
list of string
- states
list of list of states.
- Type:
list of list of string
- iKSs
list of list of KS indices for the states.
- Type:
list of list of int
- rgridwf
list of rgridwfs- separate for each emitter.
- Type:
list of arrays
- Ns
list of dict of normalization constants for each state.
- Type:
list of dict
- pwout
list of pw.out texts correspinding to each emitter for book keeping.
- Type:
list of string
- wfs
list of dict of wfs (WFunction class object) for each state as the key.
- Type:
list of dict
- kwfs
list of dict of k operated on wfs (Vector Fields) for each state as the key. Can be empty
- Type:
list of dict
- wfrs
list of dict of values of the wavefunctions over corresponding position grids.
- Type:
list of dict
- kwfrs
list of dict of values of the k operated wavefunctions over corresponding position grids.
- Type:
list of dict