AggregateExcitonAnalysis

Class adding exciton analysis on molecular aggregates

Most of the present methods are available after the aggregate is diagonalized by calling the diagonalize method.

This class should not be used directly. Use Aggregate class, which inherits all the methods from here, instead.

Examples

>>> import quantarhei as qr

>>> agg = qr.TestAggregate("homodimer-2")
>>> agg.set_coupling_by_dipole_dipole()
>>> agg.build()
>>> # create information about eigenstates of the aggregate (to call `diagonalize()` is crucial)
>>> agg.diagonalize()
>>> #
>>> # Create a report on expantions of state with index `1`
>>> agg.report_on_expansion(state=1)
+-------+-------------+--------------+------------------+
| index | squares     | coefficients | state signatures |
+-------+-------------+--------------+------------------+
| 1     | 0.50000000  | -0.70710678  | ((1, 0), ())     |
| 2     | 0.50000000  | 0.70710678   | ((0, 1), ())     |
| 0     | 0.00000000  | 0.00000000   | ((0, 0), ())     |
| 0     | -1.00000000 | 0.00000000   | ((0, 0), ())     |
| 0     | -1.00000000 | 0.00000000   | ((0, 0), ())     |
+-------+-------------+--------------+------------------+

Class Details

class quantarhei.builders.aggregate_excitonanalysis.AggregateExcitonAnalysis(molecules: list | None = None, name: str = '')

Bases: AggregateSpectroscopy

Class adding exciton analysis on molecular aggregates

get_expansion_squares(state: int = 0) → tuple

Returns the squares of expansion coefficients of an excitonic state.

The Aggregate must be built and diagonalized. This output is used by the report_on_expansion() method.

>>> import quantarhei as qr
>>> agg = qr.TestAggregate("homodimer-2")
>>> agg.set_coupling_by_dipole_dipole()
...
... # build and diagonalize
>>> agg.build()
>>> agg.diagonalize()
...
... # expansion coefficients
>>> (indx, coefs, sqrs) = agg.get_expansion_squares(1)
>>> print(indx)
[0, 1, 2]
>>> print(coefs)
[ 0.         -0.70710678  0.70710678]
>>> print(sqrs)
[ 0.   0.5  0.5]

report_on_expansion(file: Any = None, state: int = 0, N: int = 5) → None

Prints a short report on the composition of an exciton state

Parameters:

• state (int) – Excitonic state of the aggregate

• N (int) – Number of states in expansion to report

Examples

>>> import quantarhei as qr
>>> agg = qr.TestAggregate("dimer-2")
>>> agg.set_coupling_by_dipole_dipole()
...
... # build and diagonalize
>>> agg.build()
>>> agg.diagonalize()
...
>>> agg.report_on_expansion(state=1)
+-------+-------------+--------------+------------------+
| index | squares     | coefficients | state signatures |
+-------+-------------+--------------+------------------+
| 1     | 0.90998848  | -0.95393316  | ((1, 0), ())     |
| 2     | 0.09001152  | 0.30001920   | ((0, 1), ())     |
| 0     | 0.00000000  | 0.00000000   | ((0, 0), ())     |
| 0     | -1.00000000 | 0.00000000   | ((0, 0), ())     |
| 0     | -1.00000000 | 0.00000000   | ((0, 0), ())     |
+-------+-------------+--------------+------------------+

get_intersite_mixing(state1: int = 0, state2: int = 0) → float

Returns inter site mixing ration

Inter site mixing ratio gives the probability that states state1 and state2 are localized on different pigments. This measure can be used to distinguish different types of coherence, e.g. vibrational from purely electronic.

Literature:

|Cit1| available at |citlink|_

Examples

>>> import quantarhei as qr
>>> agg = qr.TestAggregate("dimer-2")
>>> agg.set_coupling_by_dipole_dipole()
...
... # build and diagonalize
>>> agg.build()
>>> agg.diagonalize()

>>> print("{0:.4f}".format(agg.get_intersite_mixing(1,2)))
0.8362

