tsh

libra_py.tsh.Boltz_corr_Ham(H, Coeff, T, case=1)[source]

This function implements the computation of the effective Hamiltonian used in the Boltzmann-corrected Ehrenfest method of Bastida et al.

Ref: Bastida, A.; Cruz, C.; Zuniga, J.; Requena, A.; Miguel, B. “A modified Ehrenfest method that achieves Boltzmann quantum state populations” Chem. Phys. Lett. 2006, 417, 53-57

Parameters

  • H (CMATRIX(N,N)) – original vibronic Hamiltonian [units: a.u.]

  • Coeff (CMATRIX(N,1)) – amplitudes of the basis states

  • T (double) – bath temperature [ units: K]

  • case (int) –

    selection of the type of the Hamiltonian

Returns

the effective Hamiltonian to be used in the calculations

Return type

CMATRIX(N,N)

libra_py.tsh.boltz_factor(E_new, E_old, T, boltz_opt)[source]

Compute the Boltzmann scaling factor, but only if we consider a hop up in energy

Parameters

  • E_new (double) – the energy of the proposed (new) state [units: a.u.]

  • E_old (double) – the energy of the current (old) state [units: a.u.]

  • T (double) – temperature of the bath [units: K]

  • boltz_opt (int) –

    the proposed hop acceptance criterion

    • 0: all hops are accepted

    • 1: hops are accepted according to the Boltzmann ratio of the final and initial states

    • 2: hops are accepted according to the classical Maxwell-Boltzmann distribution

    • 3: hops are accepted based on the quantum probability of the final state

Returns

boltz_f: the probability of the proposed hop acceptance

Return type

double

libra_py.tsh.collapse(Coeff, i)[source]

Collapse the wfc but such that to preserve the phase!

Parameters

  • Coeff (CMATRIX(N, 1)) – amplitudes of the electronic states in a coherent superposition which we are going to collapse

  • i (int) – The index of the state onto which the supeposition will be collapsed

Returns

but changes the input variable Coeff

Return type

None

libra_py.tsh.dish_py(Coeff, istate, t_m, tau_m, Hvib, boltz_opt, T, ksi1, ksi2)[source]

Decoherence-induced surface hopping (DISH) Reference: Jaeger, H. M.; Fischer, S.; Prezhdo, O. V. Decoherence-Induced Surface Hopping. J. Chem. Phys. 2012, 137, 22A545.

Parameters

  • Coeff (CMATRIX(N, 1)) – Amplitudes of electronic states

  • istate (int) – Initial state index

  • t_m (MATRIX(N, 1)) – Matrix of the times each state resides in a coherence interval since the last decoherence event [ units: a.u. ]

  • tau_m (MATRIX(N, 1)) – Matrix of the coherence intervals for each electronic state [ units: a.u. ]

  • Hvib (CMATRIX(N, N)) – Vibronic Hamiltonian matrix [ units: Ha ]

  • boltz_opt (int) –

    The selector of the proposed hop acceptance algorithm:

    • 0: all proposed hops are accepted - no rejection based on energies

    • 1: proposed hops are accepted with exp(-E/kT) probability - the old (hence the default approach)

    • 2: proposed hops are accepted with the probability derived from Maxwell-Boltzmann distribution - more rigorous

    • 3: generalization of “1”, but actually it should be changed in case there are many degenerate levels

  • T (double) – temperature [ units: K ]

  • ksi (double) – random number in interval [0.0, 1.0] cotrolling the execution of SH

  • ksi2 (double) – random number in interval [0.0, 1.0] cotrolling the execution of SH

Returns

fstat: the index of the electronic state after the “hop” (old state index or a new one)

Return type

int

Note

The function also modifies the Coeff and t_m variables

libra_py.tsh.hop_py(initstate, g, ksi)[source]

The Python implementation of the stochastic hopping procedure

Parameters

  • initstate (int) – The index of the initial state, before hop

  • g (MATRIX(N, N)) – The surface hopping matrix, the element g(i,j) contains the probability for a i->j transition. Here, N - is the total number of states considered in the transitions

  • ksi (double) – A random number uniformly distributed in the range of (0.0, 1.0) Essentially, it determines the outcome of the procedure

Returns

finstate: The index of the final state after hop

Return type

int

libra_py.tsh.hopping(Coeff, Hvib, istate, sh_method, do_collapse, ksi, ksi2, dt, T, boltz_opt=1)[source]

A simplified version for the CPA-like hopping

