Functions

This section provides an overview of the available functions in the QuantumDNA package.

Load Default Parameters

load_defaults(filepath=None)[source]

Load default settings from a YAML file.

Parameters:

filepathstr, optional: Path to the YAML file containing default settings. If None, the function loads the defaults from ‘defaults.yaml’ in the qDNA directory.

Returns:

dict: Parsed contents of the YAML file as a dictionary.

load_lcao_param(param_id, filepath=None)[source]

Load Linear Combination of Atomic Orbitals (LCAO) parameters from a JSON file.

Parameters:

param_idstr: Identifier for the parameter file to load.
filepathstr, optional: Path to the JSON file. If not provided, the default path is constructed using DATA_DIR and the param_id.

Returns:

dict: Parsed JSON data containing the LCAO parameters.

load_tb_model_props(filepath=None)[source]

Load tight-binding model properties from a JSON file.

Parameters:

filepathstr, optional: Path to the JSON file containing the model properties. If None, defaults to the file “tb_models_props.json” in the DATA_DIR directory.

Returns:

dict: Dictionary containing the loaded model properties.

load_options(filepath=None)[source]

Load options from a JSON file.

Parameters:

filepathstr, optional: Path to the JSON file containing options. If None, defaults to ‘options.json’ in the DATA_DIR directory.

Returns:

dict: Dictionary containing the loaded options.

Load Molecular Structures

load_pdb(filepath)[source]

Load atomic data from a PDB file. Parses the ATOM and HETATM records in a PDB file and extracts relevant information such as atom type, residue, chain, residue ID, coordinates, and element type.

Parameters:

filepathstr: Path to the PDB file to be loaded.

Returns:

list of dict: A list of dictionaries, each containing atomic data with keys: ‘atom’, ‘residue’, ‘chain’, ‘res_id’, ‘x’, ‘y’, ‘z’, and ‘element’.

pdb_to_xyz(filepath, **kwargs)[source]

Converts a PDB file to XYZ format and writes the output to separate files for each base and backbone in the structure.

Parameters:

filepathstr: Path to the input PDB file.

Notes

Note

The function creates a directory named after the input file (without extension) to store the output XYZ files.
Each base and backbone is written to separate XYZ files.
Base indices are adjusted for the lower strand if applicable.

write_xyz(directory, base_id, elements, coordinates, info=None)[source]

Write atomic elements and coordinates to an XYZ file.

Parameters:

directorystr: The directory where the XYZ file will be saved.
base_idstr: The base name for the XYZ file.
elementslist of str: List of atomic element symbols.
coordinateslist of tuple: List of atomic coordinates as (x, y, z) tuples.

Returns:

None

load_xyz(filepath)[source]

Load atomic data from an XYZ file.

Parameters:

filepathstr: Path to the XYZ file.

Returns:

identifierstr: The identifier or comment line from the XYZ file.
atomslist of str: List of atomic symbols.
coordinateslist of tuple of float: List of atomic coordinates as (x, y, z) tuples.

Calculate Tight-Binding Parameters

calc_orbital_interaction(lcao_param, orbitals, orbitals_coordinates, connection_type)[source]

Calculate the interaction between two orbitals based on LCAO parameters.

Parameters:

lcao_paramdict: Dictionary containing Linear Combination of Atomic Orbitals (LCAO) parameters.
orbitalslist of str: List of orbital identifiers in the format “atom_orbital”.
orbitals_coordinatesndarray: Array of shape (2, 3) representing the coordinates of the two orbitals.
connection_typestr: Type of connection between the orbitals (e.g., covalent, ionic).

Returns:

float: The calculated orbital interaction value. Returns 0 if the distance between orbitals is zero.

calc_orbital_energy(lcao_param, orbital)[source]

Calculate the energy of a specified orbital using LCAO parameters.

Parameters:

lcao_paramdict: Dictionary containing LCAO parameters. Expected keys are in the format “E_<atom><orbital_type>”.
orbitalstr: Orbital identifier in the format “<atom>_<orbital_type>”.

Returns:

float: Energy of the specified orbital.

