Classes

Linear Combination of Atomic Orbitals

class Component(filepath, **kwargs)[source]

Bases: object

Represents a component of DNA, e.g. a nucleobase, the sugar-phosphate backbone, etc.

Attributes:

param_idstr: Identifier for the LCAO parameters.
lcao_paramdict: Loaded LCAO parameters.
num_atom_orbitalsdict: Number of orbitals for each atom type.
num_atom_electronsdict: Number of electrons for each atom type.
filepathstr: Path to the XYZ file.
xyz_idstr: Identifier for the XYZ file.
atomslist of str: List of atom types in the molecule.
atoms_coordinatesndarray: Array of atomic coordinates.
atoms_idlist of str: Unique identifiers for each atom.
num_atomsint: Total number of atoms in the molecule.
num_electronsint: Total number of electrons in the molecule.
orbitalslist of str: List of orbital identifiers.
orbitals_coordinatesndarray: Array of orbital coordinates.
num_orbitalsint: Total number of orbitals in the molecule.

Methods

get_orbital_distance_matrix()	Calculates the distance matrix between orbitals.
get_orbital_bond_matrix(cutoff=1.59)	Generates a bond matrix based on orbital distances and a cutoff value.

Notes

Note

The coordinates are given in Angstroms (Å), not in nanometers (nm).

get_orbital_bond_matrix(cutoff=1.59)[source]

get_orbital_distance_matrix()[source]

class Monomer(filepaths, **kwargs)[source]

Bases: object

Monomer class representing a molecular system composed of multiple components. This class calculates various properties of the molecular system, including the LCAO Hamiltonian, molecular orbitals (HOMO and LUMO), center of mass, transition dipole moment, and orbital types.

Attributes:

filepathslist of str: List of file paths for the components of the monomer.
kwargsdict: Keyword arguments for LCAO parameter configuration.
param_idstr: Identifier for the LCAO parameter set.
lcao_paramdict: Loaded LCAO parameters.
atom_massesdict: Atomic masses for supported elements.
num_componentsint: Number of components in the monomer.
componentslist of Component: List of Component objects representing the monomer’s parts.
xyz_idlist: List of XYZ identifiers for the components.
atomslist: List of atoms in the monomer.
atoms_coordinateslist: List of atomic coordinates.
atoms_idlist: List of atom identifiers.
num_atomsint: Total number of atoms in the monomer.
orbitalslist: List of orbitals in the monomer.
orbitals_coordinateslist: List of orbital coordinates.
num_orbitalsint: Total number of orbitals in the monomer.
num_electronsint: Total number of electrons in the monomer.
Hndarray: LCAO Hamiltonian matrix.
eigvndarray: Eigenvalues of the Hamiltonian matrix.
eigsndarray: Eigenvectors of the Hamiltonian matrix.
HOMO_idxint: Index of the HOMO orbital.
E_HOMOfloat: Energy of the HOMO orbital.
HOMOndarray: Molecular orbital corresponding to HOMO.
LUMO_idxint: Index of the LUMO orbital.
E_LUMOfloat: Energy of the LUMO orbital.
LUMOndarray: Molecular orbital corresponding to LUMO.
center_of_massndarray: Center of mass of the monomer.
rel_orbitals_coordinatesndarray: Orbital coordinates relative to the center of mass.
dipole_momentndarray: Transition dipole moment.

Methods

calc_H()	Calculates the LCAO Hamiltonian matrix for the molecule.
build_block_matrix(D, U, L)	Constructs a block matrix from diagonal, upper, and lower matrices.
get_MO_type(MO)	Determines the type of molecular orbital (sigma, pi, or non-bonding).

Notes

Note

The coordinates are given in Angstroms (Å), not in nanometers (nm).

calc_H()[source]: Calculates the LCAO Hamiltonian matrix for the molecule.

get_MO_type(MO)[source]: Returns the nature of the molecular orbitals: sigma, pi, n (non-bonding).

class Oligomer(filepath_pdb, **kwargs)[source]

Bases: TBModel

Oligomer class for modeling tight-binding properties of DNA structures. This class extends the TBModel class and provides functionality for processing PDB files, and calculating tight-binding parameters such as couplings and energies for DNA-like oligomers.

