Molecule

Multi-level molecule (monomer)

The molecule is defined by the vector of energies of its states and by the transition dipole moments between allowed transitions.

>>> m = Molecule([0.0, 1.0])
>>> print(m.Nel)
2

Information about the molecule can be obtained simply by printing it

>>> print(m)
<BLANKLINE>
quantarhei.Molecule object
==========================
   name =
   position = None
   number of electronic states = 2
   # State properties
   State nr: 0 (ground state)
      electronic energy = 0.0 1/fs
      number of vibrational modes = 0
<BLANKLINE>
   State nr: 1
      electronic energy = 1.0 1/fs
      transition 0 -> 1
      transition dipole moment = [0.0, 0.0, 0.0]
      number of vibrational modes = 0
<BLANKLINE>

>>> import quantarhei as qr
>>> mol = qr.TestMolecule("two-levels-1-mode")
>>> print(mol)
<BLANKLINE>
quantarhei.Molecule object
==========================
   name = two-levels-1-mode
   position = None
   number of electronic states = 2
   # State properties
   State nr: 0 (ground state)
      electronic energy = 0.0 1/fs
      number of vibrational modes = 1
      # Mode properties
      mode no. = 0
         frequency = 1.0 1/fs
         shift = 0.0
         nmax = 2
   State nr: 1
      electronic energy = 1.0 1/fs
      transition 0 -> 1
      transition dipole moment = [0.0, 0.0, 0.0]
      number of vibrational modes = 1
      # Mode properties
      mode no. = 0
         frequency = 1.0 1/fs
         shift = 0.0
         nmax = 2

Class Details

class quantarhei.builders.molecules.Molecule(elenergies=[0.0, 1.0], name=None)

Multi-level molecule (monomer)

Parameters:

• name (str) – Monomer descriptor; a string identifying the monomer
• elenergies (list of real numbers) – List of electronic energies, one per state. It includes ground state energy. It wise to chose the ground state energy as zero.

Attributes:

dmoments

elenergies

nal

nel

nmod

position

Methods

add_Mode(mod)	Adds a vibrational mode to the monomer
build()	Building routine for the molecule
check_temperature_consistent()	Checks that the temperature is the same for all components
copy()	Returns a shallow copy of the self
deepcopy()	Returns a deep copy of the self
get_FoersterRateMatrix()	Returns Förster rate matrix for the open system
get_Hamiltonian([multi, recalculate])	Returns the Hamiltonian of the Molecule object
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_Mode(N)	Returns the Nth mode of the Molecule object
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 a SystemBathInteraction object of the molecule
get_TransitionDipoleMoment([multi])	Returns the transition dipole moment operator
get_adiabatic_coupling(state1, state2)	Returns adiabatic coupling between two states
get_diabatic_coupling(element)	Returns list of coupling descriptors
get_dipole(N[, M])	Returns the dipole vector for a given electronic transition
get_egcf(transition)
get_electronic_natural_lifetime(N[, epsilon_r])	Returns natural lifetime of a given electronic state
get_electronic_natural_linewidth(N)	Returns natural linewidth of a given electronic state
get_energy(N)	Returns energy of the Nth state of the molecule
get_excited_density_matrix([condition, …])	Returns the density matrix corresponding to excitation condition
get_mode_environment(mode, elstate)	Returns mode environment
get_number_of_modes()	Retruns the number of modes in this molecule
get_potential_1D(mode, points[, other_modes])	Returns the one dimensional diabatic potentials
get_potential_2D(modes, points[, other_modes])	Returns the two dimensional diabatic potentials
get_temperature()	Returns temperature of the molecule
get_thermal_ReducedDensityMatrix()	Returns equilibrium density matrix for a give temparature
get_transition_dephasing(transition)	Returns the dephasing rate of a given transition
get_transition_environment(transition)	Returns energy gap correlation function of a monomer
get_transition_width(transition)	Returns the transition width
liouville_pathways_1([eUt, ham, dtol, ptol, …])	Generator of the first order Liouville pathways
load(filename[, test])	Loads an object from a file and returns it
loaddir(dirname)	Returns a directory of objects saved into a directory
plot_dressed_sticks([dfce, xlims, nsteps, …])	Plots a stick spectrum dessed by a supplied function
plot_potential_1D(mode, points[, …])	Plots the potentials
plot_stick_spectrum([xlims, ylims, …])	Plots the stick spectrum of the molecule
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_adiabatic_coupling(state1, state2, coupl)	Sets adiabatic coupling between two states
set_diabatic_coupling(element, factor[, shifts])	Sets off-diagobal elements of the diabatic potential matrix
set_dipole(N, M[, vec])	Sets transition dipole moment for an electronic transition
set_egcf(transition, egcf)
set_egcf_mapping(transition, …)	Sets a correlation function mapping for a selected transition.
set_electronic_rwa(rwa_indices)	Sets which electronic states belong to different blocks
set_energy(N, en)	Sets the energy of the Nth state of the molecule
set_mode_environment([mode, elstate, corfunc])	Sets mode environment
set_transition_dephasing(transition, deph)	Sets the dephasing rate of a given transition
set_transition_environment(transition, egcf)	Sets a correlation function for a transition on this monomer
set_transition_width(transition, width)	Sets the width of a given transition
unset_transition_environment(transition)	Unsets correlation function from a transition on this monomer