calc_H_intra(lcao_param, comp)[source]

Calculate the intra-base Hamiltonian matrix for a given component.

Parameters:

lcao_paramdict: Parameters for the Linear Combination of Atomic Orbitals (LCAO) model.
compobject: Component containing orbital information.

Returns:

np.ndarray: Intra-base Hamiltonian matrix of shape (n, n), where n is the number of orbitals in the component.

calc_H_inter(lcao_param, comp1, comp2)[source]

Calculate the interbase Hamiltonian matrix for two components.

Parameters:

lcao_paramdict: Parameters for the Linear Combination of Atomic Orbitals (LCAO) method.
comp1object: First component containing orbital information and coordinates.
comp2object: Second component containing orbital information and coordinates.

Returns:

np.ndarray: A 2D array representing the interbase Hamiltonian matrix.

Save and Load Tight-Binding Parameters

save_tb_params(tb_params, source, tb_model_name, directory=None, unit='meV', notes=None, override=False)[source]

Save tight-binding parameters to a JSON file and update metadata.

Parameters:

tb_paramsdict: Dictionary containing tight-binding parameters.
sourcestr: Identifier for the source of the parameters.
tb_model_namestr: Name of the tight-binding model.
directorystr, optional: Directory to save the JSON file. Defaults to a subdirectory in DATA_DIR.
unitstr, optional: Unit of the parameters. Defaults to “meV”.
notesstr, optional: Additional notes about the parameters. Defaults to “No notes provided.”
overridebool, optional: Whether to override the file if it already exists. Defaults to False.

Returns:

None

load_tb_params(source, tb_model_name, directory=None, load_metadata=False)[source]

Load tight-binding parameters from a JSON file.

Parameters:

sourcestr: The source identifier for the parameters.
tb_model_namestr: The name of the tight-binding model.
directorystr, optional: The directory containing the parameter files. Defaults to a subdirectory within DATA_DIR named “tb_params”.
load_metadatabool, optional: If True, returns both data and metadata. Defaults to False.

Returns:

dict or tuple: If load_metadata is False, returns the parameter data as a dictionary. If load_metadata is True, returns a tuple containing the data dictionary and metadata dictionary.

delete_tb_params(source, tb_model_name, directory=None)[source]

Deletes a tight-binding parameter file.

Parameters:

sourcestr: The source identifier for the parameter file.
tb_model_namestr: The name of the tight-binding model.
directorystr, optional: The directory containing the parameter files. Defaults to a subdirectory ‘tb_params’ within DATA_DIR.

Returns:

bool: True if the file was successfully deleted, False otherwise.

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.

get_tb_basis(tb_dims)[source]

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)']

get_eh_basis(tb_dims)[source]

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)')]

get_eh_distance(eh_basis)[source]

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.        ])

get_particle_eh_states(particle, tb_basis_element, tb_basis)[source]

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)')]

basis_change(matrix, states, liouville=False)[source]

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.

local_to_global(matrix, eigs, liouville=False)[source]

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.

global_to_local(matrix, eigs, liouville=False)[source]

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

get_tb_couplings(tb_model_name, num_sites_per_strand)[source]

Generate tight-binding couplings for a specified model and strand size.

Parameters:

tb_model_namestr: Name of the tight-binding model. Supported values are: “WM”, “LM”, “ELM”, “FWM”, “FLM”, “FELM”, “TC”, “FC”.
num_sites_per_strandint: Number of sites per strand in the model.

Returns:

list: A list of coupling definitions, where each coupling is represented as a list containing the coupling type and site indices.

Raises:

ValueError: If an unknown tight-binding model name is provided.

get_tb_energies(num_channels, num_sites_per_strand)[source]

Generate a list of tight-binding energy configurations.

Parameters:

num_channelsint: The number of channels in the system.
num_sites_per_strandint: The number of sites per strand.

Returns:

list: A list of energy configurations, where each configuration is represented as a list containing a string identifier “E” and two tuples indicating the channel and site indices.

get_tb_config(tb_model_name, tb_dims)[source]

Generate the tight-binding configuration for a given model and dimensions.