Attributes:

filepath_pdbstr: Path to the input PDB file.
directorystr: Directory where XYZ files are stored.
kwargsdict: Configuration parameters for the model.
filename_pdbstr: Base name of the PDB file without extension.
sites_baseslist: List of base site filenames.
sites_backbonelist: List of backbone site filenames.
siteslist: List of site groups based on the number of channels.
sites_idnumpy.ndarray: Array of site identifiers reshaped to match tight-binding dimensions.
filepathslist: File paths to XYZ files for each site.
num_sitesint: Total number of sites in the oligomer.
monomersnumpy.ndarray: Array of Monomer objects representing individual sites.
couplingslist: Tight-binding coupling information.
energieslist: Tight-binding energy information.
tb_paramsdict or None: Calculated tight-binding parameters, including hole, electron, and exciton properties.

Methods

calc_tb_couplings(monomer1, monomer2)	Calculate tight-binding couplings between two monomers.
calc_tb_energies(monomer)	Calculate tight-binding energies for a monomer.
calc_tb_params()	Compute and return tight-binding parameters for the oligomer.
save_tb_params(directory=None)	Save tight-binding parameters to a file.
plot_couplings(particle, add_colorbar=False, add_label=True, fig=None, ax=None, dpi=None, max_coupling=None)	Plot tight-binding couplings for a specified particle type.
clean()	Clean up temporary files and directories created during processing.

Notes

Note

The class assumes a specific structure for the input PDB file and generates XYZ files accordingly.
Tight-binding parameters are calculated based on the provided LCAO model and configuration.

calc_tb_couplings(monomer1, monomer2)[source]: Calculate tight-binding couplings (HOMO, LUMO, and excitonic coupling) between two monomers.

calc_tb_energies(monomer)[source]

calc_tb_params()[source]: Calculates and returns the tight-binding parameters for the system.

clean()[source]: Clean up temporary files and directories created during processing.

plot_couplings(particle, add_colorbar=False, add_label=True, fig=None, ax=None, dpi=None, max_coupling=None)[source]: Plots coupling interactions between sites for a given particle type.

save_tb_params(directory=None)[source]: Save tight-binding parameters to a specified directory or default location.

Tight-binding Model

class TBModel(num_sites_per_strand, **kwargs)[source]

Bases: object

Tight-Binding Model class for representing DNA-like structures.

Parameters:

num_sites_per_strandint: Number of sites per strand in the model.

Attributes:

num_sites_per_strandint: Number of sites per strand in the model.
tb_model_namestr: Name of the tight-binding model.
tb_model_propsdict: Properties of the selected tight-binding model.
backbonestr: Backbone type of the model.
double_strandedbool: Indicates if the model is double-stranded.
num_channelsint: Number of channels (strands) in the model.
num_strandsint: Number of strands in the model (same as num_channels).
tb_dimstuple: Dimensions of the tight-binding model (channels, sites per strand).
tb_configdict: Configuration of the tight-binding model.
num_sitesint: Total number of sites in the model.
tb_basisndarray: Basis for the tight-binding model.
eh_basisndarray: Electron-hole basis for the model.

Notes

Note

If a custom tight-binding model is used, kwargs must include num_channels and tb_config.

Tight-binding Hamiltonian

class TBHam(tb_sites, **kwargs)[source]

Bases: TBModel

TBHam class for modeling tight-binding Hamiltonians. This class extends the TBModel to represent tight-binding Hamiltonians for DNA structures. It supports both single-particle (1P) and two-particle (2P) descriptions, includes an option for the DNA relaxed state and can perform a Fourier analysis.

Attributes:

tb_sitesnp.ndarray: Array representing the tight-binding sites.
tb_sites_flattenednp.ndarray: Flattened array of tight-binding sites.
tb_basis_sites_dictdict: Mapping of tight-binding basis to sites.
sequence_idstr: DNA sequence identifier.
descriptionstr: Description of the Hamiltonian (“1P” or “2P”).
tb_paramsdict: Tight-binding parameters.
matrixnp.ndarray or None: Hamiltonian matrix.
matrix_dimint or None: Dimension of the Hamiltonian matrix.
relaxationbool: Returns whether the DNA relaxed state is included.
coulomb_paramfloat or None: Returns the Coulomb interaction parameter.
exchange_paramfloat or None: Returns the Exchange interaction parameter.
nn_cutofffloat or None: Returns the nearest neighbor cutoff for interactions.
unitstr: Returns the unit of the Hamiltonian.
sourcestr: Returns the source of the tight-binding parameters.
particleslist: Returns the particles in the Hamiltonian.

Methods

get_tb_params()	Loads and converts tight-binding parameters.
get_matrix()	Computes the Hamiltonian matrix.
get_eigensystem()	Computes the eigenvalues and eigenvectors of the Hamiltonian matrix.
get_fourier(init_state, end_state, quantities)	Computes Fourier analysis for transitions between states.
get_amplitudes(init_state, end_state)	Computes transition amplitudes between states.
get_frequencies(init_state, end_state)	Computes transition frequencies between states.
get_average_pop(init_state, end_state)	Computes average population between states.
get_backbone_average_pop(init_state)	Computes average population for backbone sites.

Examples

>>> tb_sites = [["A", "T", "C"], ["G", "C", "A"]]
>>> tb_ham = TBHam(tb_sites, description="1P", particles=["electron"], unit="eV")
>>> tb_ham.get_matrix()

property coulomb_param: Returns the Coulomb interaction parameter.

property exchange_param: Returns the Exchange interaction parameter.

get_amplitudes(init_state, end_state)[source]

get_average_pop(init_state, end_state)[source]

get_backbone_average_pop(init_state)[source]

get_eigensystem()[source]

get_fourier(init_state, end_state, quantities)[source]

get_frequencies(init_state, end_state)[source]

get_matrix()[source]

get_tb_params()[source]

property nn_cutoff: Returns the nearest neighbor cutoff for interactions.

property particles: Returns the particles in the Hamiltonian.

property relaxation: Returns whether the DNA relaxed state is included.

property source: Returns the source of the tight-binding parameters.

property unit: Returns the unit of the Hamiltonian.

Lindblad Dissipator

class LindDiss(tb_sites, **kwargs)[source]

Bases: TBHam

LindDiss class for modeling Lindblad dissipation in quantum systems. This class extends TBHam and provides functionality to define and manage Lindblad operators, relaxation rates, dephasing, and thermalization parameters for quantum systems described by tight-binding models.

Parameters:

tb_siteslist: List of tight-binding sites.

Attributes:

c_opslist: List of Lindblad operators (collapse operators) used in the Lindblad master equation.
relax_ratesdict: Dictionary of relaxation rates for each DNA base.
num_c_opsint: Number of collapse operators.
e_opstuple: Observables including population, coherence, and ground state population operators.

property c_ops: List of Lindblad operators (collapse operators) used in the Lindblad master equation.

property relax_rates: Dictionary of relaxation rates for each DNA base.

Master Equation Solver

class MeSolver(tb_sites, **kwargs)[source]

Bases: LindDiss

MeSolver class for solving master equations in quantum dynamics. This class extends LindDiss and provides methods for simulating quantum systems using master equations. It supports initialization of Hamiltonians, density matrices, and various observables, as well as solving the equations for populations, coherences, and ground state populations.

Attributes:

kwargsdict: Configuration parameters for the solver.
timesndarray: Array of time points for the simulation.
t_unitstr: Unit of time used in the simulation.
ham_matrixqutip.Qobj: Hamiltonian matrix of the system.
init_stateslist: Initial states of the system.
init_matrixqutip.Qobj: Initial density matrix of the system.
resultlist or None: Results of the simulation.
groundstate_popdict or None: Ground state population values.
popdict or None: Population values for the system.
cohdict or None: Coherence values for the system.
optionsdict: Solver options.
solver_kwargsdict: Arguments for the solver.
qutip_versionstr: Version of QuTiP library used.
t_endfloat: Returns the end time of the simulation.
t_stepsint: Returns the number of time steps in the simulation.

Methods

