Trajectory Methods

The classes documented here are responsible for running molecular dynamics simulations with different algorithms.

class TrajectorySH(model: Any, x0: Type[ndarray], p0: Type[ndarray], rho0: Type[ndarray], tracer: Optional[Any] = None, queue: Optional[Any] = None, **options: Any)

Bases: object

Class to propagate a single FSSH trajectory

NAC_matrix(electronics: Optional[ElectronicT] = None, velocity: Optional[Type[ndarray]] = None) → Type[ndarray]

Nonadiabatic coupling matrix

Parameters

  • electronics – ElectronicStates from current step

  • velocity – velocity used to compute NAC (defaults to self.velocity)

Returns

[nstates, nstates] NAC matrix

advance_position(last_electronics: Optional[ElectronicT], this_electronics: ElectronicT) → None

Move classical position forward one step

Parameters

  • last_electronics – ElectronicStates from previous step

  • this_electronics – ElectronicStates from current step

advance_velocity(last_electronics: ElectronicT, this_electronics: ElectronicT) → None

Move classical velocity forward one step

Parameters

electronics – ElectronicStates from current step

clone() → TrajectorySH

Clone existing trajectory for spawning

Returns

copy of current object

continue_simulating() → bool

Decide whether trajectory should keep running

Returns

True if trajectory should keep running, False if it should finish

currently_interacting() → bool

Determines whether trajectory is currently inside an interaction region

Returns

boolean

direction_of_rescale(source: int, target: int, electronics: Optional[ElectronicT] = None) → ndarray

Return direction in which to rescale momentum

Parameters

  • source – active state before hop

  • target – active state after hop

  • electronics – electronic model information (used to pull derivative coupling)

Returns

unit vector pointing in direction of rescale

draw_new_zeta() → float

Returns a new zeta value for hopping. First it checks the input list of zeta values in self.zeta_list. If no value is found in zeta_list, then a random number is pulled.

Returns

zeta

duration_initialize(options: Dict[str, Any]) → None

Initializes variables related to continue_simulating

Parameters

options – dictionary with options

hamiltonian_propagator(last_electronics: ElectronicT, this_electronics: ElectronicT, velo: Optional[Type[ndarray]] = None) → ndarray

Compute the Hamiltonian used to propagate the electronic wavefunction

Parameters

elec_states – ElectronicStates at current time step

Returns

nonadiabatic coupling H - i W at midpoint between current and previous time steps

hop_allowed(direction: Type[ndarray], dE: float)

Returns whether a hop with the given rescale direction and requested energy change is allowed

Parameters

  • direction – momentum unit vector

  • dE – change in energy such that Enew = Eold + dE

Returns

whether to hop

hop_to_it(hop_targets: List[Dict[str, Union[float, int]]], electronics: Optional[ElectronicT] = None) → None

Hop from the current active state to the given state, including rescaling the momentum

Parameters

  • hop_targets – list of (target, weight) pairs

  • electronics – ElectronicStates for current step

hop_update(hop_from, hop_to)

Handle any extra operations that need to occur after a hop

hopper(gkndt: ndarray) → List[Dict[str, float]]

Determine whether and where to hop

Parameters

probs – [nstates] numpy array of individual hopping probabilities

Returns

[(target_state, weight)] list of (target_state, weight) pairs

kinetic_energy() → float64

Kinetic energy

Returns

kinetic energy

mode_kinetic_energy(direction: Type[ndarray]) → float64

Kinetic energy along given momentum mode

Parameters

direction – [ndim] numpy array defining direction

Returns

kinetic energy along specified direction

potential_energy(electronics: Optional[ElectronicT] = None) → Union[float64, complex128]

Potential energy

Parameters

electronics – ElectronicStates from current step

Returns

potential energy

propagate_electronics(last_electronics: ElectronicT, this_electronics: ElectronicT, dt: Union[float64, complex128]) → None

Propagates density matrix from t to t+dt

The propagation assumes the electronic energies and couplings are static throughout. This will only be true for fairly small time steps

Parameters

  • elec_states – ElectronicStates at t

  • dt – time step

random() → float64

Get random number for hopping decisions

Returns