Parameters:

tb_model_namestr: Name of the tight-binding model.
tb_dimstuple: A tuple containing the number of channels and the number of sites per strand.

Returns:

list: A list containing the tight-binding energies and couplings.

Tight-Binding Hamiltonian

set_matrix_element(matrix, tb_value, new_state, old_state, basis)[source]

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.]])

tb_ham_1P(tb_dims, tb_config, tb_basis, tb_param_dict, tb_basis_sites_dict)[source]

Constructs the particle tight-binding Hamiltonian matrix.

Parameters:

tb_dimsTuple[int, int]: Dimensions of the tight-binding model grid.
tb_configList[Tuple[str, str, str]]: Configuration of tight-binding connections.
tb_basisList[str]: List of basis states.
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_dims = (2, 2)
>>> tb_config = [("C", "(0, 0)", "(1, 0)"), ("E", "(0, 0)", "(0, 0)")]
>>> tb_basis = ["(0, 0)", "(1, 0)", "(0, 1)", "(1, 1)"]
>>> tb_param_dict = {"E_G": 1.0, "C_G_C": 0.5}
>>> tb_basis_sites_dict = {"(0, 0)": "G", "(1, 0)": "C"}
>>> tb_ham_1P(tb_dims, tb_config, tb_basis, tb_param_dict, tb_basis_sites_dict)
array([[1. , 0.5, 0. , 0. ],
       [0.5, 0. , 0. , 0. ],
       [0. , 0. , 0. , 0. ],
       [0. , 0. , 0. , 0. ]])

tb_ham_2P(tb_dims, tb_config, tb_basis, tb_params, tb_basis_sites_dict)[source]

Constructs the electron-hole tight-binding Hamiltonian matrix.

Parameters:

tb_dimsTuple[int, int]: Dimensions of the tight-binding model grid.
tb_configList[Tuple[str, str, str]]: Configuration of tight-binding connections.
tb_basisList[str]: List of basis states.
tb_paramsDict[str, Dict[str, float]]: Dictionary containing electron, hole, and optionally 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.

add_groundstate(matrix)[source]

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.]])

delete_groundstate(matrix)[source]

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.]])

add_interaction(matrix, eh_basis, interaction_param, interaction_type, nn_cutoff=False)[source]

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].

debye_spectral_density(omega, cutoff_freq, reorg_energy)[source]

Calculates the Debye spectral density.

Parameters:

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

Returns:

float: Debye spectral density.

ohmic_spectral_density(omega, cutoff_freq, reorg_energy, exponent)[source]

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.

bose_einstein_distrib(omega, temperature)[source]

Calculates the Bose-Einstein distribution.

Parameters:

omegafloat: Frequency.
temperaturefloat: Temperature.

Returns:

float: Bose-Einstein distribution.

dephasing_rate(cutoff_freq, reorg_energy, temperature)[source]

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

get_relax_op(tb_basis, tb_site)[source]

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

Parameters:

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

Returns:

qutip.Qobj: Relaxation operator as a Qobj instance.

get_glob_therm_op(eigs, eigenstate_i, eigenstate_j, relaxation, matrix_dim)[source]

Generate a global thermalizing operator.

Parameters:

eigsnp.ndarray: Eigensystem of the Hamiltonian.
eigenstate_iint: Index of the initial eigenstate.
eigenstate_jint: Index of the final eigenstate.
relaxationbool: Flag indicating whether relaxation effects are included.
matrix_dimint: Dimension of the matrix representing the system.

Returns:

qutip.Qobj: A global thermalizing operator in the form of a Qobj.

get_glob_therm_ops(eigv, eigs, relaxation, **kwargs)[source]

Generate global thermalizing operators.

Parameters:

eigvnp.ndarray: Eigenvalues of the system Hamiltonian.
eigsnp.ndarray: Eigenvectors of the system Hamiltonian.
relaxationbool: Flag for relaxation.

Returns:

list: List of global thermalizing operators.

get_loc_therm_op(eigv, eigs, unique, site_m, relaxation, matrix_dim)[source]

Generate a local thermalizing operator.

