AggregateBase

Class representing aggregates of molecules.

The class enables building of complicated objects from objects of the Molecule type, their mutual interactions and system-bath interactions. It also provides an interface to various methods of open quantum systems theory.

class quantarhei.builders.aggregate_base.AggregateBase(molecules=None, name='')

Molecular aggregate

Parameters:

• name (str) – Specifies the name of the aggregate
• molecules (list or tuple) – List of molecules out of which the aggregate is built

Methods

add_Mode_by_name(name, mode)
add_Molecule(mono)	Adds monomer to the aggregate
allstates([mult, mode, all_vibronic, …])	Generator of all aggregate states
build([mult, sbi_for_higher_ex, …])	Builds aggregate properties
calculate_resonance_coupling([method, params])	Sets resonance coupling calculated by a given method
cast_to_vibronic(KK)	Casts an electronic operator to a vibronic basis
clean()	Cleans the aggregate object of anything built
convert_to_DensityMatrix(psi[, …])	Converts StateVector into DensityMatrix (possibly reduced one)
copy()	Returns a shallow copy of the self
coupling(state1, state2[, full])	Coupling between two aggregate states
deepcopy()	Returns a deep copy of the self
diagonalize()	Transforms some internal quantities into diagonal basis
dipole_dipole_coupling(kk, ll[, epsr, delta])	Calculates dipole-dipole coupling
elsignatures([mult, mode, emax])	Generator of electronic signatures
elstates([mult, mode, save_indices])	Generator of electronic states
fc_factor(state1, state2)	Franck-Condon factors between two vibrational states
get_DensityMatrix([condition_type, …])	Returns density matrix according to specified condition
get_ElectronicState(sig[, index])	Returns electronic state corresponding to this aggregate
get_FoersterRateMatrix()	Returns Förster rate matrix for the open system
get_Hamiltonian()	Returns the aggregate Hamiltonian
get_KTHierarchy([depth])	Returns the Kubo-Tanimura hierarchy of an open system
get_KTHierarchyPropagator([depth])	Returns a propagator based on the Kubo-Tanimura hierarchy
get_RWA_suggestion()	Returns average transition energy
get_RedfieldRateMatrix()	Returns Redfield rate matrix
get_ReducedDensityMatrixPropagator(timeaxis)	Returns propagator of the density matrix
get_RelaxationTensor(timeaxis[, …])	Returns a relaxation tensor corresponding to the system
get_SystemBathInteraction()	Returns the aggregate SystemBathInteraction object
get_TransitionDipoleMoment()	Returns the aggregate transition dipole moment operator
get_VibronicState(esig, vsig)	Returns vibronic state corresponding to the two specified signatures
get_dipole_by_name(name, N, M)
get_electronic_Hamiltonian([full])	Returns the aggregate electronic Hamiltonian
get_electronic_groundstate()	Indices of states in electronic ground state
get_energy_by_name(name, N)	Electronic energy
get_excited_density_matrix([condition, …])	Returns the density matrix corresponding to excitation condition
get_excitonic_band([band])	Indices of states in a given excitonic band.
get_lindich_axes()
get_max_excitations()	Returns a list of maximum number of excitations on each monomer
get_nearest_Molecule(molecule)	Returns a molecule nearest in the aggregate to a given molecule
get_resonance_coupling(i, j)	Returns resonance coupling value between two sites
get_temperature()	Returns temperature associated with this aggregate
get_thermal_ReducedDensityMatrix()	Returns equilibrium density matrix for a give temparature
get_transition(Nf, Ni)	Returns relevant info about the energetic transition
get_transition_dephasing(state1[, state2])	Returns phenomenological dephasing of a given transition
get_transition_width(state1[, state2])	Returns phenomenological width of a given transition
get_width(n, N, M)
has_SystemBathInteraction()	Returns True if the Aggregate is embedded in a defined environment
init_coupling_matrix()	Nullifies coupling matrix
load(filename[, test])	Loads an object from a file and returns it
loaddir(dirname)	Returns a directory of objects saved into a directory
number_of_electronic_states_in_band([band])	Number of states in a given excitonic band
number_of_states_in_band([band, …])	Number of states in a given excitonic band
rebuild([mult, sbi_for_higher_ex, …])	Cleans the object and rebuilds it
save(filename[, comment, test])	Saves the object with all its content into a file
savedir(dirname[, tag, comment, test])	Saves an object into directory containing a file with unique name
scopy()	Creates a copy of the object by saving and loading it
set_SystemBathInteraction(sbi)	Sets the SystemBathInteraction operator for this aggregate
set_coupling_by_dipole_dipole([epsr, delta])	Sets resonance coupling by dipole-dipole interaction
set_egcf_matrix(cm)	Sets a matrix describing system bath interaction
set_lindich_axes(axis_orthog_membrane)	Creates a coordinate system with one axis supplied by the user (typically an axis orthogonal to the membrane), and two other axes, all of which are orthonormal.
set_resonance_coupling(i, j, coupling[, …])	Sets resonance coupling value between two sites
set_resonance_coupling_matrix(coupmat)	Sets resonance coupling values from a matrix
total_number_of_electronic_states([mult])	Total number of electronic states in the aggregate
total_number_of_states([mult, …])	Total number of states in the aggregate
trace_over_vibrations(operator[, Nt])	Average an operator over vibrational degrees of freedom
transition_dipole(state1, state2)	Transition dipole moment between two states
vibsignatures(elsignature[, approx])	Generator of vibrational signatures
wipe_out()	Removes everything except of name attribute

