Functions

Calculate Tight-Binding Parameters

qDNA.lcao.calc_orbital_energy(orbital)

Calculate the energy of a given orbital.

Parameters:

orbitalOrbital: An instance of the Orbital class containing information about the atom and orbital type.

Returns:

float: The energy of the specified orbital.

qDNA.lcao.calc_orbital_overlap(orbital1, orbital2, connection)

Calculate the overlap between two orbitals using the Harrison expression and the Slater-Koster two-center interactions.

Parameters:

orbital1Orbital: The first orbital object containing its coordinates, atom type, orbital type, and atom identifier.
orbital2Orbital: The second orbital object containing its coordinates, atom type, orbital type, and atom identifier.
connectionstr: The type of connection between the orbitals, either “interbase” or “intrabase”.

Returns:

float: The calculated overlap between the two orbitals. Returns 0 if the distance between orbitals is zero, if the orbitals belong to the same atom in an intrabase connection, or if the distance exceeds the cutoff radius.

Notes

Note

The directional cosines are used as projections on the coordinate axis rather than actual cosine values. The function includes a hydrogen correction factor obtained by optimization.

qDNA.lcao.load_xyz(filename, directory='/home/docs/checkouts/readthedocs.org/user_builds/quantumdna/checkouts/v0.1.10/docs')

Load atomic coordinates from an XYZ file.

Parameters:

filenamestr: The name of the XYZ file (without the .xyz extension).
directorystr, optional: The directory where the XYZ file is located. Default is a subdirectory “geometries” within DATA_DIR.

Returns:

tuple: A tuple containing the identifier from the second line of the XYZ file and a DataFrame containing the atomic coordinates with columns [“Atom”, “X”, “Y”, “Z”].

Notes

Note

The XYZ file is expected to have the following format: - The first line contains the number of atoms (ignored). - The second line contains a comment or identifier. - Subsequent lines contain atomic coordinates in the format: Atom X Y Z.

qDNA.lcao.convert_json_to_xyz(filename, directory)

Converts a JSON file to an XYZ file, e.g., from Pubchem https://pubchem.ncbi.nlm.nih.gov/.

Parameters:

filenamestr: The name of the JSON file (without extension) to be converted.
directorystr: The directory where the JSON file is located and where the XYZ file will be saved.

Raises:

FileNotFoundError: If the JSON file does not exist in the specified directory.
KeyError: If the expected keys are not found in the JSON file.
ValueError: If the JSON file contains invalid data.

Notes

Note

The JSON file is expected to follow a specific structure with atomic data under “PC_Compounds” -> “atoms” and coordinates under “coords” -> “conformers”. The atomic symbols are mapped from atomic numbers using a predefined dictionary. The JSON file is removed after conversion.

Examples

>>> convert_json_to_xyz("molecule", "/path/to/directory")
File successfully converted and saved at /path/to/directory/molecule.xyz

qDNA.lcao.convert_pdb_to_xyz(filepath_pdb)

Converts a PDB file to multiple XYZ files, one for each base.

Parameters:

filepath_pdbstr: The path to the input PDB file.

Notes

Note

Information about the atomic elements and coordinates is extracted from the PDB file. - The function creates a directory named after the input PDB file (without extension) to store the generated XYZ files. - Each base in the PDB file is written to a separate XYZ file. - If the chain identifier changes, the base numbering is adjusted to continue from the previous chain’s last base number. - The function assumes that the base counter starts from one if the chain changes. - The function prints the directory where the XYZ files are created if the verbose mode is enabled in the DEFAULTS dictionary.

qDNA.lcao.calc_tb_energies_monomers(directory)

Calculate the tight-binding energies for monomers in a given directory. This function searches for XYZ files in the specified directory, loads the data, and calculates the HOMO and LUMO energies for each monomer. The results are returned as dictionaries.

Parameters:

directorystr: The directory containing the XYZ files.

Returns:

HOMO_dictdict: A dictionary where the keys are identifiers of the form ‘E_<base_identifier>’ and the values are the HOMO energies in eV rounded to two decimal places.
LUMO_dictdict: A dictionary where the keys are identifiers of the form ‘E_<base_identifier>’ and the values are the LUMO energies in eV rounded to two decimal places.