Parameters:

eigvnp.ndarray: Eigenvalues of the system Hamiltonian.
eigsnp.ndarray: Eigenvectors of the system Hamiltonian.
uniquefloat: Unique frequency gap corresponding to the transition.
site_mint: Index of the local site where the operator acts.
relaxationbool: Flag indicating whether relaxation effects are included.
matrix_dimint: Dimension of the matrix representing the system.

Returns:

qutip.Qobj: A local thermalizing operator in the form of a Qobj.

get_loc_therm_ops(eigv, eigs, relaxation, **kwargs)[source]

Generate local thermalizing operators.

Parameters:

eigvnp.ndarray: Eigenvalues of the system Hamiltonian.
eigsnp.ndarray: Eigenvectors of the system Hamiltonian.
relaxationbool: Flag indicating whether relaxation effects are included.

Returns:

list: List of local thermalizing operators as Qobj instances.

get_loc_deph_ops(tb_basis, description, dephasing_dict, relaxation)[source]

Generate a list of local dephasing collapse operators.

This function creates local dephasing operators based on the provided tight-binding basis, system description, dephasing rates, and relaxation flag.

Parameters:

tb_basislist: List representing the tight-binding basis states.
descriptionobject: Descriptor object containing structural information about the system.
dephasing_dictdict: Dictionary mapping particle identifiers to their respective dephasing rates.
relaxationbool: If True, the ground state is included in the operators.

Returns:

list: A list of local dephasing operators as Qobj instances.

get_glob_deph_ops(eigs, dephasing_rate, relaxation)[source]

Generate a list of global dephasing collapse operators.

This function creates \(N^2\) operators, where \(N\) is the number of eigenstates.

Parameters:

eigsnp.ndarray: Array representing the eigensystem of the Hamiltonian.
dephasing_ratefloat: The rate of dephasing applied to the system.
relaxationbool: If True, the ground state is included in the operators.

Returns:

list: A list containing the global dephasing operators as Qobj instances.

Reduced Density Matrix

get_reduced_dm(dm, particle, tb_basis)[source]

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)
>>> tb_basis = ['(0, 0)', '(1, 0)']
>>> get_reduced_dm(dm, 'electron', tb_basis)
array([[1.+0.j, 0.+0.j],
       [0.+0.j, 1.+0.j]])

get_reduced_dm_eigs(eigs, eigenstate_idx, tb_basis, particle)[source]

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

Parameters:

eigsnp.ndarray: The eigenvectors of the Hamiltonian.
eigenstate_idxint: The index of the eigenstate to reduce.
tb_basisList[str]: The list of tight-binding site basis states.
particlestr: The type of particle (‘electron’ or ‘hole’).

Returns:

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

Observables

get_tb_observable(tb_basis, start_state, end_state)[source]

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.]])

get_eh_observable(tb_basis, particle, start_state, end_state)[source]

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.]])

get_pop_observable(tb_basis, description, particle, state)[source]

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.]])

get_coh_observable(tb_basis, description, particle, state1, state2)[source]

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

get_therm_eq_state(me_solver)[source]

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.

get_deph_eq_state(me_solver)[source]

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.

Unit Conversion

get_conversion(start_unit, end_unit)[source]

Converts a value from the start_unit to the end_unit.

Parameters:

start_unitstr: The unit to convert from.
end_unitstr: The unit to convert to.

Returns:

float: The conversion factor between the two units.

Examples

>>> 1/get_conversion("100meV", "rad/fs").

get_conversion_dict(param_dict, start_unit, end_unit)[source]

Convert the values in a dictionary from one unit to another.

Parameters:

param_dictdict: Dictionary containing the parameters to be converted. Keys are parameter names and values are the parameter values.
start_unitstr: The unit of the input values in param_dict.
end_unitstr: The unit to which the values in param_dict should be converted.

Returns:

dict: A new dictionary with the same keys as param_dict, but with values converted to end_unit.

Hamiltonian Analysis

calc_average_pop(eigs, init_state, end_state)[source]

Calculates the time-averaged/ static population of the end state when initially in the initial state.