convert_energy_2_current_u
convert_energy_2_internal_u
convert_length_2_current_u
convert_length_2_internal_u
get_Mode_by_name
get_Molecule_by_name
get_Molecule_index
get_dipole
remove_Molecule
unit_repr
unit_repr_latex

add_Molecule(mono)

Adds monomer to the aggregate

allstates(mult=1, mode='LQ', all_vibronic=True, save_indices=False, vibgen_approx=None, Nvib=None, vibenergy_cutoff=None)

Generator of all aggregate states

Iterator generating all states of the aggregate given a set of constraints.

Parameters:

• mult (integer {0, 1, 2}) – Exciton multiplicity (ground state, single and double excitons). All excitons with the multiplicity smaller or equal to mult are generated by default
• mode (str {"LQ", "EQ"}) – If set to “LQ” generates excitons with smaller or equal multiplicity than specified. If “EQ” is specified, generates only excitons with given multiplicity
• save_indices (bool) – If True, saves indices of all generated states, so that they can be later used.
• all_vibronic (bool) – If True, all generated states are of the type VibronicState, even if no vibrational modes are specified. If False, ElectronicState is returned for pure electronic states
• vibgen_approx (str {"ZPA", "SPA", "TPA", "NPA", "SPPMA", "TPPMA", "NPPMA"}) – Type of approximation in generating vibrational states
• Nvib (integer) – Number of vibrational states that goes into “NPA” and “NPPMA” approximations
• vibenergy_cutoff (float) – Maximum vibrational energy allowed in generation of vibrational states

build(mult=1, sbi_for_higher_ex=False, vibgen_approx=None, Nvib=None, vibenergy_cutoff=None, fem_full=False)

Builds aggregate properties

Calculates Hamiltonian and transition dipole moment matrices and sets up system-bath interaction

Parameters:

• mult (int) – exciton multiplicity
• sbi_for_higher_ex (bool) – If set True, system-bath information is explicitely created for higher exciton states (consistent with the specified parameters mult). If set False, it is expected that if system-bath interaction for higher excitons is needed, it will be reconstructed from the single exciton part of this object
• vibge_approx – Approximation used in the generation of vibrational state.

calculate_resonance_coupling(method='dipole-dipole', params={'epsr': 1.0})

Sets resonance coupling calculated by a given method