qDNA.lcao.calc_tb_params_dimer(bases, tb_model_name, double_stranded=True)

Calculate tight-binding (TB) parameters for a dimer in meV.

Parameters:

baseslist: List of base objects representing the bases in the dimer.
tb_model_namestr: Name of the tight-binding model. Can be “WM”, “LM”, or “ELM”.
double_strandedbool, optional: Flag indicating whether the dimer is double-stranded (default is True).

Returns:

tuple: A tuple containing two dictionaries: - HOMO_dict: Dictionary with HOMO (Highest Occupied Molecular Orbital) parameters. - LUMO_dict: Dictionary with LUMO (Lowest Unoccupied Molecular Orbital) parameters.

Raises:

AssertionError: If tb_model_name is not “WM” for single-stranded mode. If the length of bases is not 2 for single-stranded mode.

qDNA.lcao.calc_tb_params(directories, tb_model_name, double_stranded=True)

Calculate tight-binding parameters in meV for a set of DNA base pairs.

Parameters:

directorieslist of str: List of directories containing the XYZ files for the DNA bases.
tb_model_namestr: Name of the tight-binding model to be used.
double_strandedbool, optional: If True, consider the DNA as double-stranded. If False, consider it as single-stranded. Default is True.

Returns:

HOMO_dictdict: Dictionary containing the Highest Occupied Molecular Orbital (HOMO) parameters for each dimer.
LUMO_dictdict: Dictionary containing the Lowest Unoccupied Molecular Orbital (LUMO) parameters for each dimer.

Save and Load Tight-Binding Parameters

qDNA.hamiltonian.save_tb_params(tb_params, metadata, directory)

Save tight-binding parameters to a file.

Parameters:

tb_paramsdict: Dictionary containing the tight-binding parameters.
metadatadict: Dictionary with metadata, e.g., source, particle, and tb_model_name.
directorystr, optional: Directory to save the file, by default data/raw/tb_params.

Examples

>>> save_tb_params({"t_AB": 5, "t_AC": 3, "t_BC": -2}, {"source": "author2024", "particle": "particle", "tb_model_name": "model"}, "delete_this_folder")

qDNA.hamiltonian.load_tb_params(metadata, directory, load_metadata=False)

Load tight-binding parameters from a file.

Parameters:

metadatadict: Dictionary with metadata, e.g., source, particle, and tb_model_name.
directorystr, optional: Directory to load the file from, by default data/raw/tb_params.
load_metadatabool, optional: Whether to load metadata along with the parameters, by default False.

Returns:

dict: Loaded tight-binding parameters.

Examples

>>> load_tb_params({"source": "author2024", "particle": "particle", "tb_model_name": "model"}, "delete_this_folder", load_metadata=False)

qDNA.hamiltonian.wrap_save_tb_params(tb_params, source, particle, tb_model_name, unit=None, notes=None)

Wrapper function for save_tb_params().

Parameters:

tb_paramsdict: Dictionary containing the tight-binding parameters.
sourcestr: Source of the parameters, e.g., Hawke2010.
particlestr: Type of particle, e.g., electron, hole, exciton.
tb_model_namestr: Name of the tight-binding model.
unitstr, optional: The unit of the parameters.
notesstr, optional: Additional notes to include in the info_dict, by default None.

Examples

>>> wrap_save_tb_params({"t_AB": 5, "t_AC": 3, "t_BC": -2}, "author2024", "particle", "model", "delete_this_folder")

qDNA.hamiltonian.wrap_load_tb_params(source, particle, tb_model_name, load_metadata=False)

Wrapper function for load_tb_params().

Parameters:

sourcestr: Source of the parameters, e.g., Hawke2010.
particlestr: Type of particle, e.g., electron, hole, exciton.
tb_model_namestr: Name of the tight-binding model.
load_metadatabool, optional: Whether to load metadata along with the parameters, by default False.

Returns:

dict: Loaded tight-binding parameters.

Examples

>>> wrap_load_tb_params("author2024", "particle", "model", load_metadata=False)