Parameters

  • Coeff (CMATRIX(nstates, 1)) – amplitudes of all states

  • Hvib (CMATRIX(nstates, nstates)) – vibronic Hamiltonian

  • istate (int) – the index of the initial state

  • sh_method (int) –

    selector of the TSH method:

    • 0: MSSH

    • 1: FSSH

    • 2: GFSH

  • do_collapse (int) –

    flag to turn on the decoherence via ID-A:

    • 0 - no decoherence

    • 1 - decoherence via ID-A

  • ksi (double) – random number in interval [0.0, 1.0] cotrolling the execution of SH

  • ksi2 (double) – random number in interval [0.0, 1.0] cotrolling the execution of SH

  • dt (double) – the time interval for the surface hopping [ units: a.u. ]

  • T (double) – temperature [ units: K ]

  • boltz_opt (int) –

    The selector of the proposed hop acceptance algorithm:

    • 0: all proposed hops are accepted - no rejection based on energies

    • 1: proposed hops are accepted with exp(-E/kT) probability - the old (hence the default approach)

    • 2: proposed hops are accepted with the probability derived from Maxwell-Boltzmann distribution - more rigorous

    • 3: generalization of “1”, but actually it should be changed in case there are many degenerate levels

Returns

( istate, Coeff1 ): where:

  • istate ( int ): index of the final state, after the hop

  • Coeff1 ( CMATRIX(N, 1) ): the updated state of the electronic DOF

Return type

tuple

libra_py.tsh.ida_py(Coeff, old_st, new_st, E_old, E_new, T, ksi, do_collapse, boltz_opt=1)[source]

The Python implementation of the instantaneous decoherence at attempted hops algorithm

This function takes care of a single act of decoherence/hop

Parameters

  • Coeff (CMATRIX(N, 1) or Electronic) – An object containig electronic DOFs (basis wavefunctions amplitudes). Here, N would be the number of electronic states in the dynamical basis

  • old_st (int) – The state index before hop

  • new_st (int) – The state index after hop

  • E_old (double) – The energy of the initial state, before hop [ units: a.u. ]

  • E_new (double) – The energy of the final state, after hop [ units: a.u. ]

  • T (double) – The Temperature of nuclear DOF [ units: K]

  • ksi (double) – A random number uniformly distributed in the range of [0.0, 1.0]

  • do_collapse (int) –

    The flag turning the decoherence (at the IDA level on/off):

    • 0: do not include decoherence

    • 1: include decoherence

  • boltz_opt (int) –

    The proposed hop acceptance criterion:

    • 0: all proposed hops are accepted - no rejection based on energies

    • 1: proposed hops are accepted with min{ 1, exp(-dE/kT) } probability, where

      dE = E_new - E_old [ default ]

    • 2: proposed hops are accepted with the probability derived from Maxwell-Boltzmann distribution - more rigorous

    • 3: generalization of “1”, but actually it should be changed in case there are many degenerate levels

Returns

( res, C ): where:

  • res ( int ): index of the final state, after IDA is applied (or not)

  • C ( CMATRIX(N, 1) or Electronic ): the updated state of the electronic DOF, in the same data type as the input

Return type

tuple

libra_py.tsh.project_out(Coeff, i)[source]

Projects the state i out of a coherent superposition of states

Parameters

  • Coeff (CMATRIX(N, 1)) – amplitudes of the electronic states in a coherent superposition from which we will project a state out

  • i (int) – The index of the state to be projected out

Returns

but changes the input variable Coeff

Return type

None

libra_py.tsh.sample(x, mean_x, sigma_x, rnd)[source]

This function generates ntraj ndof-dimensional vectors sampled from a normal distribution with a given mean and variance

Parameters

  • x (MATRIX(ndof, ntraj)) – Each column of the matrix corresponds to a vector of certain properties (e.g. coordinates, momenta, of all DOFs) for a given trajectory (element of ensemble)

  • mean_x (MATRIX(ndof, 1)) – The mean of the ndof-dimensional vector (component-wise)

  • sigma_x (MATRIX(ndof, 1)) – The variance width for each component

  • rnd (Random) – The random number generator object

Returns

but changes the matrix `x`

Return type

None

libra_py.tsh.sdm_py(Coeff, dt, act_st, En, Ekin, C_param=1.0, eps_param=0.1)[source]

Python implementation of the simplified decay of mixing algorithm for decoherence correction

Reference: Granucci, G.; Persico, M. J. Chem. Phys. 2007, 126, 134114