Parameters:method (string) – Method to be used for calculation of resonance coupling

cast_to_vibronic(KK)

Casts an electronic operator to a vibronic basis

clean()

Cleans the aggregate object of anything built

This operation leaves the molecules of the aggregate intact and keeps few more pieces of information it it. E. g. coupling matrix is not deleted. You call build again after this.

convert_to_DensityMatrix(psi, trace_over_vibrations=True)

Converts StateVector into DensityMatrix (possibly reduced one)

coupling(state1, state2, full=False)

Coupling between two aggregate states

Parameters:state1 ({ElectronicState, VibronicState}) – States for which coupling should be calculated

diagonalize()

Transforms some internal quantities into diagonal basis

dipole_dipole_coupling(kk, ll, epsr=1.0, delta=1e-05)

Calculates dipole-dipole coupling

elsignatures(mult=1, mode='LQ', emax=None)

Generator of electronic signatures

Here we create signature tuples of electronic states. The signature is a tuple with as many integer numbers as the members of the aggregate. Each integer represents the state in which the member of the aggregate is, e.g. 0 for ground state, 1 for the first excited state etc.

Parameters:

• mult (int) – multiplicity of excitons
• mode (str {"LQ", "EQ"}) –

  mode of the functions.

  mode=”LQ” returns all signatures of states with multiplicity less than or equal to the mult

  mode=”EQ” returns signatures of states with a multiplicity given by mult

elstates(mult=1, mode='LQ', save_indices=False)

Generator of electronic states

fc_factor(state1, state2)

Franck-Condon factors between two vibrational states

Calculates Franck-Condon factor between two aggregate_states regardless of their electronic parts

get_DensityMatrix(condition_type=None, relaxation_theory_limit='weak_coupling', temperature=None, relaxation_hamiltonian=None)

Returns density matrix according to specified condition

Returs density matrix to be used e.g. as initial condition for propagation.

Parameters:

• condition_type (str) – Type of the initial condition. If None, the property rho0, which was presumably calculated in the past, is returned.
• relaxation_theory_limits (str {weak_coupling, strong_coupling}) – Type of the relaxation theory limits; We mean the system bath coupling. When weak_coupling is chosen, the density matrix is returned in form of a canonical equilibrium in terms of the exciton basis. For strong_coupling, the canonical equilibrium is calculated in site basis with site energies striped of reorganization energies.
• temperature (float) – Temperature in Kelvin
• relaxation_hamiltonian – Hamiltonian according to which we form thermal equilibrium. In case of strong_coupling, no reorganization energies are subtracted - we assume that the supplied energies are already void of them.
• types (Condition) –
• --------------- –
• thermal – Thermally equilibriated population of the whole density matrix
• thermal_excited_state – Thermally equilibriuated excited state
• impulsive_excitation – Excitation by ultrabroad laser pulse

get_ElectronicState(sig, index=None)

Returns electronic state corresponding to this aggregate

Parameters:

• sig (tuple) – Tuple defining the electronic state of the aggregate
• index (integer or None) – If integer is specified, this number is recorded as an index of this state in the aggregate. It is recorded only internally in the state object. Aggregate keeps its own record which is created during the build.

get_Hamiltonian()

Returns the aggregate Hamiltonian

get_RWA_suggestion()

Returns average transition energy

Average transition energy of the monomer as a suggestion for RWA frequency

get_SystemBathInteraction()

Returns the aggregate SystemBathInteraction object

get_TransitionDipoleMoment()

Returns the aggregate transition dipole moment operator

get_VibronicState(esig, vsig)

Returns vibronic state corresponding to the two specified signatures

get_electronic_Hamiltonian(full=False)

Returns the aggregate electronic Hamiltonian

In case this is a purely electronic aggregate, the output is identical to get_Hamiltonian()

get_electronic_groundstate()

Indices of states in electronic ground state

Returns indices of all states in the electronic ground state of the system.

get_energy_by_name(name, N)

Electronic energy

get_excitonic_band(band=1)