uniform random number between 0 and 1

rescale_component(direction: Type[ndarray], reduction: Union[float64, complex128]) → None

Updates velocity by rescaling the momentum in the specified direction and amount

Parameters

  • direction – the direction of the momentum to rescale

  • reduction – how much kinetic energy should be damped

simulate() → Trace

Simulate

Returns

Trace of trajectory

snapshot() → Dict[str, Any]

Collect data from run for logging

Returns

dictionary with all data from current time step

surface_hopping(last_electronics: ElectronicT, this_electronics: ElectronicT)

Compute probability of hopping, generate random number, and perform hops

Parameters

elec_states – ElectronicStates from current step

total_energy(electronics: Optional[ElectronicT] = None) → Union[float64, complex128]

Kinetic energy + Potential energy

Parameters

electronics – ElectronicStates from current step

Returns

total energy

trace(force: bool = False) → None

Add results from current time point to tracing function Only adds snapshot if nsteps%trace_every == 0, unless force=True

Parameters

force – force snapshot

update_weight(weight: float) → None

Update weight held by trajectory and by trace

class Ehrenfest(*args: Any, **kwargs: Any)

Bases: TrajectorySH

Ehrenfest dynamics

NAC_matrix(electronics: Optional[ElectronicT] = None, velocity: Optional[Type[ndarray]] = None) → Type[ndarray]

Nonadiabatic coupling matrix

Parameters

  • electronics – ElectronicStates from current step

  • velocity – velocity used to compute NAC (defaults to self.velocity)

Returns

[nstates, nstates] NAC matrix

advance_position(last_electronics: Optional[ElectronicT], this_electronics: ElectronicT) → None

Move classical position forward one step

Parameters

  • last_electronics – ElectronicStates from previous step

  • this_electronics – ElectronicStates from current step

advance_velocity(last_electronics: ElectronicT, this_electronics: ElectronicT) → None

Move classical velocity forward one step

Parameters

electronics – ElectronicStates from current step

clone() → TrajectorySH

Clone existing trajectory for spawning

Returns

copy of current object

continue_simulating() → bool

Decide whether trajectory should keep running

Returns

True if trajectory should keep running, False if it should finish

currently_interacting() → bool

Determines whether trajectory is currently inside an interaction region

Returns

boolean

direction_of_rescale(source: int, target: int, electronics: Optional[ElectronicT] = None) → ndarray

Return direction in which to rescale momentum

Parameters

  • source – active state before hop

  • target – active state after hop

  • electronics – electronic model information (used to pull derivative coupling)

Returns

unit vector pointing in direction of rescale

draw_new_zeta() → float

Returns a new zeta value for hopping. First it checks the input list of zeta values in self.zeta_list. If no value is found in zeta_list, then a random number is pulled.

Returns

zeta

duration_initialize(options: Dict[str, Any]) → None

Initializes variables related to continue_simulating

Parameters

options – dictionary with options

hamiltonian_propagator(last_electronics: ElectronicT, this_electronics: ElectronicT, velo: Optional[Type[ndarray]] = None) → ndarray

Compute the Hamiltonian used to propagate the electronic wavefunction

Parameters

elec_states – ElectronicStates at current time step

Returns

nonadiabatic coupling H - i W at midpoint between current and previous time steps

hop_allowed(direction: Type[ndarray], dE: float)

Returns whether a hop with the given rescale direction and requested energy change is allowed

Parameters

  • direction – momentum unit vector

  • dE – change in energy such that Enew = Eold + dE

Returns

whether to hop

hop_to_it(hop_targets: List[Dict[str, Union[float, int]]], electronics: Optional[ElectronicT] = None) → None

Hop from the current active state to the given state, including rescaling the momentum

Parameters

  • hop_targets – list of (target, weight) pairs

  • electronics – ElectronicStates for current step

hop_update(hop_from, hop_to)

Handle any extra operations that need to occur after a hop

hopper(gkndt: ndarray) → List[Dict[str, float]]

Determine whether and where to hop

Parameters

probs – [nstates] numpy array of individual hopping probabilities

Returns

[(target_state, weight)] list of (target_state, weight) pairs

kinetic_energy() → float64