Parameters:

eigsnp.ndarray: Eigenvector matrix.
init_stateint: Initial state in the basis.
end_stateint: End state in the basis.

Returns:

float: The static population of the end state.

calc_amplitudes(eigs, init_state, end_state)[source]

Calculates the amplitudes for transitions between states.

Parameters:

eigsnp.ndarray: Eigenvector matrix.
init_stateint: Initial state in the basis.
end_stateint: End state in the basis.

Returns:

np.ndarray: A list of amplitudes for transitions.

calc_frequencies(eigv)[source]

Calculates the frequencies corresponding to energy level differences.

Parameters:

eigvnp.ndarray: Eigenvalue vector.

Returns:

np.ndarray: A list of frequencies.

get_pop_fourier(t, average_pop, amplitudes, frequencies)[source]

Calculates the population using Fourier series.

Parameters:

tfloat: Time variable.
average_popfloat: Average population.
amplitudesnp.ndarray: Amplitudes for transitions.
frequenciesnp.ndarray: Frequencies corresponding to energy level differences.

Returns:

float: The population at time t.

calc_ipr_hamiltonian(eigs)[source]

Calculates the inverse participation ratio (IPR) for each eigenstate of the Hamiltonian.

Parameters:

eigsnp.ndarray: Eigenvector matrix.

Returns:

list of float: The IPR values for each eigenstate.

Notes

Note

The IPR is a measure of the localization of an eigenstate. It is defined as the sum of the squared coefficients of the eigenvector. The IPR ranges from 1 to N, where N is the dimension of the Hilbert space. The IPR values can be used to distinguish between localized and delocalized eigenstates.

\[\mathrm{IPR} = 1/\sum_{i=1}^{N} |c_i|^4.\]

Localized state: \(\mathrm{IPR} = 1/N\)
Delocalized coherent state: \(\mathrm{IPR} = N\)

Density Matrix Analysis

calc_trace_distance(dm_1, dm_2)[source]

Calculate the trace distance between two density matrices. The trace distance is a measure of the distinguishability between two quantum states represented by their density matrices. It is defined as half the trace of the absolute difference between the two density matrices.

Parameters:

dm_1numpy.ndarray: The first density matrix.
dm_2numpy.ndarray: The second density matrix.

Returns:

float: The trace distance between the two density matrices.

Raises:

ValueError: If the density matrices do not have the same shape.

calc_purity(dm)[source]

Calculates the purity of a density matrix.

Parameters:

dmnp.ndarray: Density matrix.

Returns:

float: The purity of the density matrix.

calc_coherence(dm)[source]

Calculates the coherence (absolute sum of the off-diagonals) of a density matrix.

Parameters:

dmnp.ndarray: Density matrix.

Returns:

float: The coherence of the density matrix.

calc_ipr_dm(dm)[source]

Calculate the inverse participation ratio (IPR) of a density matrix.

Parameters:

dmnp.ndarray: The density matrix for which the IPR is calculated. Should be a square, complex-valued matrix.

Returns:

float: The inverse participation ratio of the density matrix, providing an indication of state localization.

Notes

Note

The IPR provides a measure of the localization of a quantum state

\[\mathrm{IPR} = \frac{\left( \sum_{i,j} |\rho_{i,j}| \right)^2}{N \sum_{i,j} |\rho_{i,j}|^2}\]

Localized state: \(IPR = 1/N\), where N is the dimension of the density matrix.
Delocalized (coherent) state: \(IPR = N\), indicating full coherence.
Maximally mixed state: \(IPR = 1\), representing maximal mixing.

Evaluation

evaluate_pdb(directory_pdb, start_site_idx, end_site_idx, tb_model_name='ELM')[source]

Evaluates PDB files within a specified directory and calculates results.

Parameters:

directory_pdbstr: Path to the directory containing PDB files.
start_site_idxint: Starting index for slicing the sites.
end_site_idxint: Ending index for slicing the sites.
tb_model_namestr, optional: Name of the tight-binding model (default is ‘ELM’).

Returns:

None: Results are saved to a JSON file in the specified directory.