get_transition_dipole(state1: int = 0, state2: int = 0) → float

Returns transition dipole moment between two state.

If the second state is not specified, we get transition to the first state from the ground state.

Parameters:

• state1 (int) – Starting state of the transition

• state2 (int) – Final states of the transition

Examples

>>> import quantarhei as qr
>>> agg = qr.TestAggregate("dimer-2")
>>> agg.set_coupling_by_dipole_dipole()
...
... # build and diagonalize
>>> agg.build()
>>> agg.diagonalize()
...
>>> a = agg.get_transition_dipole(0,1)
>>> print("{0:.6f}".format(a))
2.480265

get_state_energy(state: int = 0) → float | ndarray

Return the energy of a state with a given index

Parameters:

state (int) – Index of the state whose energy we ask for

Examples

>>> import quantarhei as qr
>>> agg = qr.TestAggregate("dimer-2")
>>> agg.set_coupling_by_dipole_dipole()
...
... # build and diagonalize
>>> agg.build()
>>> agg.diagonalize()
...
>>> print("{0:.4f}".format(agg.get_state_energy(2)))
2.3231

>>> with energy_units("1/cm"):
...     print("{0:.4f}".format(agg.get_state_energy(2)))
12332.9320

exciton_report(file: Any = None, start: int = 1, stop: int | None = None, Nrep: int = 5, criterium: Any = None) → None

Prints a report on excitonic properties of the aggregate

Parameters:

• start (int (default = 1)) – First state to report on. Because 0 is often the ground state, it is skipped. For systems with molecular vibrations, first mixed states start with an index different from 1.

• stop (int (default = None)) – Where to stop the report. if None, all states are reported

• Nrep (int (default = 5)) – How many sites of the exciton decomposition we should list

Examples

>>> import quantarhei as qr
>>> agg = qr.TestAggregate("dimer-2")
>>> agg.set_coupling_by_dipole_dipole()
...
... # build and diagonalize
>>> agg.build()
>>> agg.diagonalize()
...
>>> agg.exciton_report()
Report on excitonic properties
------------------------------

Exciton 1
=========

Transition energy        : 11967.06803045 1/cm
Transition dipole moment : 2.48026499 D
+-------+-------------+--------------+------------------+
| index | squares     | coefficients | state signatures |
+-------+-------------+--------------+------------------+
| 1     | 0.90998848  | -0.95393316  | ((1, 0), ())     |
| 2     | 0.09001152  | 0.30001920   | ((0, 1), ())     |
| 0     | 0.00000000  | 0.00000000   | ((0, 0), ())     |
| 0     | -1.00000000 | 0.00000000   | ((0, 0), ())     |
| 0     | -1.00000000 | 0.00000000   | ((0, 0), ())     |
+-------+-------------+--------------+------------------+

Exciton 2
=========

Transition energy        : 12332.93196955 1/cm
Transition dipole moment : 5.16973501 D
+-------+-------------+--------------+------------------+
| index | squares     | coefficients | state signatures |
+-------+-------------+--------------+------------------+
| 2     | 0.90998848  | 0.95393316   | ((0, 1), ())     |
| 1     | 0.09001152  | 0.30001920   | ((1, 0), ())     |
| 0     | 0.00000000  | 0.00000000   | ((0, 0), ())     |
| 0     | -1.00000000 | 0.00000000   | ((0, 0), ())     |
| 0     | -1.00000000 | 0.00000000   | ((0, 0), ())     |
+-------+-------------+--------------+------------------+

get_state_signature_by_index(N: int) → tuple

Return aggregate vibronic state signature by its index

Parameters:

N (int) – Index of state (or site). Signatures make sense only for localized states

Example

>>> import quantarhei as qr
>>> agg = qr.TestAggregate("dimer-2")
>>> agg.set_coupling_by_dipole_dipole()
...
... # build and diagonalize
>>> agg.build()
>>> agg.diagonalize()

>>> agg.get_state_signature_by_index(2)
((0, 1), ())