Kinetic energy

Returns

kinetic energy

mode_kinetic_energy(direction: Type[ndarray]) → float64

Kinetic energy along given momentum mode

Parameters

direction – [ndim] numpy array defining direction

Returns

kinetic energy along specified direction

potential_energy(electronics: Optional[ElectronicT] = None) → Union[float64, complex128]

Ehrenfest potential energy = tr(rho * H)

Parameters

electronics – ElectronicStates from current step

propagate_electronics(last_electronics: ElectronicT, this_electronics: ElectronicT, dt: Union[float64, complex128]) → None

Propagates density matrix from t to t+dt

The propagation assumes the electronic energies and couplings are static throughout. This will only be true for fairly small time steps

Parameters

  • elec_states – ElectronicStates at t

  • dt – time step

random() → float64

Get random number for hopping decisions

Returns

uniform random number between 0 and 1

rescale_component(direction: Type[ndarray], reduction: Union[float64, complex128]) → None

Updates velocity by rescaling the momentum in the specified direction and amount

Parameters

  • direction – the direction of the momentum to rescale

  • reduction – how much kinetic energy should be damped

simulate() → Trace

Simulate

Returns

Trace of trajectory

snapshot() → Dict[str, Any]

Collect data from run for logging

Returns

dictionary with all data from current time step

surface_hopping(last_electronics: ElectronicT, this_electronics: ElectronicT)

Ehrenfest never hops

total_energy(electronics: Optional[ElectronicT] = None) → Union[float64, complex128]

Kinetic energy + Potential energy

Parameters

electronics – ElectronicStates from current step

Returns

total energy

trace(force: bool = False) → None

Add results from current time point to tracing function Only adds snapshot if nsteps%trace_every == 0, unless force=True

Parameters

force – force snapshot

update_weight(weight: float) → None

Update weight held by trajectory and by trace

class TrajectoryCum(*args: Any, **kwargs: Any)

Bases: TrajectorySH

Trajectory surface hopping using a cumulative approach rather than instantaneous

Instead of using a random number generator at every time step to test for a hop, hops occur when the cumulative probability of a hop crosses a randomly determined threshold. Swarmed results should be identical to the traditional variety, but should be a bit easier to reproduce since far fewer random numbers are ever needed.

NAC_matrix(electronics: Optional[ElectronicT] = None, velocity: Optional[Type[ndarray]] = None) → Type[ndarray]

Nonadiabatic coupling matrix

Parameters

  • electronics – ElectronicStates from current step

  • velocity – velocity used to compute NAC (defaults to self.velocity)

Returns

[nstates, nstates] NAC matrix

advance_position(last_electronics: Optional[ElectronicT], this_electronics: ElectronicT) → None

Move classical position forward one step

Parameters

  • last_electronics – ElectronicStates from previous step

  • this_electronics – ElectronicStates from current step

advance_velocity(last_electronics: ElectronicT, this_electronics: ElectronicT) → None

Move classical velocity forward one step

Parameters

electronics – ElectronicStates from current step

clone() → TrajectorySH

Clone existing trajectory for spawning

Returns

copy of current object

continue_simulating() → bool

Decide whether trajectory should keep running

Returns

True if trajectory should keep running, False if it should finish

currently_interacting() → bool

Determines whether trajectory is currently inside an interaction region

Returns

boolean

direction_of_rescale(source: int, target: int, electronics: Optional[ElectronicT] = None) → ndarray

Return direction in which to rescale momentum

Parameters

  • source – active state before hop

  • target – active state after hop

  • electronics – electronic model information (used to pull derivative coupling)

Returns

unit vector pointing in direction of rescale

draw_new_zeta() → float

Returns a new zeta value for hopping. First it checks the input list of zeta values in self.zeta_list. If no value is found in zeta_list, then a random number is pulled.

Returns

zeta

duration_initialize(options: Dict[str, Any]) → None

Initializes variables related to continue_simulating

Parameters

options – dictionary with options

hamiltonian_propagator(last_electronics: ElectronicT, this_electronics: ElectronicT, velo: Optional[Type[ndarray]] = None) → ndarray

Compute the Hamiltonian used to propagate the electronic wavefunction