Parameters

  • Coeff (CMATRIX(N, 1) or Electronic) – An object containig electronic DOFs (basis wavefunctions amplitudes). Here, N would be the number of electronic states in the dynamical basis

  • dt (double) – Nuclear integration time-step [ units: a.u. ]

  • act_st (int) – The current active state index

  • En (list of doubles) – Energies of the states [ units: Ha ]

  • Ekin (double) – The classical kinetic energy of nuclei [ units: Ha ]

  • C_param (double) – The method parameter [ units: None, default: 1.0]

  • eps_param (double) – The method parameter [ units: Ha, default: 0.1 Ha ]

Returns

C :

the updated state of the electronic DOF, in the same data type as the input

Return type

( CMATRIX(N, 1) or Electronic )

libra_py.tsh.set_random_state(prob, ksi)[source]

This function implements a simple random state selection procedure. Each state is selected with a given probability

Parameters

  • prob (list of N doubles) – The probabilities of all N states

  • ksi (double) – A random number uniformly distributed in the range of (0.0, 1.0). It determines the outcome of this function.

Returns

finstate: The index of the selected state

Return type

integer

libra_py.tsh.surface_hopping(mol, el, ham, rnd, params)[source]

This function performs either generic or NBRA-type surface hopping

Here, the number of nuclear objects and that of electronic ones may be not equal. Each trajectory evolves both nuclear and electronic DOFs, as appropriate for the most general TSH recipe, but one can execute multiple TSH realizations per selected-electron-nuclear dynamics

Parameters

  • mol (list of Nuclear objects) – variables that contains classical DOFs for each trajectory

  • el (list of Electronic objects) – variables that contains quantum DOFs for each trajectory

  • ham (list of Hamiltonian objects) – variables that control energy/forces calculations for each trajectory

  • rnd (Random object) – a random number generator object. It is important that we use the same (global) object every time this function is called. If we create it here and use - the statistical properties will be very poor, because every new “random” number will be not far from the common seed value

  • params (dictionary) –

    control parameters, specifically:

    • params[“tsh_method”] ( int ): choose the hopping probability calculation scheme

      • 1: FSSH [default]

      • 2: GFSH

      • 3: MSSH

    • params[“rep”] ( int ): choose the representation for velocity rescaling

      • 0: diabatic (uniform rescaling)

      • 1: adiabatic (need the derivative couplings) [default]

    • params[“do_rescaling”] ( int ): choose how to account for detailed balance

      • 0: don’t do explicit rescaling, so it is used with Boltzmann factor hopping probability scaling

      • 1: do the excplicit velocity rescaling [default]

    • params[“do_reverse”] ( int ): how to handle the nuclear velocities when hop is frustrated

      • 0: keep as they are, don’t change

      • 1: reverse the velocities [default]

    • params[“dt_nucl”] ( double): nuclear time step [ units: fs, default: 1.0 TODO: check units ]

    • params[“Temperature”] ( double ): Temperature of the environment [ units: K, default: 300.0 ]

    • params[“print_tsh_probabilities”] ( int ): Print hopping probabilities matrix

      • 0: don’t print [default]

      • 1: print

    • params[“check_tsh_probabilities”] ( int ): Run-time sanity test of the dt_nucl,

      • 0: don’t check

      • 1: check [default]

    • params[“use_boltz_factor”] ( int ): whether to scale the hopping probabilities by the Boltzmann factor

      • 0: don’t scale [default]

      • 1: scale

    • params[“nconfig”] ( int ): how many distinct initial nuclear geometries

    • **params[“excitations_init”] ( list of ints ): indices of excited states to which

      each initial geometry may be excited, multiplies the total number of distinct electron-nuclear evolutions

    • params[“num_SH_traj”] ( int ): the number of electronic evolutions per initial

      geometry per initial excitation

Returns

but the following variables are changed

  • mol

  • el

  • ham

Return type

None

libra_py.tsh.surface_hopping_cpa(mol, el, ham, rnd, params)[source]

This function performs surface hopping with Boltzmann factor used to rescale hopping probabilities in lieu of explicit velocity rescaling

Parameters

SeeAlso – surface_hopping

Returns

surface_hopping

Return type

SeeAlso

libra_py.tsh.surface_hopping_cpa2(mol, el, ham, rnd, params)[source]

This function performs surface hopping with velocity rescaling according to total energy conservation (but not along the derivative coupling vectors)

Parameters

SeeAlso – surface_hopping

Returns

surface_hopping

Return type

SeeAlso