convert_energy_2_current_u
convert_energy_2_internal_u
convert_length_2_current_u
convert_length_2_internal_u
get_diabatic_shifts
set_electronic_natural_lifetime
unit_repr
unit_repr_latex

add_Mode(mod)

Adds a vibrational mode to the monomer

Parameters:mod (quantarhei.Mode) – Intramolecular vibrational mode

Examples

>>> mode = Mode()
>>> mol = Molecule([0.0, 2.0])
>>> print(mol.get_number_of_modes())
0
>>> mol.add_Mode(mode)
>>> print(mol.get_number_of_modes())
1

build()

Building routine for the molecule

Unlike with the Aggregate, it is not compulsory to call build() before we start using the Molecule

check_temperature_consistent()

Checks that the temperature is the same for all components

Examples

Isolated molecule has always consistent temperature

>>> m = Molecule([0.0, 1.0, 1.2])
>>> print(m.check_temperature_consistent())
True

>>> from ..qm.corfunctions import CorrelationFunction
>>> from .. import TimeAxis
>>> ta = TimeAxis(0.0,1000,1.0)
>>> params1 = dict(ftype="OverdampedBrownian",
...                reorg=20,cortime=100,T=300)
>>> params2 = dict(ftype="OverdampedBrownian",
...                reorg=20,cortime=100,T=200)
>>> with energy_units("1/cm"):
...     cf1 = CorrelationFunction(ta, params1)
...     cf2 = CorrelationFunction(ta, params2)
>>> m.set_transition_environment((0,1), cf1)
>>> m.set_transition_environment((0,2), cf2)
>>> print(m.get_temperature())
Traceback (most recent call last):
...
Exception: Molecular environment has an inconsisten temperature

get_Hamiltonian(multi=True, recalculate=False)

Returns the Hamiltonian of the Molecule object

Examples

After the molecule is created, its Hamiltonian can be obtained

>>> import quantarhei as qr
>>> mol = qr.TestMolecule("two-levels-1-mode")
>>> H = mol.get_Hamiltonian()
>>> print(H.dim)
4

>>> print(H.data)
[[ 0.  0.  0.  0.]
 [ 0.  1.  0.  0.]
 [ 0.  0.  1.  0.]
 [ 0.  0.  0.  2.]]

The Hamiltonian is stored, and next time it is retrieved we obtain the same object.

>>> print(H.has_rwa)
False

We can manipulate with the Hamiltonian in between retrievals >>> H.set_rwa([0,1]) >>> print(H.has_rwa) True

The Hamiltonian the obtain the second time is affected by the changes performed outside the Molecule class

>>> H1 = mol.get_Hamiltonian()
>>> print(H1.has_rwa)
True

The newly obtained Hamiltonina IS the Hamiltonian obtained earlier.

>>> H1 is H
True

get_Mode(N)

Returns the Nth mode of the Molecule object

Parameters:N (int) – Index of the mode to be returned

Examples

>>> import quantarhei as qr
>>> mol = qr.TestMolecule("two-levels-1-mode")
>>> mod = mol.get_Mode(1)
Traceback (most recent call last):
    ...
IndexError: list index out of range

>>> mod = mol.get_Mode(0)
>>> mod.get_energy(1)
1.0

get_SystemBathInteraction()

Returns a SystemBathInteraction object of the molecule

get_TransitionDipoleMoment(multi=True)

Returns the transition dipole moment operator

get_adiabatic_coupling(state1, state2)

Returns adiabatic coupling between two states

get_diabatic_coupling(element)

Returns list of coupling descriptors

get_dipole(N, M=None)

Returns the dipole vector for a given electronic transition

There are two ways how to use this function:

1. recommended

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

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