Parameters

elec_states – ElectronicStates at current time step

Returns

nonadiabatic coupling H - i W at midpoint between current and previous time steps

hop_allowed(direction: Type[ndarray], dE: float)

Returns whether a hop with the given rescale direction and requested energy change is allowed

Parameters

  • direction – momentum unit vector

  • dE – change in energy such that Enew = Eold + dE

Returns

whether to hop

hop_to_it(hop_targets: List[Dict[str, Union[float, int]]], electronics: Optional[ElectronicT] = None) → None

Hop from the current active state to the given state, including rescaling the momentum

Parameters

  • hop_targets – list of (target, weight) pairs

  • electronics – ElectronicStates for current step

hop_update(hop_from, hop_to)

Handle any extra operations that need to occur after a hop

hopper(gkndt: Type[ndarray]) → List[Dict]

given a set of probabilities, determines whether and where to hop

Parameters

probs – [nstates] numpy array of individual hopping probabilities

Returns

dictioanry with { “target”: int, “weight”: float, “zeta”: float, “prob”: float }

kinetic_energy() → float64

Kinetic energy

Returns

kinetic energy

mode_kinetic_energy(direction: Type[ndarray]) → float64

Kinetic energy along given momentum mode

Parameters

direction – [ndim] numpy array defining direction

Returns

kinetic energy along specified direction

potential_energy(electronics: Optional[ElectronicT] = None) → Union[float64, complex128]

Potential energy

Parameters

electronics – ElectronicStates from current step

Returns

potential energy

propagate_electronics(last_electronics: ElectronicT, this_electronics: ElectronicT, dt: Union[float64, complex128]) → None

Propagates density matrix from t to t+dt

The propagation assumes the electronic energies and couplings are static throughout. This will only be true for fairly small time steps

Parameters

  • elec_states – ElectronicStates at t

  • dt – time step

random() → float64

Get random number for hopping decisions

Returns

uniform random number between 0 and 1

rescale_component(direction: Type[ndarray], reduction: Union[float64, complex128]) → None

Updates velocity by rescaling the momentum in the specified direction and amount

Parameters

  • direction – the direction of the momentum to rescale

  • reduction – how much kinetic energy should be damped

simulate() → Trace

Simulate

Returns

Trace of trajectory

snapshot() → Dict

returns loggable data

surface_hopping(last_electronics: ElectronicT, this_electronics: ElectronicT)

Compute probability of hopping, generate random number, and perform hops

Parameters

elec_states – ElectronicStates from current step

total_energy(electronics: Optional[ElectronicT] = None) → Union[float64, complex128]

Kinetic energy + Potential energy

Parameters

electronics – ElectronicStates from current step

Returns

total energy

trace(force: bool = False) → None

Add results from current time point to tracing function Only adds snapshot if nsteps%trace_every == 0, unless force=True

Parameters

force – force snapshot

update_weight(weight: float) → None

Update weight held by trajectory and by trace

class EvenSamplingTrajectory(*args: Any, **options: Any)

Bases: TrajectoryCum

Trajectory surface hopping using an even sampling approach

Related to the cumulative trajectory picture, but instead of hopping stochastically, new trajectories are spawned at even intervals of the of the cumulative probability distribution. This is an experimental in principle deterministic algorithm for FSSH simulations.

NAC_matrix(electronics: Optional[ElectronicT] = None, velocity: Optional[Type[ndarray]] = None) → Type[ndarray]

Nonadiabatic coupling matrix

Parameters

  • electronics – ElectronicStates from current step

  • velocity – velocity used to compute NAC (defaults to self.velocity)

Returns

[nstates, nstates] NAC matrix

advance_position(last_electronics: Optional[ElectronicT], this_electronics: ElectronicT) → None

Move classical position forward one step

Parameters

  • last_electronics – ElectronicStates from previous step

  • this_electronics – ElectronicStates from current step

advance_velocity(last_electronics: ElectronicT, this_electronics: ElectronicT) → None

Move classical velocity forward one step

Parameters

electronics – ElectronicStates from current step

clone(spawn_stack: Optional[Any] = None) → EvenSamplingTrajectory

Clone existing trajectory for spawning

