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