Tight-Binding Basis

There are three relevant bases:

The tight-binding basis or one-particle basis, which is the basis in which the tight-binding Hamiltonian is defined.
The electron-hole basis or two-particle basis, which is the basis in which the electron-hole states are defined.
The eigenstate basis, which is the basis in which the Hamiltonian is diagonal.

The first two are refered to as local bases, the third as the global basis. The functions below define these bases and allow to change between them.

qDNA.model.get_tb_basis(tb_dims)

Generates a symbolic string representation of the indices ‘(i, j)’ where i indicates the strand number and j the site number inside the strand.

Parameters:

tb_dims: tuple: A tuple (num_strands, num_sites_per_strand) representing the tight-binding dimensions.

Returns:

list: List of string representations of site indices.

Examples

>>> get_tb_basis((2, 2))
['(0, 0)', '(0, 1)', '(1, 0)', '(1, 1)']

qDNA.model.get_eh_basis(tb_dims)

Generates a symbolic string representation of electron-hole basis indices.

Parameters:

tb_dims: tuple: A tuple (num_strands, num_sites_per_strand) representing the tight-binding dimensions.

Returns:

list: List of tuples representing electron-hole basis indices.

Examples

>>> get_eh_basis((2, 2))
[('(0, 0)', '(0, 0)'), ('(0, 0)', '(0, 1)'), ('(0, 0)', '(1, 0)'), ('(0, 0)', '(1, 1)'),
 ('(0, 1)', '(0, 0)'), ('(0, 1)', '(0, 1)'), ('(0, 1)', '(1, 0)'), ('(0, 1)', '(1, 1)'),
 ('(1, 0)', '(0, 0)'), ('(1, 0)', '(0, 1)'), ('(1, 0)', '(1, 0)'), ('(1, 0)', '(1, 1)'),
 ('(1, 1)', '(0, 0)'), ('(1, 1)', '(0, 1)'), ('(1, 1)', '(1, 0)'), ('(1, 1)', '(1, 1)')]

qDNA.model.get_eh_distance(eh_basis)

Calculates the distance between electron and hole for each state in the basis (in multiples of the lattice spacing).

Parameters:

eh_basis: list: List of electron and hole positions as tuples of strings.

Returns:

ndarray: Array of distances between electron and hole for each state.

Examples

>>> get_eh_distance([('(0, 0)', '(1, 1)'), ('(1, 0)', '(0, 0)')])
array([1.41421356, 1.        ])

qDNA.model.get_particle_eh_states(particle, tb_basis_element, tb_basis)

Generates a list of electron-hole states for a given particle and site basis element.

Parameters:

particle: str: The type of particle (‘electron’, ‘hole’, or ‘exciton’).
tb_basis_element: str: The site basis element for which to generate the states.
tb_basis: list: The list of all site basis elements.

Returns:

list: List of tuples representing the electron-hole states.

Examples

>>> get_particle_eh_states('electron', '(0, 2)', get_tb_basis((1,3)))
[('(0, 2)', '(0, 0)'), ('(0, 2)', '(0, 1)'), ('(0, 2)', '(0, 2)')]

qDNA.model.basis_change(matrix, states, liouville=False)

Performs a basis change of the given matrix.

Parameters:

matrix: ndarray: The matrix to change basis.
states: ndarray: The old basis expressed as a vector in the new basis.
liouville: bool: Set to True for an open quantum system. The matrix must have dimension \(N^2\) instead of \(N\).

Returns:

ndarray: Matrix in the new basis.

qDNA.model.local_to_global(matrix, eigs, liouville=False)

Performs a basis change from the site basis to the eigenbasis.

Parameters:

matrix: ndarray: The matrix to change basis.
eigs: ndarray: The site basis (old) expressed in the eigenbasis (new).
liouville: bool: Set to True for an open quantum system. The matrix must have dimension \(N^2\) instead of \(N\).

Returns:

ndarray: Matrix in the eigenbasis.

qDNA.model.global_to_local(matrix, eigs, liouville=False)

Performs a basis change from the eigenbasis to the site basis.

Parameters:

matrix: ndarray: The matrix to change basis.
eigs: ndarray: The eigenbasis (old) expressed in the site basis (new).
liouville: bool: Set to True for an open quantum system. The matrix must have dimension \(N^2\) instead of \(N\).

Returns:

ndarray: Matrix in the site basis.

Tight-Binding Configuration

qDNA.model.get_tb_config(tb_model_name, tb_dims)

Get the tight-binding configuration for a specified model.

Parameters:

tb_model_namestr: The name of the tight-binding model.
tb_dimstuple: The dimensions of the model (number of strands, number of sites per strand).

Returns:

list of tuple: The configuration of the specified tight-binding model.

Examples

>>> get_tb_config("WM", (1, 3))
[('E', '(0, 0)', '(0, 0)'),
('E', '(0, 1)', '(0, 1)'),
('E', '(0, 2)', '(0, 2)'),
('t', '(0, 1)', '(0, 0)'),
('t', '(0, 2)', '(0, 1)')]

DNA sequences

qDNA.create_upper_strands(num_dna_bases, dna_bases)

Generate all possible upper DNA strands of a given length using specified DNA bases.

Parameters:

num_dna_basesint: The number of DNA bases in each strand.
dna_baseslist of str: A list of DNA bases to use for generating the strands.

Returns:

list of str: A list containing all possible upper DNA strands of the specified length.

Raises:

AssertionError: If any element of dna_bases is not in the configured DNA bases.

Tight-Binding Hamiltonian

qDNA.hamiltonian.set_matrix_element(matrix, tb_value, new_state, old_state, basis)

Sets the matrix element for the Hamiltonian matrix ensuring hermiticity.

Parameters:

matrixnp.ndarray: The Hamiltonian matrix.
tb_valuefloat: The tight-binding value to set.
new_statestr: The new state in the basis.
old_statestr: The old state in the basis.
basisList[str]: The list of basis states.

Returns:

np.ndarray: The updated Hamiltonian matrix.

Examples

>>> set_matrix_element(np.zeros((2, 2)), 1, "(0, 0)", "(1, 0)", ["(0, 0)", "(1, 0)"])
array([[0., 1.],
       [1., 0.]])

qDNA.hamiltonian.tb_ham_1P(tb_model, tb_param_dict, tb_basis_sites_dict)

Constructs the particle tight-binding Hamiltonian matrix.

Parameters:

tb_modelTBModelType: The tight-binding model.
tb_param_dictDict[str, float]: Dictionary of tight-binding parameters.
tb_basis_sites_dictDict[str, str]: Dictionary mapping the TB basis to the TB sites.

Returns:

np.ndarray: The tight-binding Hamiltonian matrix.

Examples

>>> tb_model = TB_Model("model_name", (2, 2))
>>> tb_param_dict = {"E_G": 1.0, "C_GC": 0.5}
>>> tb_basis_sites_dict = {"(0, 0)": "G", "(1, 0)": "C"}
>>> tb_ham_1P(tb_model, tb_param_dict, tb_basis_sites_dict)
array([[1. , 0.5],
       [0.5, 1. ]])

qDNA.hamiltonian.tb_ham_2P(tb_model, tb_param_dict_electron, tb_param_dict_hole, tb_param_dict_exciton, tb_basis_sites_dict)

Constructs the electron-hole tight-binding Hamiltonian matrix.

Parameters:

tb_modelTBModelType: The tight-binding model.
tb_param_dict_electronDict[str, float]: Electron tight-binding parameters.
tb_param_dict_holeDict[str, float]: Hole tight-binding parameters.
tb_param_dict_excitonDict[str, float]: Exciton tight-binding parameters.
tb_basis_sites_dictDict[str, str]: Dictionary mapping the TB basis to the TB sites.

Returns:

np.ndarray: The electron-hole tight-binding Hamiltonian matrix.

Examples