Returns

copy of current object

continue_simulating() → bool

Decide whether trajectory should keep running

Returns

True if trajectory should keep running, False if it should finish

currently_interacting() → bool

Determines whether trajectory is currently inside an interaction region

Returns

boolean

direction_of_rescale(source: int, target: int, electronics: Optional[ElectronicT] = None) → ndarray

Return direction in which to rescale momentum

Parameters

  • source – active state before hop

  • target – active state after hop

  • electronics – electronic model information (used to pull derivative coupling)

Returns

unit vector pointing in direction of rescale

draw_new_zeta() → float

Returns a new zeta value for hopping. First it checks the input list of zeta values in self.zeta_list. If no value is found in zeta_list, then a random number is pulled.

Returns

zeta

duration_initialize(options: Dict[str, Any]) → None

Initializes variables related to continue_simulating

Parameters

options – dictionary with options

hamiltonian_propagator(last_electronics: ElectronicT, this_electronics: ElectronicT, velo: Optional[Type[ndarray]] = None) → ndarray

Compute the Hamiltonian used to propagate the electronic wavefunction

Parameters

elec_states – ElectronicStates at current time step

Returns

nonadiabatic coupling H - i W at midpoint between current and previous time steps

hop_allowed(direction: Type[ndarray], dE: float)

Returns whether a hop with the given rescale direction and requested energy change is allowed

Parameters

  • direction – momentum unit vector

  • dE – change in energy such that Enew = Eold + dE

Returns

whether to hop

hop_to_it(hop_to: List[Dict[str, Any]], electronics: Optional[ElectronicT] = None) → None

hop_to_it for even sampling spawns new trajectories instead of enacting hop

hop_to_it must accomplish:

  • copy current trajectory

  • initiate hops on the copied trajectories

  • make no changes to current trajectory

  • set next threshold for spawning

Parameters

  • hop_to – [nspawn] list of states and associated weights on which to hop

  • electronics – model class

hop_update(hop_from, hop_to)

Handle any extra operations that need to occur after a hop

hopper(probs: Type[ndarray]) → List[Dict[str, Union[float, int]]]

Given a set of probabilities, determines whether and where to hop :param probs: [nstates] numpy array of individual hopping probabilities :returns: [ (target_state, hop_weight) ]

kinetic_energy() → float64

Kinetic energy

Returns

kinetic energy

mode_kinetic_energy(direction: Type[ndarray]) → float64

Kinetic energy along given momentum mode

Parameters

direction – [ndim] numpy array defining direction

Returns

kinetic energy along specified direction

potential_energy(electronics: Optional[ElectronicT] = None) → Union[float64, complex128]

Potential energy

Parameters

electronics – ElectronicStates from current step

Returns

potential energy

propagate_electronics(last_electronics: ElectronicT, this_electronics: ElectronicT, dt: Union[float64, complex128]) → None

Propagates density matrix from t to t+dt

The propagation assumes the electronic energies and couplings are static throughout. This will only be true for fairly small time steps

Parameters

  • elec_states – ElectronicStates at t

  • dt – time step

random() → float64

Get random number for hopping decisions

Returns

uniform random number between 0 and 1

rescale_component(direction: Type[ndarray], reduction: Union[float64, complex128]) → None

Updates velocity by rescaling the momentum in the specified direction and amount

Parameters

  • direction – the direction of the momentum to rescale

  • reduction – how much kinetic energy should be damped

simulate() → Trace

Simulate

Returns

Trace of trajectory

snapshot() → Dict

returns loggable data

surface_hopping(last_electronics: ElectronicT, this_electronics: ElectronicT)

Compute probability of hopping, generate random number, and perform hops

Parameters

elec_states – ElectronicStates from current step

total_energy(electronics: Optional[ElectronicT] = None) → Union[float64, complex128]

Kinetic energy + Potential energy

Parameters

electronics – ElectronicStates from current step

Returns

total energy

trace(force: bool = False) → None

Add results from current time point to tracing function Only adds snapshot if nsteps%trace_every == 0, unless force=True

Parameters

force – force snapshot

update_weight(weight: float) → None

Update weight held by trajectory and by trace