lumeq.dynamics package

Submodules

lumeq.dynamics.dimers_in_crystal module

add_molecule(ix, iy, iz, inverse, abc, angles, elements, scales)

add_molecules_cell(n_images, abc, angles, elements, scales)

cal_dipole_interactions(dipoles, coords)

dipole_dipole_interaction(d1, d2, r1, r2)

d1, d2: dipoles (x,y,z) r1, r2: dipole center coordinates (x, y, z)

get_center_of_mass(atmsym, coords)

read_unit_cell_info(ciff)

translate_molecule(ix, iy, iz, abc, angles, elements, coords0)

write_eda_files(elements, coordinates, mol)

write_xyz_files(elements, coordinates, mol)

lumeq.dynamics.electronic_dynamics_gs module

class CurvyStep(key)

Bases: ElectronicStep

refer: Herbert 2004 JCP 10.1063/1.1814934

cal_electronic_energy_force(F, P, Z)

cy_get_mass_on_basis(F)

cy_orbital_response()

cy_update_delta(G, mass_bas)

cy_update_density(P, Z)

euler_step(G, mass_bas)

get_electronic_kinetic_energy(velocities, mass)

init_electronic_density_static(coords)

leapfrog_step(G, mass_bas)

update_electronic_density_static(coords)

update_electronic_density_static2(coords)

velocity_verlet_step(G, mass_bas, half)

class ElectronicStep(key, **kwargs)

Bases: object

cal_electronic_force()

get_ortho_basis(ovlp=None)

init_electronic_density_static(coords, *args, **kwargs)

setup_electronic_basis(coords, *args, **kwargs)

update_electronic_density_dynamics(coords)

update_electronic_density_static(coords, *args, **kwargs)

class ExtendedLagStep(key)

Bases: ElectronicStep

refer: Niklasson 2009 JCP 10.1063/1.3148075

Niklasson 2017 JCP 10.1063/1.4985893 Niklasson 2020 JCP 10.1063/1.5143270

init_electronic_density_static(coords)

init_xl_variables()

static_extended_lagrange()

update_electronic_density_static(coords)

xl_auxiliary_density_dotdot()

xl_build_fock(coords)

xl_build_fock_init(coords, k)

class GrassmannStep(key)

Bases: ElectronicStep

init_electronic_density_static(coords)

interpolation(coords)

update_electronic_density_static(coords)

update_gamma_lagrange(coords)

cal_electronic_energy1(mf, P1, Z=None, method='lowdin')

normal energy

cal_electronic_energy2(mf, P1, Z=None, method='lowdin')

extended lagrange energy

cal_electronic_force(mf, P1, P2=None, P3=None, F=None, Z=None, method='lowdin')

cal_idempotency(P, S=None)

cal_pulay_force(mf, F, P, Fao, Pao, Z, method='lowdin')

density_purification(P, S=None)

run_pyscf_gs(scf_method, mol, functional, *args, **kwargs)

lumeq.dynamics.exciton_dynamics module

class Exciton(key={}, **kwargs)

Bases: object

Exciton class at each time for energy transport simulation. It builds the exciton Hamiltonian and update the exciton coefficients.

analyze_wf_property(coefficients=None, c2=None)

Analyze the exciton wavefunction properties including r-correlation and ipr.

cal_energy(hamiltonian=None, coefficients=None)

Calculate the exciton energy expectation value.

cal_ipr_value(coefficients=None, c2=None)

Calculate the inverse participation ratio (ipr) value.

cal_r_correlation(coefficients=None, c2=None)

Calculate the exciton r^2 - <r>^2 correlation value.

cal_spectra(dipole=None, coefficients=None)

Calculate the exciton absorption spectra.

Parameters:

• dipole (numpy.ndarray, optional) – Transition dipoles for each site with shape (nsite*nstate, 3).

• coefficients (numpy.ndarray, optional) – Exciton coefficients with shape (nsite*nstate,).

Returns:

Exciton eigenvalues and oscillator strengths, each with shape (nsite*nstate,).

Return type:

tuple

check_sanity()