>>> tb_model = TB_Model("model_name", (2, 2))
>>> tb_param_dict_electron = {"E_G": 1.0, "C_GC": 0.5}
>>> tb_param_dict_hole = {"E_G": 0.8, "C_GC": 0.4}
>>> tb_basis_sites_dict = {"(0, 0)": "G", "(1, 0)": "C"}
>>> tb_ham_2P(tb_model, tb_param_dict_electron, tb_param_dict_hole, tb_basis_sites_dict)
array([[1.5, 0.5, 0.4, 0. ],
       [0.5, 1. , 0. , 0. ],
       [0.4, 0. , 1.3, 0.5],
       [0. , 0. , 0.5, 0.8]])

qDNA.hamiltonian.add_groundstate(matrix)

Adds a dimension to the matrix to include the ground state.

Parameters:

matrixnp.ndarray: Input matrix.

Returns:

np.ndarray: Matrix with an additional dimension for the ground state.

Examples

>>> add_groundstate(np.array([[1, 2], [3, 4]]))
array([[0., 0., 0.],
       [0., 1., 2.],
       [0., 3., 4.]])

qDNA.hamiltonian.delete_groundstate(matrix)

Removes the ground state dimension from the matrix.

Parameters:

matrixnp.ndarray: Input matrix with ground state dimension.

Returns:

np.ndarray: Matrix without the ground state dimension.

Examples

>>> delete_groundstate(np.array([[0., 0., 0.], [0., 1., 2.], [0., 3., 4.]]))
array([[1., 2.],
       [3., 4.]])

qDNA.hamiltonian.add_interaction(matrix, eh_basis, interaction_param, interaction_type, nn_cutoff=False)

Adds interaction terms to the Hamiltonian based on the distance between electron and hole.

Parameters:

matrixnp.ndarray: The initial Hamiltonian matrix.
eh_basisList[Tuple[str, str]]: List of electron and hole positions as tuples of strings.
interaction_paramfloat: The interaction parameter.
interaction_typestr: The type of interaction. Either ‘Coulomb’ or ‘Exchange’.
nn_cutoffbool, optional: If True, only nearest neighbor interactions are considered.

Returns:

np.ndarray: Hamiltonian matrix with interaction terms added.

Notes

Note

This works only for a Hamiltonian without the additional basis element accounting for relaxation. Therefore the interaction should always be added before the relaxation.

Examples

>>> Hamiltonian = np.array([[0, 1], [1, 0]])
>>> eh_basis = [("(0, 0)", "(1, 1)"), ("(1, 0)", "(0, 0)")]
>>> add_interaction(Hamiltonian, eh_basis, 1.0, "Coulomb", True)
array([[0.        , 1.17639077],
       [1.17639077, 0.        ]])

Lindblad rates

These functions is adapted from the quantum_HEOM GitHub repository [Abb20].

qDNA.environment.debye_spectral_density(omega, cutoff_freq, reorg_energy)

Calculates the Debye spectral density.

Parameters:

omegafloat: Frequency.
cutoff_freqfloat: Cutoff frequency.
reorg_energyfloat: Reorganization energy.

Returns:

float: Debye spectral density.

qDNA.environment.ohmic_spectral_density(omega, cutoff_freq, reorg_energy, exponent)

Calculates the Ohmic spectral density.

Parameters:

omegafloat: Frequency.
cutoff_freqfloat: Cutoff frequency.
reorg_energyfloat: Reorganization energy.
exponentfloat: Specifies a sub- or superohmic bath.

Returns:

float: Ohmic spectral density.

qDNA.environment.bose_einstein_distrib(omega, temperature)

Calculates the Bose-Einstein distribution.

Parameters:

omegafloat: Frequency.
temperaturefloat: Temperature.

Returns:

float: Bose-Einstein distribution.

qDNA.environment.dephasing_rate(cutoff_freq, reorg_energy, temperature)

Calculates the dephasing rate in the limit of the Redfield rate equation as the frequency approaches zero.

Parameters:

cutoff_freqfloat: Cutoff frequency.
reorg_energyfloat: Reorganization energy.
temperaturefloat: Temperature.

Returns:

float: Dephasing rate.

Lindblad operators

qDNA.environment.get_relax_op(tb_basis, tb_site)

Annihilation operator of an exciton on a given tight-binding site. Relaxation of the DNA to its ground state.

Parameters:

tb_basislist: List of tight-binding site basis states.
tb_sitestr: Tight-binding site.