reset()	Resets the solver state and clears results.
get_result()	Solves the master equation and returns the state evolution.
get_result_particle(particle)	Returns the reduced density matrix for a specific particle.
get_pop()	Computes and returns population values.
get_coh()	Computes and returns coherence values.
get_groundstate_pop()	Computes and returns ground state population values.

get_coh()[source]

get_groundstate_pop()[source]

get_pop()[source]

get_result()[source]

get_result_particle(particle)[source]

reset()[source]

property t_end: Returns the end time of the simulation.

property t_steps: Returns the number of time steps in the simulation.

Evaluation

class Evaluation(tb_sites, **kwargs)[source]

Bases: MeSolver

Evaluation class for analyzing exciton dynamics in quantum DNA models.

Parameters:

tb_siteslist: List of tight-binding sites defining the system.
**kwargsdict: Additional parameters for the MeSolver superclass.

Attributes:

lifetimefloat or None: Estimated exciton lifetime in femtoseconds.
charge_separationfloat or None: Average charge separation based on electron-hole distances.
dipole_momentfloat or None: Dipole moment of the system in Debye units.

Methods

calc_lifetime()	Calculate the exciton lifetime based on ground state population.
calc_charge_separation(average=True)	Compute the charge separation based on electron-hole distances.
calc_dipole_moment()	Calculate the dipole moment of the system.
calc_backbone_transfer()	Compute average transfer for backbone sites in Fishbone models.
calc_exciton_transfer()	Calculate exciton transfer for double-stranded, non-backbone models.

calc_backbone_transfer(average=True)[source]

Calculates the average transfer for backbone sites in a Fishbone model.

Returns:

float: The average transfer value across the backbone sites.

Raises:

AssertionError: If the backbone attribute is not set, indicating the model is not a Fishbone model.

calc_charge_separation(average=True)[source]

Calculate the charge separation based on electron-hole distances.

Parameters:

averagebool, optional: If True, returns the average charge separation. Defaults to True.

Returns:

float or list: The calculated charge separation. Returns a single float if average is True, otherwise returns a list of charge separations.

Examples

>>> eva = Evaluation([list('GCG'), list('CGC')], relax_rate=0.)
>>> eva.calc_charge_separation()
2.951734389657976

calc_dipole_moment()[source]

Calculates the dipole moment of the system.

Returns:

float: The dipole moment in Debye units.

Examples

>>> eva = Evaluation([list('GCG'), list('CGC')], relax_rate=0.)
>>> eva.calc_dipole_moment()
14.177784530660903

calc_exciton_transfer(average=True)[source]

Calculate exciton transfer for a double-stranded, non-backbone model. This method computes the average exciton transfer between the upper and lower strands of the model.

Returns:

dict

A dictionary containing the average exciton transfer populations for the upper and lower strands:

upper_strand_pop: Population transfer for the upper strand.
lower_strand_pop: Population transfer for the lower strand.

Raises:

AssertionError: If the model is not double-stranded or if it includes a backbone.

Examples

>>> eva = Evaluation([list('GCG'), list('CGC')], relax_rate=0.)
>>> eva.calc_exciton_transfer()
({'electron': 0.6867427675114343,
'hole': 0.9943813264087192,
'exciton': 0.45001514054414693},
{'electron': 0.31325723248857257,
'hole': 0.005618673591287626,
'exciton': 0.0001960836601784245})

calc_lifetime()[source]

Calculate the estimated exciton lifetime (in fs) based on ground state population.

Returns:

float or str: The calculated lifetime in the specified time unit, or a message indicating no relaxation occurred within the given time.

Examples

>>> eva = Evaluation([list('GCG'), list('CGC')], relax_rate=3., unit="rad/ps")
>>> eva.calc_lifetime()
775.5511022044088

class EvaluationParallel(evaluation_list, **kwargs)[source]

Bases: object

A class for parallel evaluation of observables across a list of sequences using multiprocessing.

Parameters:

evaluation_listlist: A list of evaluation objects, each containing a sequence ID and associated data.

Attributes:

num_sequencesint: Total number of sequences to evaluate.
available_cpusint: Number of CPU cores available on the system.
num_cpuint: Number of CPU cores allocated for multiprocessing.
evaluation_listlist: List of evaluation objects to process.
sequence_id_listlist: List of sequence IDs extracted from the evaluation objects.
observableslist of str: Observables to calculate for each sequence.
argslist of tuple: Arguments prepared for multiprocessing, containing sequence index, observables, and evaluation list.

Methods

calc_results(filepath=None, save=True)

Calculate results for the sequences using multiprocessing and optionally save them to a file.

calc_results(filepath=None, save=True)[source]

Calculate results for a set of sequences using multiprocessing.

Parameters:

filepathstr, optional: Path to save the results as a JSON file. If None, results are not saved.
savebool, default=True: Whether to save the results to a file.

Returns:

dict: A dictionary containing the calculated results for each sequence and metadata including observables and calculation time.

Visualization

class Visualization(tb_sites, **kwargs)[source]

Bases: Evaluation

Visualization class for plotting and analyzing quantum DNA data. This class extends the Evaluation class and provides various methods for visualizing quantum DNA data, including heatmaps, population plots, coherence plots, eigenstate distributions, Fourier analysis, and cumulative average population plots.

Attributes:

tb_siteslist: List of tight-binding sites.
kwargsdict: Additional keyword arguments passed to the Evaluation class.

Methods

plot_heatmap(heatmap_type=”seaborn”, fig=None, ax=None, dpi=None, plot_kwargs)**	Plot heatmaps for particle populations using seaborn or matplotlib.
plot_pop(tb_site, fig=None, ax=None, dpi=None, add_legend=True, plot_kwargs)**	Plot population dynamics for a specific tight-binding site.
plot_pops(fig=None, ax=None, dpi=None, plot_kwargs)**	Plot population dynamics for all tight-binding sites.
plot_pop_fourier(init_state, end_state, times, t_unit, fig=None, ax=None, dpi=None, add_legend=True, plot_kwargs)**	Plot population dynamics using Fourier analysis.
plot_coh(fig=None, ax=None, dpi=None, plot_kwargs)**	Plot coherence dynamics for particles.
plot_test_fourier(tb_site, fig=None, ax=None, dpi=None, plot_kwargs)**	Test Fourier analysis by comparing population dynamics and Fourier results.
plot_eigv(energy_unit=”eV”, fig=None, ax=None, dpi=None, color=None)	Plot eigenvalues of the system.
plot_eigs(eigenstate_idx, fig=None, ax=None, dpi=None)	Plot eigenstate distributions for a given eigenstate index.
plot_fourier(init_state, end_state, x_axis, fig=None, ax=None, dpi=None)	Plot Fourier amplitudes and frequencies or periods.
plot_average_pop(J_list, J_unit=”100meV”, fig=None, ax=None, dpi=None, plot_kwargs)**	Plot cumulative average population for varying Coulomb parameters.

plot_average_pop(J_list, J_unit='100meV', fig=None, ax=None, dpi=None, **plot_kwargs)[source]

plot_coh(fig=None, ax=None, dpi=None, add_legend=True, **plot_kwargs)[source]

plot_eigs(eigenstate_idx, fig=None, ax=None, dpi=None)[source]

plot_eigv(energy_unit='eV', fig=None, ax=None, dpi=None, color=None)[source]

plot_fourier(init_state, end_state, x_axis, fig=None, ax=None, dpi=None)[source]

plot_heatmap(heatmap_type='seaborn', fig=None, ax=None, dpi=None, vmax_list=None, cmaps=None, **plot_kwargs)[source]

plot_heatmap2(heatmap_type='seaborn', fig=None, ax=None, dpi=None, vmax_list=None, cmaps=None, number=None, **plot_kwargs)[source]

plot_pop(tb_site, fig=None, ax=None, dpi=None, add_legend=True, **plot_kwargs)[source]

plot_pop_fourier(init_state, end_state, times, t_unit, fig=None, ax=None, dpi=None, add_legend=True, **plot_kwargs)[source]

plot_pops(fig=None, ax=None, dpi=None, **plot_kwargs)[source]

plot_test_fourier(tb_site, fig=None, ax=None, dpi=None, **plot_kwargs)[source]