Check the sanity of the input parameters.

convert_parameter_units(unit_dict={})

Convert the input parameters into atomic unit for the calculations.

exciton_couplings(coupling_j=None, neighbor_index=None, **kwargs)

Build the exciton couplings part of exciton Hamiltonian.

exciton_diagonal(energy=None, **kwargs)

Return the on-site energy.

get_hamiltonian(energy=None, coupling_j=None, neighbor_index=None, **kwargs)

Build the periodic exciton Hamiltonian of exciton part.

Parameters:

• energy (numpy.ndarray, optional) – Exciton energies for each state.

• coupling_j (numpy.ndarray, optional) – Exciton-exciton couplings with shape (ndimer, nstate, nstate).

• neighbor_index (list, optional) – Neighbor indices for the couplings.

• **kwargs – Additional keyword arguments.

Returns:

Exciton Hamiltonian with shape (nsite*nstate, nsite*nstate).

Return type:

numpy.ndarray

get_initial_coefficients(H=None, method=None, **kwargs)

Get the initial exciton coefficients from the exciton Hamiltonian.

Parameters:

• H (numpy.ndarray, optional) – Exciton Hamiltonian with shape (nsite*nstate, nsite*nstate).

• method (str, optional) – Method used to initialize the coefficients. 'random' gives random coefficients, 'equal' gives an equal superposition state, 'ground' gives the ground state, and 'thermal' gives a thermal equilibrium state at the given temperature.

Returns:

Squared exciton coefficients with shape (nsite*nstate,).

Return type:

numpy.ndarray

print_site_coords(xyzfile=None)

Print site coordinates to xyz file for visualization.

process_parameters()

Process the input parameters and get real parameters.

update_coefficients(H=None, dt=None, exp_h=None, **kwargs)

Update the exciton coefficients with time step dt.

Parameters:

dt (float) – Time step in atomic units.

Returns:

Squared exciton coefficients with shape (nsite*nstate,).

Return type:

numpy.ndarray

class ExcitonDynamics(key, **kwargs)

Bases: object

Exciton dynamics for energy transport simulation. Wrapper class containing exciton and phonon dynamics steps.

kernel()

set_dynamics_class(key)

Set the dynamics class for exciton and phonon dynamics.

class ExcitonDynamicsMC(key, **kwargs)

Bases: ExcitonDynamics

Exciton dynamics with Monte Carlo sampling Hamiltonian. Wrapper class containing exciton dynamics with MC disorders.

kernel()

set_dynamics_class(key)

Set the dynamics class for exciton Monte Carlo dynamics.

class ExcitonMC(key={}, **kwargs)

Bases: Exciton

Thermal fluctuations are accounted for by Monte Carlo sampling Hamiltonian.

get_sampler(variance=0.1, seed=123, **kwargs)

Get the sampler for Monte Carlo sampling of exciton Hamiltonian.

Parameters:

• variance (float) – Variance of the random numbers.

• seed (int) – Seed for the random number generator.

split_operator(dt=None, **kwargs)

Get the split operator for time propagation.

Math exp(-i H dt) = exp(-i H_d dt/2) exp(-i H_c dt) exp(-i H_d dt/2)

Parameters:

dt (float, optional) – Time step in atomic units.

Returns:

Function that returns the time-propagation operator with shape (nsite*nstate, nsite*nstate).

Return type:

callable

update_parameters(sample=None, dt=None)

Update the exciton Hamiltonian parameters by Monte Carlo sampling.

Parameters:

sample (callable, optional) – Sampling function used to generate the random numbers. Passing a callable avoids repeated attribute lookup.

class ExcitonStep(key={}, **kwargs)

Bases: Exciton

Thermal fluctuations are accounted for by explicit vibrational oscillators. Requires the exciton-phonon couplings, and oscillator coordinates.

cal_force(coordinate, coefficients=None)

Calculate the forces on each oscillators from exciton-phonon couplings.

exciton_couplings(coupling_j=None, neighbor_index=None, coupling_a=None, coordinate=None)

Build the exciton couplings part with coordinate fluctuation.

