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.

Issues:

Only ground to excited state transition widths and dephasing ( no 1->2 band transition widths)
No energy gap correlation function for the 1->2 band transitions (only ground to excited ones)
- Coft is for the state and not transition for the 1->2 transition on single molecule the cofts has to be properly subtracted
Transformation of the transition width for multilevel molecules (check), transform the same for the vibronic agregate for the multilevel molecule

class quantarhei.builders.aggregate_base.AggregateBase(molecules: list | None = None, name: str = '')[source]#

Bases: UnitsManaged, Saveable, OpenSystem

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

clean() → None[source]#

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.

wipe_out() → None[source]#

Removes everything except of name attribute

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

init_coupling_indexes() → None[source]#

Set indexes for elements of the coupling matrix

index for coupling between mon1 init1 -> final1 and mon2 init2 -> final2 is self._mol2coupling[mon1][init1][final1-init1-1][mon2-mon1-1][init2][final2-init2-1]

init_coupling_vector() → None[source]#: initialize coupling vector

get_resonance_coupling_vec(mon1: int, init1: int, fin1: int, mon2: int, init2: int, fin2: int) → float | ndarray[source]#

returns coupling between mon1 transition init1->fin1 and mon2 transition init2->fin2

Parameters:

mon1 (integer) – indexes of two monomers betweem which interaction energy is calculated
mon2 (integer) – indexes of two monomers betweem which interaction energy is calculated
init1 (integer) – index of initial and final state, respectively, of monomer 1 for electronic transition init1->fin1. Ground state is 0 first excited state 1, and so on
fin1 (integer) – index of initial and final state, respectively, of monomer 1 for electronic transition init1->fin1. Ground state is 0 first excited state 1, and so on
init2 (integer) – index of initial and final state, respectively, of monomer 2
fin2 (integer) – index of initial and final state, respectively, of monomer 2

Returns:

coupling (float) – coupling between mon1 transition init1->fin1 and mon2 transition init2->fin2 in current energy units

set_coupling_by_dipole_dipole_vec(epsr: float = 1.0) → None[source]#: Sets resonance coupling by dipole-dipole interaction for multilevel molecules

init_coupling_matrix() → None[source]#: Nullifies coupling matrix

set_resonance_coupling(i: int, j: int, coupling: float, mode_linear: list | None = None, mode_shift: list | None = None) → None[source]#: Sets resonance coupling value between two sites

set_coupling_by_Hamiltonian(HH: ndarray) → None[source]#

set the resonance coupling values according to given electronic Hamiltonian (single exciton band is expected - without the ground state). Only excitations from the ground state are allowed.

Parameters:: HH (numpy.array of float) – First exciton band hamiltonian. Only excitations from the ground state are supported so far. The ordering of the hamiltonian must be the same and the nomomers and its transitions.

set_resonance_coupling_vec(i: int, j: int, coupling: float) → None[source]#

Sets resonance coupling value between two sites (between !electronic states!)

Parameters:

i (integer) – indexes of electronic levels (in aggregate) for which the coupling is set
j (integer) – indexes of electronic levels (in aggregate) for which the coupling is set
coupling (float) – coupling between the electronic states in current energy units

get_resonance_coupling(i: int, j: int) → float | ndarray[source]#: Returns resonance coupling value between two sites

set_resonance_coupling_matrix(coupmat: ndarray | list | tuple) → None[source]#: Sets resonance coupling values from a matrix

dipole_dipole_coupling(kk: int, ll: int, epsr: float = 1.0, delta: float = 1e-05) → float | ndarray[source]#: Calculates dipole-dipole coupling

dipole_dipole_coupling_multilevel(mon1: int, in1: int, fin1: int, mon2: int, in2: int, fin2: int, epsr: float = 1.0) → float | ndarray[source]#

Calculates dipole-dipole coupling for multilevel monomers

Parameters:

mon1 (integer) – indexes of two monomers betweem which dipole-dipole interaction energy is calculated
mon2 (integer) – indexes of two monomers betweem which dipole-dipole interaction energy is calculated
init1 (integer) – index of initial and final state, respectively, of monomer 1 for electronic transition init1->fin1. Ground state is 0 first excited state 1, and so on
fin1 (integer) – index of initial and final state, respectively, of monomer 1 for electronic transition init1->fin1. Ground state is 0 first excited state 1, and so on
init2 (integer) – index of initial and final state, respectively, of monomer 2
fin2 (integer) – index of initial and final state, respectively, of monomer 2
epsr (float) – relative permitivity of the environment