Returns:

qutip.Qobj: Relaxation operator.

qDNA.environment.get_glob_therm_op(eigs, eigenstate_i, eigenstate_j, relaxation, matrix_dim)

Global thermalizing operator.

Parameters:

eigsnp.ndarray: Eigensystem.
eigenstate_iint: Index of the initial eigenstate.
eigenstate_jint: Index of the final eigenstate.
relaxationbool: Flag for relaxation.
matrix_dimint: Dimension of the matrix.

Returns:

qutip.Qobj: Thermalizing operator.

qDNA.environment.get_glob_therm_ops(eigv, eigs, relaxation, deph_rate=7, cutoff_freq=20, reorg_energy=1, temperature=300, spectral_density='debye', exponent=1)

Generate global thermalizing operators.

Parameters:

eigvarray_like: Eigenvalues of the system Hamiltonian.
eigsarray_like: Eigenvectors of the system Hamiltonian.
relaxationfloat: Relaxation rate for the system.
deph_ratefloat, optional: Dephasing rate (default is 7).
cutoff_freqfloat, optional: Cutoff frequency for the spectral density (default is 20).
reorg_energyfloat, optional: Reorganization energy (default is 1).
temperaturefloat, optional: Temperature of the thermal bath (default is 300).
spectral_densitystr, optional: Type of spectral density function (default is “debye”).
exponentfloat, optional: Exponent for the spectral density function (default is 1).

Returns:

list: List of collapse operators for the Lindblad master equation.

qDNA.environment.get_loc_therm_op(eigv, eigs, unique, site_m, relaxation, matrix_dim)

Local thermalizing operator.

Parameters:

eigvnp.ndarray: Eigenvalues.
eigsnp.ndarray: Eigensystem.
uniquefloat: Unique frequency gap.
site_mint: Local site index.
relaxationbool: Flag for relaxation.
matrix_dimint: Dimension of the matrix.

Returns:

qutip.Qobj: Thermalizing operator.

qDNA.environment.get_loc_therm_ops(eigv, eigs, relaxation, deph_rate=7, cutoff_freq=20, reorg_energy=1, temperature=300, spectral_density='debye', exponent=1)

Generate local thermalizing operators.

Parameters:

eigvnp.ndarray: Eigenvalues.
eigsnp.ndarray: Eigensystem.
relaxationbool: Flag for relaxation.
deph_ratefloat: Dephasing rate.
cutoff_freqfloat: Cutoff frequency.
reorg_energyfloat: Reorganization energy.
temperaturefloat: Temperature in Kelvin.
spectral_densitystr: Type of spectral density.
exponentfloat: Exponent for Ohmic spectral density.

Returns:

list: List of thermalizing operators.

qDNA.environment.get_loc_deph_ops(tb_basis, dephasing_rate, relaxation)

Local dephasing operators. In total \(2N\) operators (where \(N\) is the number of tight-binding sites).

Parameters:

tb_basislist: List of tight-binding site basis states.
dephasing_ratefloat: Dephasing rate.
relaxationbool: Flag for relaxation.

Returns:

list: List of local dephasing operators.

qDNA.environment.get_glob_deph_ops(eigs, dephasing_rate, relaxation)

Global dephasing operators. In total \(N^2\) operators (where \(N\) is the number of eigenstates).

Parameters:

eigsnp.ndarray: Eigensystem.
dephasing_ratefloat: Dephasing rate.
relaxationbool: Flag for relaxation.

Returns:

list: List of global dephasing operators.

qDNA.environment.get_loc_deph_p_ops(tb_basis, dephasing_rate)

Local dephasing operators for particle description. In total \(N\) operators (where \(N\) is the number of tight-binding sites).

Parameters:

tb_basislist: List of tight-binding site basis states.
dephasing_ratefloat: Dephasing rate.

Returns:

list: List of local dephasing operators for particle description.

qDNA.environment.get_glob_deph_p_ops(eigs, dephasing_rate)

Global dephasing operators for particle description. In total \(N\) operators (where \(N\) is the number of eigenstates).

Parameters:

eigsnp.ndarray: Eigensystem.
dephasing_ratefloat: Dephasing rate.

Returns:

list: List of global dephasing operators for particle description.

Master Equation Solver

qDNA.dynamics.get_me_solver(upper_strand, tb_model_name, **kwargs)

Creates an instance of ME_Solver.

Parameters:

upper_strandstr: The upper strand of DNA sequence.
tb_model_namestr: The name of the tight-binding model.
kwargsdict: Additional keyword arguments for creating the ME_Solver instance.

Returns:

ME_Solver: An instance of ME_Solver.

Reduced Density Matrix

qDNA.dynamics.get_reduced_dm(dm, particle, tb_basis)

Reduces the density matrix for a specific particle type.

Parameters:

dmnp.ndarray: The initial density matrix.
particlestr: The type of particle (‘electron’ or ‘hole’).
tb_basisList[str]: The list of tight-binding site basis states.

Returns:

np.ndarray: The reduced density matrix for the specified particle.

Raises:

ValueError: If the particle type is not recognized.

Examples

>>> dm = np.eye(4)
>>> get_reduced_dm(dm, 'electron', ['(0, 0)', '(1, 0)'])
array([[2., 0.],
       [0., 2.]])

qDNA.dynamics.get_reduced_dm_eigs(tb_ham, particle, eigenstate_idx)

Reduces the density matrix of a selected eigenstate of the Hamiltonian for a specific particle type.

Parameters:

tb_hamTBHamType: The Hamiltonian object containing the matrix and site basis.
particlestr: The type of particle (‘electron’ or ‘hole’).
eigenstate_idxint: The index of the eigenstate.

Returns:

np.ndarray: The reduced density matrix.

Exciton Observables

qDNA.evaluation.calc_lifetime(upper_strand, tb_model_name, **kwargs)

Calculates the exciton lifetime in femtoseconds (fs).

Parameters:

upper_strandstr: The upper strand of DNA sequence.
tb_model_namestr: The name of the tight-binding model.
kwargsdict: Additional keyword arguments for the master equation solver.

Returns:

float or str: The exciton lifetime in femtoseconds, or a message indicating no relaxation in the given time.

Examples

>>> calc_lifetime("GCG", "ELM", relax_rate=3, unit="rad/ps")
775.5511022044088

qDNA.evaluation.calc_lifetime_dict(upper_strands, tb_model_name, filename, directory, num_cpu=None, **kwargs)

Calculates the exciton lifetime for multiple upper strands using multiprocessing.

Parameters:

upper_strandsList[str]: List of upper strands of DNA sequences.
tb_model_namestr: The name of the tight-binding model.
filenamestr: The filename to save the lifetime dictionary.
directorystr: The directory where the lifetime dictionary is located.
num_cpuint, optional: The number of CPU cores to use. Defaults to the total number of CPUs minus one.
kwargsdict: Additional keyword arguments for the master equation solver.

Returns:

Dict[str, float]: Dictionary containing the exciton lifetime for each upper strand.

qDNA.evaluation.calc_dipole(upper_strand, tb_model_name, average=True, **kwargs)

Calculates the average charge separation.

Parameters:

upper_strandstr: The upper strand of DNA sequence.
tb_model_namestr: The name of the tight-binding model.
averagebool: Indicates if the charge separation should be time-averaged.
kwargsdict: Additional keyword arguments for the master equation solver.

Returns:

float or List[float]: The average charge separation.

Examples

>>> calc_dipole("GCG", "ELM")
2.951734389657976

qDNA.evaluation.calc_dipole_wrapper(upper_strand, tb_model_name, lifetime_dict, **kwargs)

Calculates the average charge separation in the exciton lifetime.

Parameters:

upper_strandstr: The upper strand of DNA sequence.
tb_model_namestr: The name of the tight-binding model.
lifetime_dictDict[str, float]: Dictionary containing lifetimes for each upper strand.
kwargsdict: Additional keyword arguments for the master equation solver.

Returns:

float: The average charge separation during the exciton lifetime.

qDNA.evaluation.calc_dipole_dict(tb_model_name, filename, directory, num_cpu=None)