Indices of states in a given excitonic band.

Returns indices of all states in the excitonic band with number of excitons equal to band

Parameters:band (int) – Specifies which band should be returned.

get_max_excitations()

Returns a list of maximum number of excitations on each monomer

get_nearest_Molecule(molecule)

Returns a molecule nearest in the aggregate to a given molecule

Parameters:molecule (Molecule) – Molecule whose neighbor we look for

get_resonance_coupling(i, j)

Returns resonance coupling value between two sites

get_temperature()

Returns temperature associated with this aggregate

The temperature originates from the system-bath interaction

get_transition(Nf, Ni)

Returns relevant info about the energetic transition

Parameters:

• Nf ({int, ElectronicState, VibronicState}) – Final state of the transition
• Ni ({int, ElectronicState VibronicState}) – Initial state of the transition

get_transition_dephasing(state1, state2=None)

Returns phenomenological dephasing of a given transition

Parameters:

• state1 ({ElectroniState/VibronicState, tuple}) – If both state1 and state2 are specified, it is assumed they are of the type of Electronic of Vibronic state. Otherwise, if state2 is None, it is assumed that it is a tuple representing a transition
• state2 ({ElectroniState/VibronicState, None}) –
• not None it is of the type of Electronic of Vibronic state (If) –

get_transition_width(state1, state2=None)

Returns phenomenological width of a given transition

Parameters:

• state1 ({ElectroniState/VibronicState, tuple}) – If both state1 and state2 are specified, it is assumed they are of the type of Electronic of Vibronic state. Otherwise, if state2 is None, it is assumed that it is a tuple representing a transition
• state2 ({ElectroniState/VibronicState, None}) –
• not None it is of the type of Electronic of Vibronic state (If) –

has_SystemBathInteraction()

Returns True if the Aggregate is embedded in a defined environment

init_coupling_matrix()

Nullifies coupling matrix

number_of_electronic_states_in_band(band=1)

Number of states in a given excitonic band

number_of_states_in_band(band=1, vibgen_approx=None, Nvib=None, vibenergy_cutoff=None)

Number of states in a given excitonic band

rebuild(mult=1, sbi_for_higher_ex=False, vibgen_approx=None, Nvib=None, vibenergy_cutoff=None)

Cleans the object and rebuilds it

set_SystemBathInteraction(sbi)

Sets the SystemBathInteraction operator for this aggregate

set_coupling_by_dipole_dipole(epsr=1.0, delta=1e-05)

Sets resonance coupling by dipole-dipole interaction

set_egcf_matrix(cm)

Sets a matrix describing system bath interaction

set_lindich_axes(axis_orthog_membrane)

Creates a coordinate system with one axis supplied by the user (typically an axis orthogonal to the membrane), and two other axes, all of which are orthonormal.

set_resonance_coupling(i, j, coupling, mode_linear=None, mode_shift=None)

Sets resonance coupling value between two sites

set_resonance_coupling_matrix(coupmat)

Sets resonance coupling values from a matrix

total_number_of_electronic_states(mult=1)

Total number of electronic states in the aggregate

total_number_of_states(mult=1, vibgen_approx=None, Nvib=None, vibenergy_cutoff=None, save_indices=False)

Total number of states in the aggregate

Counts all states of the aggregate by iterating through them. States are generated with a set of constraints.

trace_over_vibrations(operator, Nt=None)

Average an operator over vibrational degrees of freedom

Average MUST be done in site basis. Only in site basis we can distinguish the vibrational states properly

transition_dipole(state1, state2)

Transition dipole moment between two states

Parameters:

• state1 (class VibronicState) – state 1
• state2 (class VibronicState) – state 2

vibsignatures(elsignature, approx=None)

Generator of vibrational signatures

Parameters:approx (None or str) – Approximation used in generation of vibrational states Allowed values are None or “SPA”

wipe_out()

Removes everything except of name attribute

You have to set molecules and recalculate interactions before you can build