Parameters:

• coupling_j (numpy.ndarray, optional) – Exciton-exciton couplings with shape (ndimer, nstate, nstate).

• neighbor_index (list, optional) – Neighbor indices for the couplings.

• coupling_a (numpy.ndarray, optional) – Off-diagonal exciton-phonon couplings with shape (ndimer, nmode, nstate, nstate).

• coordinate (numpy.ndarray, optional) – Oscillator coordinates with shape (nsite, nmode).

Returns:

Exciton Hamiltonian with shape (nsite*nstate, nsite*nstate).

Return type:

numpy.ndarray

exciton_diagonal(coordinate)

Return the on-site energy with coordinate dependence.

setup_exciton_dynamics(infile, key={}, nsteps=300)

Run the exciton dynamics simulation.

Parameters:

• infile (str) – Input file for dynamics parameters.

• key (dict) – Input parameters.

• nsteps (int) – Total number of time steps for the dynamics.

Returns:

Configured exciton-dynamics object.

Return type:

ExcitonDynamicsMC

lumeq.dynamics.molecular_dynamics module

class MolecularDynamics(key, ed_key={}, ph_key={}, **kwargs)

Bases: object

kernel()

plot_time_variables(fig_name=None)

run_dynamics()

set_electronic_step(key, **kwargs)

set_nuclear_step(key)

set_photon_step(key, **kwargs)

plot_time_variables(total_time, nsteps, dists, energies)

lumeq.dynamics.oscillator_dynamics module

class NuclearStep(key={}, **kwargs)

Bases: harmonic_oscillator

Nuclear dynamics step class.

convert_parameter_units(unit_dict)

get_potential_energy(mass=None, coordinate=None, omega2=None)

Calculate the potential energy.

init_coordinate_velocity(init_method=None)

Generate the initial nuclear coordinate and velocity.

Parameters:

init_method (str, optional) – Method used to initialize the coordinates and velocities. 'restart' reads stored values, 'kick' sets zero initial velocity, 'thermo' samples a Boltzmann distribution at init_temp, and 'random' uses random velocities with the given kinetic energy.

init_velocity_random(etrans=None, sigma=0.0001, scale=0.1, seed=12345)

Generate random kinetic energy for atoms at three directions.

init_velocity_thermo(temp=None, seed=1385448536)

Generate random velocity following Boltzmann distribution.

project_force(force, mass=None, coords=None)

Project out the translational and rotational components from the force.

project_velocity(velocity, mass=None, coords=None)

Project out the translational and rotational components from the velocity.

update_coordinate_velocity(force, half=1, **kwargs)

Update the nuclear coordinate and velocity.

class OscillatorStep(key={}, **kwargs)

Bases: harmonic_oscillator

Oscillator dynamics step class.

convert_parameter_units(unit_dict)

required input:

mass in amu frequency in meV

get_phonon_hamiltonian(velocity=None, mass=None, coordinate=None, omega2=None)

angular_property(mass, coords, props)

get_boltzmann_beta(temperature)

class harmonic_oscillator(key={}, **kwargs)

Bases: object

Harmonic oscillator class.

euler_step(force)

Simple Euler integration step.

get_energy(velocity, mass=None, coordinate=None, omega2=None)

Calculate the total energy.

get_kinetic_energy(velocity, mass=None)

Calculate the kinetic energy and temperature.

get_potential_energy(mass=None, coordinate=None, omega2=None)

Calculate the potential energy.

init_coordinate_velocity(n_site=None, init_method=None)

Generate the initial oscillator coordinate and velocity.

Parameters:

• n_site (int, optional) – Total number of molecular sites.

• init_method (str, optional) – Initialization method. 'thermo' uses the Boltzmann distribution at init_temp.

leapfrog_step(force)

Leapfrog integration step.

recursive_exploration_step(force, force_func, **kwargs)

Recursive exploration integration step.

update_coordinate_velocity(force, half=1, **kwargs)

Update the oscillator coordinate and velocity, as well as the energy.

Parameters:

• force (numpy.ndarray) – Force acting on the oscillator.