Calculates the average charge separation for multiple upper strands using multiprocessing.

Parameters:

tb_model_namestr: The name of the tight-binding model.
filenamestr: The filename to load the lifetime dictionary from.
directorystr: The directory where the lifetime dictionary is located.
num_cpuint, optional: The number of CPU cores to use. Defaults to the total number of CPUs minus one.

Returns:

Dict[str, float]: Dictionary containing the average charge separation for each upper strand.

Observables

qDNA.environment.get_tb_observable(tb_basis, start_state, end_state)

Wrapper function of get_observable. Creates a matrix element for the transition between a given start and end state in the provided basis.

Parameters:

tb_basisList[str]: The list of tight-binding site basis states.
start_statestr: The starting state.
end_statestr: The ending state.

Returns:

np.ndarray: The density matrix.

Examples

>>> get_tb_observable(['(0, 0)', '(0, 1)', '(0, 2)'], '(0, 1)', '(0, 2)')
array([[0., 0., 0.],
       [0., 0., 1.],
       [0., 0., 0.]])

qDNA.environment.get_eh_observable(tb_basis, particle, start_state, end_state)

Creates a electron-hole matrix element for the given particle type.

Parameters:

tb_basisList[str]: The list of tight-binding site basis states.
particlestr: The type of particle (‘electron’, ‘hole’, or ‘exciton’).
start_statestr: The starting state.
end_statestr: The ending state.

Returns:

np.ndarray: The electron-hole density matrix.

Raises:

ValueError: If the particle type is not recognized.

Examples

>>> get_eh_observable(['(0, 0)', '(1, 0)'], 'electron', '(0, 0)', '(1, 0)')
array([[0., 0., 1., 0.],
       [0., 0., 0., 1.],
       [0., 0., 0., 0.],
       [0., 0., 0., 0.]])

qDNA.environment.get_pop_particle(tb_basis, particle, state)

Creates the population observable for a specific particle and state.

Parameters:

tb_basisList[str]: The list of tight-binding site basis states.
particlestr: The type of particle (‘electron’, ‘hole’, or ‘exciton’).
statestr: The state of the particle.

Returns:

np.ndarray: The population density matrix.

Examples

>>> get_pop_particle(['(0, 0)', '(1, 0)'], 'electron', '(0, 0)')
array([[1., 0., 0., 0.],
       [0., 1., 0., 0.],
       [0., 0., 0., 0.],
       [0., 0., 0., 0.]])

qDNA.environment.get_coh_particle(tb_basis, particle, state1, state2)

Creates the coherence observable for a specific particle and pair of states.

Parameters:

tb_basisList[str]: The list of tight-binding site basis states.
particlestr: The type of particle (‘electron’, ‘hole’, or ‘exciton’).
state1str: The first state.
state2str: The second state.

Returns:

np.ndarray: The coherence density matrix.

Examples

>>> get_coh_particle(['(0, 0)', '(1, 0)'], 'electron', '(0, 0)', '(1, 0)')
array([[0., 0., 1., 0.],
       [0., 0., 0., 1.],
       [0., 0., 0., 0.],
       [0., 0., 0., 0.]])

Equilibrium states

qDNA.evaluation.get_therm_eq_state(me_solver)

Calculate the thermal equilibrium state.

Parameters:

me_solverobject: An instance of a master equation solver which contains the tight-binding Hamiltonian tb_ham and the Lindblad dissipation parameters lindblad_diss.

Returns:

numpy.ndarray: The thermal equilibrium state of the system. If the temperature is zero, returns the ground state. Otherwise, returns the thermal equilibrium state as a density matrix in the local basis.

Notes

Note

The function first checks if the temperature is zero. If so, it returns the ground state. For non-zero temperatures, it calculates the equilibrium values for each eigenvalue of the Hamiltonian, normalizes them, and transforms the resulting diagonal matrix to the local basis.

qDNA.evaluation.get_deph_eq_state(me_solver)

Calculate the dephasing equilibrium state.

Parameters:

me_solverobject: An instance of ME_Solver solver which contains the following attributes:

Returns:

numpy.ndarray: The dephasing equilibrium state as a density matrix.