Returns:

val (float) – dipole-dipole interaction energy in current energy units

set_coupling_by_dipole_dipole(epsr: float = 1.0, delta: float = 1e-05) → None[source]#: Sets resonance coupling by dipole-dipole interaction

calculate_resonance_coupling(method: str = 'dipole-dipole', params: dict | None = None) → None[source]#

Sets resonance coupling calculated by a given method

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

set_lindich_axes(axis_orthog_membrane: ndarray) → None[source]#: 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.

get_lindich_axes() → ndarray[source]#

set_egcf_matrix(cm: object) → None[source]#: Sets a matrix describing system bath interaction

add_Molecule(mono: Any) → None[source]#: Adds monomer to the aggregate

get_Molecule_by_name(name: str) → object[source]#

get_Molecule_index(name: str) → int[source]#

remove_Molecule(mono: object) → None[source]#

get_nearest_Molecule(molecule: Any) → tuple[source]#

Returns a molecule nearest in the aggregate to a given molecule

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

get_dipole(n: Any, N: Any = None, M: Any = None, **kwargs: Any) → ndarray[source]#

Returns the dipole vector for a given electronic transition

There are two ways how to use this function:

recommended

get_dipole((0,1),[1.0, 0.0, 0.0])

here N represents a transition by a tuple, M is the dipole

deprecated (used in earlier versions of quantarhei)

get_dipole(0,1,[1.0, 0.0, 0.0])

here the transition is characterized by two integers and the last arguments is the vector

Examples

>>> m = OpenSystem([0.0, 1.0])
>>> m.set_dipole((0,1),[1.0, 0.0, 0.0])
>>> m.get_dipole((0,1))
array([ 1.,  0.,  0.])

get_velocity_dipole(n: int, N: int, M: int) → ndarray[source]#

get_magnetic_dipole(n: int, N: int, M: int) → ndarray[source]#

get_width(n: int, N: int, M: int) → float[source]#

get_max_excitations() → list[source]#: Returns a list of maximum number of excitations on each monomer

set_dipole(N: Any, M: Any = None, vec: Any = None) → None[source]#: Sets the dipole moment of a given transition

fc_factor(state1: Any, state2: Any) → float[source]#

Franck-Condon factors between two vibrational states

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

map_egcf_to_states(mpx: ndarray) → ndarray[source]#

Maps the participation matrix on g(t) functions storage

This should work for a simple mapping matrix and first excited band. Specialized mapping such as those for 2 exciton states is implemented in classes that inherite from here.

get_transition_width(state1: Any, state2: Any | None = None) → float[source]#

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})
state (If not None it is of the type of Electronic of Vibronic)

get_transition_dephasing(state1: Any, state2: Any | None = None) → float[source]#

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})
state (If not None it is of the type of Electronic of Vibronic)

transition_dipole(state1: Any, state2: Any) → ndarray | float[source]#

Transition dipole moment between two states

Parameters:

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

transition_velocity_dipole(state1: Any, state2: Any) → ndarray | float[source]#

Transition dipole moment between two states

Parameters:

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

transition_magnetic(state1: Any, state2: Any) → ndarray | float[source]#

Transition magnetic dipole moment between two states

Parameters:

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

total_number_of_states(mult: int = 1, vibgen_approx: str | None = None, Nvib: int | None = None, vibenergy_cutoff: float | None = None, save_indices: bool = False, band_external: list | None = None) → int[source]#

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.

total_number_of_electronic_states(mult: int = 1) → int[source]#: Total number of electronic states in the aggregate

number_of_states_in_band(band: int = 1, vibgen_approx: str | None = None, Nvib: int | None = None, vibenergy_cutoff: float | None = None) → int[source]#: Number of states in a given excitonic band

number_of_electronic_states_in_band(band: int = 1) → int[source]#: Number of states in a given excitonic band

get_ElectronicState(sig: tuple, index: int | None = None) → ElectronicState[source]#

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_StateBand(state: Any) → int[source]#

Returns band of the corresponding electronic state

This effectively counts the number of excitations in the state by counting the band numbers in each molecules.

Parameters:: state (ElectronicState) – Aggregate electronic state.

get_VibronicState(esig: tuple, vsig: tuple) → VibronicState[source]#: Returns vibronic state corresponding to the two specified signatures

coupling_vec(state1: Any, state2: Any) → float | ndarray[source]#

Coupling between two aggregate states

Parameters:

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

Returns:

coup (float) – Resonance coupling in current units