• half (int) – 1 or 2, indicating the first or second half of the update.

Returns:

Projected force after the update, only for half=2.

Return type:

numpy.ndarray

velocity_verlet_step(force, half)

Velocity Verlet integration step.

remove_trans_rotat_force(force, mass, coords)

Remove the translational and rotational components from the force.

Parameters:

• force (ndarray) – The forces acting on the particles (shape: (n_particles, 3)).

• mass (ndarray) – The masses of the particles (shape: (n_particles,)).

• coords (ndarray) – The coordinates of the particles (shape: (n_particles, 3)).

Returns:

The projected forces with translational and rotational components removed.

Return type:

force (ndarray)

remove_trans_rotat_velocity(velocity, mass, coords)

Remove the translational and rotational components from the velocity.

Parameters:

• velocity (ndarray) – The velocities of the particles (shape: (n_particles, 3)).

• mass (ndarray) – The masses of the particles (shape: (n_particles,)).

• coords (ndarray) – The coordinates of the particles (shape: (n_particles, 3)).

Returns:

The projected velocities with translational and rotational components removed.

Return type:

velocity (ndarray)

lumeq.dynamics.photon_dynamics module

class PhotonStep(key, **kwargs)

Bases: object

get_initial_density(ntot, ns)

update_density(molecular_dipole, dt, half=1)

class PhotonStep2(key={}, **kwargs)

Bases: harmonic_oscillator

convert_parameter_units(unit_dict)

get_minimim_displacement(molecular_dipole)

update_density(molecular_dipole, dt, half=1)

get_trans_amplitude(ntot, coupling=1.0, energy=None, vector=False)

lumeq.dynamics.process_exciton_parameters module

process_parameters(cif_file, n_cell, outfile_dir='./', nstate=2, npairs=50, center=0, debug=0)

Process the input parameters and get real parameters: on-site energies, transition dipoles, state couplings for dimers.

Parameters:

• cif_file (str) – The cif file name

• n_cell (list) – The number of unit cells in each direction [nx, ny, nz].

• outfile_dir (str) – The output file directory

• nstate (int) – The number of exciton states per site

• npairs (int) – The number of neighboring pairs to be included

• center (int) – The center site index needed to shift (0 for B, 1 for A)

• debug (int) – The debug level

Returns:

The unit cell information energy (numpy.ndarray): Exciton energies of each site in eV. coupling_j (numpy.ndarray): Exciton-exciton couplings between dimers in eV. dipole (numpy.ndarray): Transition dipole moments of two sites in au. neighbor_index (list): Neighbor-index list for each dimer. distances (numpy.ndarray): Distances between dimers in Angstrom. center_coords (numpy.ndarray): Center-of-mass coordinates of the sites in Angstrom.

Return type:

unit_cell (dict)

read_energy_coupling(outfile, nstate=2)

Read exciton energy and Coulomb coupling from the output file.

Parameters:

• outfile (str) – The q-chem output file name

• nstate (int) – The number of exciton states per site

Returns:

Exciton energies with shape (nstate,), exciton-exciton coupling matrix with shape (nstate, nstate), and transition dipoles with shape (2, nstate, 3).

Return type:

tuple

set_model(neighbor_index, distances, model='AB', n_cell=[10, 1, 1], r_cutoff=10, debug=0)

Pick the model parameters based on the model type.

Parameters:

• neighbor_index (list) – Neighbor-index list for each dimer.

• distances (numpy.ndarray) – Distances between dimers in Angstrom.

• model (str) – The model type, e.g., ‘AB’, ‘BC’, ‘ABAC’, ‘AB-C’, ‘any’

• n_cell (list) – The number of unit cells in each direction [nx, ny, nz].

• r_cutoff (float) – The cutoff distance in Angstrom (10, 17, 26)

• debug (int) – The debug level

Returns:

Cell indices based on the model. neighbor_index (list): Refined neighbor-index list based on the model.

Return type:

cells (numpy.ndarray)

sort_index(i, j, k, l, nx, ny, nz, ns)

Module contents