2. 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 = Molecule([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_electronic_natural_lifetime(N, epsilon_r=1.0)

Returns natural lifetime of a given electronic state

get_electronic_natural_linewidth(N)

Returns natural linewidth of a given electronic state

get_energy(N)

Returns energy of the Nth state of the molecule

Parameters:N (int) – Index of the state

Examples

>>> import quantarhei as qr
>>> mol = qr.TestMolecule("two-levels-1-mode")
>>> mol.get_energy(1)
1.0

This methods reacts to the energy_units context manager

>>> with qr.energy_units("1/cm"):
...     print("{0:.8f}".format(mol.get_energy(1)))
5308.83745888

get_mode_environment(mode, elstate)

Returns mode environment

Returns the environment (bath correlation function) interacting with a a given mode in a given electronic state.

Parameters:

• mode (int) – index of the mode
• elstate (int) – index of the electronic state

get_number_of_modes()

Retruns the number of modes in this molecule

Examples

>>> m = Molecule([0.0, 1.0])
>>> m.get_number_of_modes()
0

>>> import quantarhei as qr
>>> m = qr.TestMolecule("two-levels-1-mode")
>>> m.get_number_of_modes()
1

get_potential_1D(mode, points, other_modes=None)

Returns the one dimensional diabatic potentials

get_potential_2D(modes, points, other_modes=None)

Returns the two dimensional diabatic potentials

get_temperature()

Returns temperature of the molecule

Checks if the setting of environments is consistent and than takes the temperature from one of the energy gaps. If no environment (correlation function) is assigned to this molecule, we assume zero temperature.

Examples

Default temperature is 0 K

>>> import quantarhei as qr
>>> mol = qr.TestMolecule("two-levels-1-mode")
>>> mol.get_temperature()
0.0

Molecule gets its temperature from the environment

>>> from ..qm.corfunctions import CorrelationFunction
>>> from .. import TimeAxis
>>> ta = TimeAxis(0.0,1000,1.0)
>>> params = dict(ftype="OverdampedBrownian",reorg=20,cortime=100,T=300)
>>> with energy_units("1/cm"):
...     cf = CorrelationFunction(ta, params)
>>> m = Molecule([0.0, 1.0])
>>> m.set_transition_environment((0,1), cf)
>>> print(m.get_temperature())
300

get_transition_dephasing(transition)

Returns the dephasing rate of a given transition

Parameters:transition ({tuple, list}) – Quantum numbers of the states between which the transition occurs

get_transition_environment(transition)

Returns energy gap correlation function of a monomer

Parameters:transition (tuple) – A tuple describing a transition in the molecule, e.g. (0,1) is a transition from the ground state to the first excited state.

Example

>>> m = Molecule([0.0, 1.0])

Environment of the transition has to be set first

>>> cc = m.get_transition_environment((0,1))
Traceback (most recent call last):
    ...
Exception: No environment set for the transition

Environment is characterized by the bath correlation function

>>> from ..qm.corfunctions import CorrelationFunction
>>> from .. import TimeAxis
>>> ta = TimeAxis(0.0,1000,1.0)
>>> params = dict(ftype="OverdampedBrownian",reorg=20,cortime=100,T=300)
>>> with energy_units("1/cm"):
...     cf = CorrelationFunction(ta, params)
>>> m.set_transition_environment((0,1), cf)
>>> cc = m.get_transition_environment((0,1))
>>> cc == cf
True

When non-existent transition is tried, exception is raised

>>> cc = m.get_transition_environment((0,2))
Traceback (most recent call last):
    ...
Exception: Index out of range

get_transition_width(transition)

Returns the transition width

Returns the full width at half maximum (FWHM) of a Gaussian lineshape, or half width at half maximum (HWHM) of a Lorentzian lineshape

Parameters:transition ({tuple, list}) – Quantum numbers of the states between which the transition occurs

liouville_pathways_1(eUt=None, ham=None, dtol=0.01, ptol=0.001, etol=1e-06, verbose=0, lab=None)

Generator of the first order Liouville pathways

Generator of the pathways for an absorption spectrum calculation.

Parameters:eUt (EvolutionSuperOperator) – Evolution superoperator representing the evolution of optical coherence in the system

dtol : float

Minimum acceptable strength of the transition from ground to excited state, relative to the maximum dipole strength available in the system

ptol : float

Minimum acceptable population of the ground state (e.g. states not thermally populated are excluded)

lab : LaboratorySetup

Object representing laboratory setup - number of pulses, polarization etc.

Returns:lst – List of LiouvillePathway objects Return type:list

plot_dressed_sticks(dfce=None, xlims=[0, 1], nsteps=1000, show_zero_coupling=False, show=True)

Plots a stick spectrum dessed by a supplied function

plot_potential_1D(mode, points, other_modes=None, nonint=True, states=None, energies=True, show=True, ylims=None)

Plots the potentials

plot_stick_spectrum(xlims=[0.0, 1.0], ylims=None, show_zero_coupling=False, show=True)

Plots the stick spectrum of the molecule

set_adiabatic_coupling(state1, state2, coupl)

Sets adiabatic coupling between two states

set_diabatic_coupling(element, factor, shifts=None)

Sets off-diagobal elements of the diabatic potential matrix

set_dipole(N, M, vec=None)

Sets transition dipole moment for an electronic transition

There are two ways how to use this function:

1. recommended

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

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

2. deprecated (used in earlier versions of quantarhei)

   set_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 = Molecule([0.0, 1.0])
>>> m.set_dipole((0,1),[1.0, 0.0, 0.0])
>>> m.get_dipole((0,1))
array([ 1.,  0.,  0.])

set_egcf_mapping(transition, correlation_matrix, position)

Sets a correlation function mapping for a selected transition.

The monomer can either have a correlation function assigned to it, or it can be a part of a correlation matrix. Here the mapping to the correlation matrix is specified.

Parameters:

• transition (tuple) – A tuple describing a transition in the molecule, e.g. (0,1) is a transition from the ground state to the first excited state.
• correlation_matrix (CorrelationFunctionMatrix) – An instance of CorrelationFunctionMatrix
• position (int) – Position in the CorrelationFunctionMatrix corresponding to the monomer.

Examples

A set of three monomers

>>> en1 = [0.0,12100, 13000] #*cm2int]
>>> en2 = [0.0,12000] #*cm2int]
>>> with energy_units("1/cm"):
...     m1 = Molecule(en1)
...     m2 = Molecule(en1)
...     m3 = Molecule(en2)

Bath correlation functions to describe molecular environment

>>> from .. import TimeAxis
>>> from .. import CorrelationFunction
>>> time = TimeAxis(0.0, 2000, 1.0) # in fs
>>> temperature = 300.0 # in Kelvins
>>> cfce_params1 = dict(ftype="OverdampedBrownian",
...           reorg=30.0,
...           cortime=60.0,
...           T=temperature)
>>> cfce_params2 = dict(ftype="OverdampedBrownian",
...           reorg=30.0,
...           cortime=60.0,
...           T=temperature)
>>> with energy_units("1/cm"):
...    cf1 = CorrelationFunction(time,cfce_params1)
...    cf2 = CorrelationFunction(time,cfce_params2)

Environment of the molecules is collected to a matrix. A smaller number of correlation functions can be assigned to a large number of “sites”.

>>> cm = CorrelationFunctionMatrix(time,3)
>>> ic1 = cm.set_correlation_function(cf1,[(0,0),(2,2)])
>>> ic2 = cm.set_correlation_function(cf2,[(1,1)])

The sites of the in the matrix are assigned to molecules.

>>> m1.set_egcf_mapping((0,1), cm, 0)
>>> m2.set_egcf_mapping((0,1), cm, 1)
>>> m3.set_egcf_mapping((0,1), cm, 2)

The environment cannot be set twice

>>> m1.set_egcf_mapping((0,1), cm, 2)
Traceback (most recent call last):
    ...
Exception: Monomer has a correlation function already

>>> m1.set_egcf_mapping((0,2), cm, 2)
>>> m1.set_egcf_mapping((0,2), cm, 2)
Traceback (most recent call last):
    ...
Exception: Monomer has a correlation function already

set_electronic_rwa(rwa_indices)

Sets which electronic states belong to different blocks

Setting the indices of blocks should allow the construction of Rotating Wave Approximation for the Hamiltonian. This in turn is used for the calculations of optical spectra.

Examples

>>> with energy_units("1/cm"):
...     mol1 = Molecule([0.0, 10000.0])
>>> mol1.set_electronic_rwa([0, 1])
>>> H = mol1.get_Hamiltonian()
>>> H.has_rwa
True

>>> with energy_units("1/cm"):
...     mol2 = Molecule([0.0, 10000.0, 10500.0, 20000.0])

>>> with energy_units("1/cm"):
...     mod2 = Mode(frequency=200.0)
...     mol2.add_Mode(mod2)
>>> mod2.set_nmax(0, 5)
>>> mod2.set_nmax(1, 4)
>>> mod2.set_nmax(2, 5)
>>> mod2.set_nmax(3, 3)

>>> mol2.set_electronic_rwa([0, 1, 3])
>>> H = mol2.get_Hamiltonian()
>>> H.has_rwa
True

>>> print(H.rwa_indices)
[ 0  5 14]

set_energy(N, en)

Sets the energy of the Nth state of the molecule

Parameters:

• N (int) – Index of the state
• en (float) – Energy to be assigned to the Nth state.

Examples

>>> import quantarhei as qr
>>> mol = qr.TestMolecule("two-levels-1-mode")
>>> mol.set_energy(1, 1.5)
>>> mol.get_energy(1)
1.5

This method reacts to the energy_units context manager

>>> import quantarhei as qr
>>> mol = qr.TestMolecule("two-levels-1-mode")
>>> with qr.energy_units("1/cm"):
...     mol.set_energy(1, 5308.8374588761453)
>>> mol.get_energy(1)
1.0

set_mode_environment(mode=0, elstate=0, corfunc=None)

Sets mode environment

Sets the environment (bath correlation function) interacting with a a given mode in a given electronic state.

Parameters:

• mode (int) – index of the mode
• elstate (int) – index of the electronic state
• corfunc (quantarhei.CorrelationFunction) – CorrelationFunction object

set_transition_dephasing(transition, deph)

Sets the dephasing rate of a given transition

Parameters:

• transition ({tuple, list}) – Quantum numbers of the states between which the transition occurs
• deph (float) – Dephasing rate of the transition

set_transition_environment(transition, egcf)

Sets a correlation function for a transition on this monomer

Parameters:

• transition (tuple) – A tuple describing a transition in the molecule, e.g. (0,1) is a transition from the ground state to the first excited state.
• egcf (CorrelationFunction) – CorrelationFunction object

Example

>>> from ..qm.corfunctions import CorrelationFunction
>>> from .. import TimeAxis
>>> ta = TimeAxis(0.0,1000,1.0)
>>> params = dict(ftype="OverdampedBrownian",reorg=20,cortime=100,T=300)
>>> with energy_units("1/cm"):
...     cf = CorrelationFunction(ta, params)
>>> m = Molecule([0.0, 1.0])
>>> m.set_transition_environment((0,1), cf)
>>> print(m._has_system_bath_coupling)
True

When the environment is already set, the next attempt is refused

>>> m.set_transition_environment((0,1), cf)
Traceback (most recent call last):
...
Exception: Correlation function already speficied for this monomer

The environment cannot be set when the molecule is mapped on a correlation function matrix

>>> with energy_units("1/cm"):
...     cf1 = CorrelationFunction(ta, params)
>>> cm = CorrelationFunctionMatrix(ta,1)
>>> ic1 = cm.set_correlation_function(cf1,[(0,0)])
>>> m1 = Molecule([0.0, 1.0])
>>> m1.set_egcf_mapping((0,1), cm, 0)
>>> m1.set_transition_environment((0,1), cf1)
Traceback (most recent call last):
    ...
Exception: This monomer is mapped on a CorrelationFunctionMatrix

set_transition_width(transition, width)

Sets the width of a given transition

Parameters:

• transition ({tuple, list}) – Quantum numbers of the states between which the transition occurs
• width (float) – The full width at half maximum (FWHM) of a Gaussian lineshape, or half width at half maximum (HWHM) of a Lorentzian lineshape

unset_transition_environment(transition)

Unsets correlation function from a transition on this monomer

This is needed if the environment is to be replaced

Parameters:transition (tuple) – A tuple describing a transition in the molecule, e.g. (0,1) is a transition from the ground state to the first excited state.

Example

>>> from ..qm.corfunctions import CorrelationFunction
>>> from .. import TimeAxis
>>> ta = TimeAxis(0.0,1000,1.0)
>>> params = dict(ftype="OverdampedBrownian",reorg=20,cortime=100,T=300)
>>> with energy_units("1/cm"):
...     cf = CorrelationFunction(ta, params)
>>> m = Molecule([0.0, 1.0])
>>> m.set_transition_environment((0,1), cf)
>>> print(m._has_system_bath_coupling)
True

>>> m.unset_transition_environment((0,1))
>>> print(m._has_system_bath_coupling)
False

When the environment is unset, the next attempt to set is succesful

>>> m.set_transition_environment((0,1), cf)
>>> print(m._has_system_bath_coupling)
True

The environment cannot be unset when the molecule is mapped on a correlation function matrix

>>> with energy_units("1/cm"):
...     cf1 = CorrelationFunction(ta, params)
>>> cm = CorrelationFunctionMatrix(ta,1)
>>> ic1 = cm.set_correlation_function(cf1,[(0,0)])
>>> m1 = Molecule([0.0, 1.0])
>>> m1.set_egcf_mapping((0,1), cm, 0)
>>> m1.unset_transition_environment((0,1))
Traceback (most recent call last):
    ...
Exception: This monomer is mapped on a CorrelationFunctionMatrix