coupling(state1: Any, state2: Any, full: bool = False) → float | ndarray[source]#

Coupling between two aggregate states

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

elsignatures(mult: int = 1, mode: str = 'LQ', emax: list | None = None) → Iterator[tuple[Any, ...]][source]#

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.

Provide correct ordering for the multilevel molecues

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

vibsignatures(elsignature: tuple, approx: str | None = None) → Any[source]#

Generator of vibrational signatures

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

allstates(mult: int = 1, mode: str = 'LQ', all_vibronic: bool = True, save_indices: bool = False, vibgen_approx: str | None = None, Nvib: int | None = None, vibenergy_cutoff: float | None = None, band_external: list | None = None) → Generator[tuple[int, Any], None, None][source]#

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

elstates(mult: int = 1, mode: str = 'LQ', save_indices: bool = False) → Generator[tuple[int, Any], None, None][source]#: Generator of electronic states

build(mult: int = 1, sbi_for_higher_ex: bool = False, vibgen_approx: str | None = None, Nvib: int | None = None, vibenergy_cutoff: float | None = None, band_external: list | None = None, el_blocks: bool = False) → None[source]#

Builds aggregate properties

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

Parameters:

multint: 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.
band_externallist of integers (dimension Nx2): redefinition of correspondence of individual electronic states to excitonic bands, e.g. [[4,1],[5,2]] means that 4th electronic state is moved to single exciton band and 5th electronic state to the second exciton band (zeroth electronic state is the ground state). The mult must be high enough to allow the building the original states, e.g for 2 two level carotenoids where S2-S2 interaction should mult=2 Because it is interaction between second excited state and secodn excited state

rebuild(mult: int = 1, sbi_for_higher_ex: bool = False, vibgen_approx: str | None = None, Nvib: int | None = None, vibenergy_cutoff: float | None = None) → None[source]#: Cleans the object and rebuilds it

Converts an operator to a ground state vibrational basis repre

Default representation in Quantarhei is that with a specific shifted vibrational basis in each electronic state. Here we convert to a representation where there is a single basis used for all vibrational states regardless of elecrtronic state

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

trace_converted(operator: ReducedDensityMatrix | DensityMatrix | Hamiltonian | ReducedDensityMatrixEvolution | DensityMatrixEvolution, Nt: int | None = None) → ReducedDensityMatrix | Hamiltonian | TransitionDipoleMoment | ReducedDensityMatrixEvolution[source]#

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

cast_to_vibronic(KK: ndarray) → ndarray[source]#: Casts an electronic operator to a vibronic basis

convert_to_DensityMatrix(psi: object, trace_over_vibrations: bool = True) → object[source]#: Converts StateVector into DensityMatrix (possibly reduced one)

get_RWA_suggestion() → float[source]#

Returns average transition energy

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

diagonalize() → None[source]#: Transforms some internal quantities into diagonal basis

get_StateVector(condition_type: str | None = None, DD: ndarray | None = None) → Any[source]#

Returns state vector accordoing to specified conditions

Parameters:: condition_type (str) – Type of the initial condition. If None, the property sv0, which was presumably calculated in the past, is returned.

get_DensityMatrix(condition_type: str | None = None, relaxation_theory_limit: str = 'weak_coupling', temperature: float | None = None, relaxation_hamiltonian: Hamiltonian | None = None, DD: ndarray | None = None) → DensityMatrix[source]#

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.
DD (real array) – Submit your own transition dipole moment matrix (for x, y and z)
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_temperature() → float[source]#

Returns temperature associated with this aggregate

The temperature originates from the system-bath interaction

get_electronic_groundstate() → tuple[source]#

Indices of states in electronic ground state

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

get_excitonic_band(band: int = 1) → tuple[source]#

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_transition(Nf: Any, Ni: Any) → tuple[source]#

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

has_SystemBathInteraction() → bool[source]#: Returns True if the Aggregate is embedded in a defined environment

get_SystemBathInteraction() → Any[source]#: Returns the aggregate SystemBathInteraction object

set_SystemBathInteraction(sbi: Any) → None[source]#: Sets the SystemBathInteraction operator for this aggregate

get_Hamiltonian() → Any[source]#: Returns the aggregate Hamiltonian

get_electronic_Hamiltonian(full: bool = False) → Any[source]#

Returns the aggregate electronic Hamiltonian

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

get_TransitionDipoleMoment() → Any[source]#: Returns the aggregate transition dipole moment operator

get_TransitionMagneticDipoleMoment() → Any[source]#: Returns the aggregate transition dipole moment operator