Tasks#

Tasks are functions that carry out the elementary operations of an algorithm by modifying a state object and optionally a parameters object, which are both dictionaries. Built-in tasks can be found in the qclab.tasks module and are documented on this page.

A generic tasks has the form:

def my_task(sim, state, parameters, **kwargs):
    # Get any keyword arguments, with default values if not provided.
    kwarg1 = kwargs.get('kwarg1', default_value1)
    # Carry out the task by modifying state and parameters
    return state, parameters

where sim is an instance of the qclab.Simulation class (see Simulations), and **kwargs are any additional keyword arguments that customize the task to the context in which it is used. Generally, keyword arguments specify which attributes of the state and parameters objects are to be used and/or modified by the task (e.g., the name of the wavefunction or Hamiltonian attributes).

If a task has keyword arguments, they must be provided when the task is included in the algorithm’s recipe (see Algorithms) by using the partial function from the functools module, as in:

from functools import partial
# Specifying keyword arguments when including a task in a recipe.
algorithm.initialization_recipe = [partial(my_task, kwarg1=value1), ...]
# Including a task without keyword arguments.
algorithm.initialization_recipe = [another_task, ...]

Vectorization#

In QC Lab, attributes of the state and parameters objects are vectorized by default, meaning that they have an additional leading dimension that indexes multiple trajectories. For example, the diabatic wavefunction attribute wf_db of the state object has shape (sim.settings.batch_size, sim.model.constants.num_quantum_states), where sim.settings.batch_size is the number of trajectories in the batch and sim.model.constants.num_quantum_states is the number of quantum states in the model.

Initialization, Update, and Collect Tasks#

Tasks are organized into three categories: initialization tasks, update tasks, and collect tasks. Initialization tasks create objects in the state and parameters objects that are needed for the simulation, update tasks propagate the attributes of the state and parameters objects forward in time, and collect tasks gather and process the results of the simulation into the output dictionary.

Examples of these tasks are:

def my_initialization_task(sim, state, parameters, **kwargs):
    # Create an attribute in the state object with name "new_attribute_name".
    shape = (sim.settings.num_trajs, sim.model.constants.num_quantum_states)
    state["new_attribute_name"] = np.zeros(shape, dtype=complex)
    return state, parameters

def my_update_task(sim, state, parameters, **kwargs):
    # Update an attribute in the state object.
    state["new_attribute_name"] += 1j
    return state, parameters

def my_collect_task(sim, state, parameters, **kwargs):
    # Collect results into the output dictionary.
    state["output_dict"]['new_attribute_name'] = state["new_attribute_name"]
    return state, parameters

These tasks can then be included in the appropriate recipe of an algorithm object (see Algorithms). Notice that none of these tasks have keyword arguments and so can be included directly in recipes without using partial.

Built-in Tasks#

Built-in tasks can be found in the qclab.tasks module and are documented below.

Note

All tasks assume that the model object has a minimal set of constants including num_quantum_states (the number of quantum states) and num_classical_coordinates (the number of classical coordinates), classical_coordinate_mass (the mass of the classical coordinates), and classical_coordinate_weight (the weight of the classical coordinates). These constants are discussed in Models. For brevity we exclude explicit mention of these constants in the task documentation.

Initialization Tasks#

This module contains the tasks that initialize quantities in the state and parameters objects.

These are typically used in the initialization recipe of the algorithm object.

qclab.tasks.initialization_tasks.initialize_variable_objects(sim, state, parameters, **kwargs)#

Populates the state object with non-private variables in sim.initial_state, and an empty dictionary for storing output quantities.

For any non-private (i.e. not beginning with “_”) ndarray in sim.initial_state, a new array is created in state with shape (batch_size, *original_shape)` where original_shape is the shape of the array in sim.initial_state. The new array is initialized by copying the original array into each slice along the first axis.

Required Constants

None

Keyword Arguments

None

Modifications

state[name]ndarray: Initialized state variable with shape (batch_size, *original_shape). name is the name of the variable in sim.initial_state.
state[“output_dict”]dict: Dictionary to store output quantities during the simulation.

qclab.tasks.initialization_tasks.initialize_norm_factor(sim, state, parameters, **kwargs)#

Assigns the normalization factor to the state object.

Required Constants

None

Keyword Arguments

norm_factor_namestr, default: “norm_factor”: Name of the normalization factor in the state object.

Modifications

state[norm_factor_name]int: Normalization factor for trajectory averages.

qclab.tasks.initialization_tasks.initialize_branch_seeds(sim, state, parameters, **kwargs)#

Converts seeds into branch seeds for deterministic surface hopping.

This is done by first assuming that the number of branches is equal to the number of quantum states. Then, a branch index is created which gives the branch index of each seed in the batch. Then a new set of seeds is created by floor dividing the original seeds by the number of branches so that the seeds corresponding to different branches within the same trajectory are the same.

Notably, this leads to the number of unique classical initial conditions being equal to the number of trajectories divided by the number of branches in deterministic surface hopping.

Required Constants

None

Keyword Arguments

seed_namestr, default: “seed”: Name of the seeds array in state.
branch_ind_namestr, default: “branch_ind”: Name of the branch index array in state.

Modifications

state[branch_ind_name]ndarray: Branch index for each trajectory.
state[seed_name]ndarray: Seeds remapped for branches.

qclab.tasks.initialization_tasks.initialize_z_mcmc(sim, state, parameters, **kwargs)#

Initializes classical coordinates according to Boltzmann statistics using Markov- Chain Monte Carlo with a Metropolis-Hastings algorithm.

The algorithm has two modes, separable and non-separable. In the separable mode, each classical coordinate is evolved as an independent random walker. In the non-separable mode, the full classical coordinate vector is evolved as a single random walker. The separable mode converges much faster but assumes that the classical Hamiltonian can be written as a sum of independent terms depending on each classical coordinate.

Required Constants

mcmc_burn_in_sizeint, default: 1000: Burn-in step count.
mcmc_sample_sizeint, default: 10000: Number of retained samples.
mcmc_stdfloat, default: 1.0: Sampling standard deviation.
mcmc_h_c_separablebool, default: True: Whether the classical Hamiltonian is separable.
mcmc_init_zndarray, default: output of gen_sample_gaussian: Initial coordinate sample.
kBTfloat: Thermal quantum.

Keyword Arguments

seed_namestr: Attribute name of the seeds array in state.
z_namestr: Name of destination attribute in the state object.

Modifications

state[z_name]ndarray: Initialized classical coordinates.

qclab.tasks.initialization_tasks.initialize_z(sim, state, parameters, **kwargs)#

Initializes the classical coordinate by using the init_classical function from the model object.

Required Constants

None

Keyword Arguments

seed_namestr: Name of seed attribute in state object.
z_namestr: Name of classical coordinates in the state object.

Modifications

state[z_name]ndarray: initialized classical coordinates.

qclab.tasks.initialization_tasks.copy_in_state(sim, state, parameters, **kwargs)#

Creates a copy of a variable in the state object with a new name.

Required Constants

None

Keyword Arguments

copy_namestr: Name of the copy in the state object.
orig_namestr: Name of the source in the state object.

Modifications

state[copy_name]type of state[orig_name]: Copy of state[orig_name].

qclab.tasks.initialization_tasks.initialize_active_surface(sim, state, parameters, **kwargs)#

Initializes the active surface, active surface index, and initial active surface index for FSSH.

If fssh_deterministic=True it will set the initial active surface index to be the same as the branch index and assert that the number of branches is equal to the number of quantum states.

If fssh_deterministic=False it will stochastically sample the active surface from the density corresponding to the initial quantum wavefunction in the adiabatic basis.

Required Constants

None

Keyword Arguments

act_surf_ind_0_namestr, default: “act_surf_ind_0”: Name of the initial active surface index in the state object.
act_surf_ind_namestr, default: “act_surf_ind”: Name of the active surface index in the state object.
act_surf_namestr, default: “act_surf”: Name of the active surface in the state object.
init_act_surf_rand_vals_namestr, default: “init_act_surf_rand_vals”: Name of the random numbers for active surface initialization in FSSH.
wf_adb_namestr, default: “wf_adb”: Name of the adiabatic wavefunction in the state object.

Modifications

state[act_surf_ind_0_name]ndarray: Initial active surface index.
state[act_surf_ind_name]ndarray: Current active surface index.
state[act_surf_name]ndarray: Active surface wavefunctions.

qclab.tasks.initialization_tasks.initialize_random_values_fssh(sim, state, parameters, **kwargs)#

Initializes a set of random numbers using the trajectory seeds for FSSH.

Required Constants

None

Keyword Arguments

hop_prob_rand_vals_namestr, default: “hop_prob_rand_vals”: Name of the random numbers for hop decisions in the state object.
init_act_surf_rand_vals_namestr, default: “init_act_surf_rand_vals”: Name of the random numbers for active surface initialization in FSSH.
seed_namestr, default: “seed”: Name of the seeds array in the state object.

Modifications

state[hop_prob_rand_vals_name]ndarray: Random numbers for hop decisions.
state[init_act_surf_rand_vals_name]ndarray: Random numbers for active surface selection in stochastic FSSH.

qclab.tasks.initialization_tasks.initialize_dm_adb_0_fssh(sim, state, parameters, **kwargs)#

Initializes the initial adiabatic density matrix for FSSH.

Required Constants

None

Keyword Arguments

dm_adb_0_namestr, default: “dm_adb_0”: Name of the initial adiabatic density matrix in the state object.
wf_adb_namestr, default: “wf_adb”: Name of the adiabatic wavefunction in the state object.

Modifications

state[dm_adb_0_name]ndarray: Initial adiabatic density matrix.

Update Tasks#

This module contains tasks that update the state and parameters objects during propagation.

qclab.tasks.update_tasks.update_t(sim, state, parameters, **kwargs)#

Updates the time in the state object with the time index in each trajectory multiplied by the update timestep.

Model Constants

None

Keyword Arguments

t_namestr, default: “t”: Name of the time variable in the state object.

Input Variables

None

Output Variables

state[t_name]ndarray, (batch_size,), float: Time of each trajectory.

qclab.tasks.update_tasks.update_dh_c_dzc_finite_differences(sim, state, parameters, **kwargs)#

Updates the gradient of the classical Hamiltonian using finite differences.

Model Constants

dh_c_dzc_finite_difference_deltafloat, defaultnumerical_constants.FINITE_DIFFERENCE_DELTA: Finite-difference step size.

Keyword Arguments

z_namestr, default: “z”: Name of the classical coordinates in the state object.
dh_c_dzc_namestr, default: “dh_c_dzc”: Name under which to store the finite-difference gradient in the state object.

Input Variables

state[z_name]ndarray, (batch_size, num_classical_coordinates), complex: Classical coordinates.

Output Variables

state[dh_c_dzc_name]ndarray, (batch_size, num_classical_coordinates), complex: Gradient of the classical Hamiltonian.

qclab.tasks.update_tasks.update_classical_force(sim, state, parameters, **kwargs)#

Updates the gradient of the classical Hamiltonian w.r.t. the conjugate classical coordinate.

Required Constants

None

Keyword Arguments

z_namestr, default: “z”: Name of the classical coordinates in the state object.
classical_force_namestr, default: “classical_force”: Name under which to store the classical force in the state object.

Modifications

state[classical_force_name]ndarray: Gradient of the classical Hamiltonian.

qclab.tasks.update_tasks.update_dh_qc_dzc_finite_differences(sim, state, parameters, **kwargs)#

Updates the gradient of the quantum-classical Hamiltonian using finite differences.

Required Constants

dh_qc_dzc_finite_difference_deltafloat, defaultnumerical_constants.FINITE_DIFFERENCE_DELTA: Finite-difference step size.

Keyword Arguments

z_namestr, default: “z”: Name of classical coordinates in the state object.
dh_qc_dzc_namestr, default: “dh_qc_dzc”: Name under which to store the gradient of the quantum-classical Hamiltonian in the state object.

Modifications

state[dh_qc_dzc_name]tuple: Gradient of the quantum-classical Hamiltonian.

qclab.tasks.update_tasks.update_dh_qc_dzc(sim, state, parameters, **kwargs)#

Updates the gradient of the quantum-classical Hamiltonian w.r.t. the conjugate classical coordinate.

Required Constants

None

Keyword Arguments

z_namestr, default: “z”: Name of classical coordinates in state object.
dh_qc_dzc_namestr, default: “dh_qc_dzc”: Name under which to store the gradient of the quantum-classical Hamiltonian in the state object.

Modifications

state[dh_qc_dzc_name]tuple: Gradient of the quantum-classical Hamiltonian.

qclab.tasks.update_tasks.update_quantum_classical_force(sim, state, parameters, **kwargs)#

Updates the quantum-classical force w.r.t. the wavefunction defined by wf_db.

If the model has a gauge_field_force ingredient, this term will be added to the quantum-classical force.

Required Constants

None

Keyword Arguments

z_namestr, default: “z”: Name of classical coordinates in state object.
wf_db_namestr, default: “wf_db”: Name of the wavefunction (in the diabatic basis) in the state object.
dh_qc_dzc_namestr, default: “dh_qc_dzc”: Name of the gradient of the quantum-classical Hamiltonian in the state object.
quantum_classical_force_namestr, default: “quantum_classical_force”: Name under which to store the quantum-classical force in the state object.
state_ind_namestr, default: “act_surf_ind”: Name in the state object of the state index for which to obtain the gauge field force. Required if algorithm.settings.use_gauge_field_force is True.
wf_changedbool, default: True: If True, the wavefunction has changed since the last time the force were calculated.

Modifications

state[dh_qc_dzc_name]tuple: Gradient of the quantum-classical Hamiltonian.
state[quantum_classical_force_name]ndarray: Quantum-classical force.

qclab.tasks.update_tasks.add_gauge_field_force(sim, state, parameters, **kwargs)#

Adds the quantum-classical force with the gauge field force if the model has a gauge_field_force ingredient.

Required Constants

None

Keyword Arguments

z_namestr, default: “z”: Name of classical coordinates in state object.
adb_state_ind_namestr, default: “act_surf_ind”: Name of the adiabatic state index for which to obtain the gauge field force.
quantum_classical_force_namestr, default: “quantum_classical_force”: Name of the quantum-classical force in the state object.

Modifications

state[quantum_classical_force_name]ndarray: Quantum-classical force with gauge field force added.

qclab.tasks.update_tasks.diagonalize_matrix(sim, state, parameters, **kwargs)#

Diagonalizes a given matrix from the state object and stores the eigenvalues and eigenvectors in the state object.

Required Constants

None

Keyword Arguments

matrix_namestr: Name of the matrix to diagonalize in the state object.
eigvals_namestr: Name of the eigenvalues in the state object.
eigvecs_namestr: Name of the eigenvectors in the state object.

Modifications

state[eigvals_name]ndarray: Eigenvalues of the matrix.
state[eigvecs_name]ndarray: Eigenvectors of the matrix.

qclab.tasks.update_tasks.update_eigvecs_gauge(sim, state, parameters, **kwargs)#

Updates the gauge of the eigenvectors as specified by the gauge_fixing parameter.

if gauge_fixing == “sign_overlap”:: The sign of the eigenvector is changed so the real part of its overlap with the previous eigenvector is positive.
if gauge_fixing == “phase_overlap”:: The phase of the eigenvector is determined from its overlap with the previous eigenvector and used to maximize the real part of the overlap. The sign is then changed so the real part of the overlap is positive.
if gauge_fixing == “phase_der_couple”:: The phase of the eigenvector is determined by calculating the derivative couplings and changed so that all the derivative couplings are real-valued.

Required Constants

None

Keyword Arguments

eigvals_namestr, default: “eigvals”: Name of the eigenvalues in the state object.
eigvecs_namestr, default: “eigvecs”: Name of the eigenvectors in the state object.
eigvecs_previous_namestr, default: “eigvecs_previous”: Name of the previous eigenvectors in the state object.
output_eigvecs_namestr, default: eigvecs_name: Name of the output gauge-fixed eigenvectors in the state object.
z_namestr, default: “z”: Name of classical coordinates in the state object.
gauge_fixingstr, default: sim.algorithm.settings.gauge_fixing: Gauge-fixing method to use.
dh_qc_dzc_namestr, default: “dh_qc_dzc”: Name of the gradient of the quantum-classical Hamiltonian in the state object.

Modifications

state[output_eigvecs_name]ndarray: Gauge-fixed eigenvectors.

qclab.tasks.update_tasks.update_vector_basis(sim, state, parameters, **kwargs)#

Transforms a vector to a new basis.

Required Constants

None

Keyword Arguments

input_vec_namestr: Name of the vector to transform in the state object.
basis_namestr: Name of the basis to transform to in the state object. Assumed to be column vectors corresponding to adiabatic states.
output_vec_namestr: Name of the output vector in the state object.
adb_to_dbbool, default: False: If True, transforms from adiabatic to diabatic. If False, transforms from adiabatic to diabatic.

Modifications

state[output_vec_name]ndarray: Vector expressed in the new basis.

qclab.tasks.update_tasks.update_act_surf_wf(sim, state, parameters, **kwargs)#

Updates the wavefunction corresponding to the active surface.

Required Constants

None

Keyword Arguments

act_surf_wf_namestr, default: “act_surf_wf”: Name of the active surface wavefunction in the state object.
act_surf_ind_namestr, default: “act_surf_ind”: Name of the active surface index in the state object.
eigvecs_namestr, default: “eigvecs”: Name of the eigenvectors in the state object.

Modifications

state[act_surf_wf_name]ndarray: Wavefunction of the active surface.

qclab.tasks.update_tasks.update_wf_db_propagator(sim, state, parameters, **kwargs)#

Updates the diabatic wavefunction by calculating and applying the propagator.

Required Constants

None

Keyword Arguments

wf_db_namestr, default: “wf_db”: Name of the diabatic wavefunction in the state object.
eigvals_namestr, default: “eigvals”: Name of the eigenvalues in the state object.
eigvecs_namestr, default: “eigvecs”: Name of the eigenvectors in the state object.

Modifications

state[wf_db_name]ndarray: Updated diabatic wavefunction.

qclab.tasks.update_tasks.update_wf_db_rk4(sim, state, parameters, **kwargs)#

Updates the wavefunction using the 4th-order Runge-Kutta method.

Required Constants

None

Keyword Arguments

wf_db_namestr, default: “wf_db”: Name of the diabatic wavefunction in the state object.
h_q_tot_namestr, default: “h_q_tot”: Name of the quantum Hamiltonian in the state object.

Modifications

state[wf_db_name]ndarray: Updated diabatic wavefunction.

qclab.tasks.update_tasks.update_hop_prob_fssh(sim, state, parameters, **kwargs)#

Calculates the hopping probabilities according to the FSSH algorithm.

\(P_{a \rightarrow b} = -2 \Re \left( (C_{b}/C_{a}) \langle a(t) | b(t-dt) \rangle \right)\)

Required Constants

None

Keyword Arguments

act_surf_ind_namestr, default: “act_surf_ind”: Name of the active surface index in the state object.
wf_adb_namestr, default: “wf_adb”: Name of the adiabatic wavefunction in the state object.
eigvecs_namestr, default: “eigvecs”: Name of the eigenvectors in the state object.
eigvecs_previous_namestr, default: “eigvecs_previous”: Name of the previous eigenvectors in the state object.
hop_prob_namestr, default: “hop_prob”: Name under which to store the hopping probabilities in the state object.

Modifications

state[hop_prob_name]ndarray: Hopping probabilities between the active surface and all other surfaces.

qclab.tasks.update_tasks.update_hop_inds_fssh(sim, state, parameters, **kwargs)#

Updates indices of trajectories that hop according to their probabilities (but may later be frustrated) and their destination state indices.

Required Constants

hop_prob_namestr, default: “hop_prob”: Name of the hopping probabilities in the state object.
hop_prob_rand_vals_namestr, default: “hop_prob_rand_vals”: Name of the random values for hopping probabilities in the state object.
hop_ind_namestr, default: “hop_ind”: Name under which to store the indices of the hopping trajectories in the state object.
hop_dest_namestr, default: “hop_dest”: Name under which to store the destination indices of the hopping trajectories in the state object.

Keyword Arguments

None

Modifications

state[hop_ind_name]ndarray: Indices of trajectories that hop.
state[hop_dest_name]ndarray: Destination surface for each hop.

qclab.tasks.update_tasks.update_z_shift_fssh(sim, state, parameters, **kwargs)#

Determines if a hop occurs and calculates the shift in the classical coordinate at the single trajectory level.

Required Constants

None

Keyword Arguments

z_traj_namestr, default: “z_traj”: Name of the classical coordinates for this trajectory in the state object.
resc_dir_z_traj_namestr, default: “resc_dir_z_traj”: Name of the rescaling direction for this trajectory in the state object.
eigval_diff_traj_namestr, default: “eigval_diff_traj”: Name of the difference in eigenvalues between the initial and final states (e_final - e_initial) for this trajectory in the state object.
hop_successful_traj_namestr, default: “hop_successful_traj”: Name under which to store whether the hop was successful for this trajectory in the state object.
z_shift_traj_namestr, default: “z_shift_traj”: Name under which to store the shift in classical coordinates for this trajectory in the state object.

Modifications

state[hop_successful_traj_name]bool: Flag indicating if the hop was successful.
state[z_shift_traj_name]ndarray: Shift required to conserve energy.

qclab.tasks.update_tasks.update_hop_vals_fssh(sim, state, parameters, **kwargs)#

Updates trajectory hopping information for FSSH.

Executes the hopping function for the hopping trajectories and stores the rescaled coordinates in state.z_rescaled and a Boolean registering if the hop was successful in state.hop_successful.

If the model has a rescaling_direction_fssh ingredient, it will be used to determine the direction in which to rescale the coordinates. Otherwise, the direction will be calculated with functions.calc_resc_dir_z_fssh.

Required Constants

None

Keyword Arguments

z_shift_namestr, default: “z_shift”: Name under which to store the shift in coordinates for each hopping trajectory in the state object.
hop_successful_namestr, default: “hop_successful”: Name under which to store flags indicating if each hop was successful in the state object.
hop_ind_name: str, default: “hop_ind”: Name of the indices of the trajectories that are attempting to hop in the state object.
hop_dest_name: str, default: “hop_dest”: Name of the destination states of the trajectories that are attempting to hop in the state object.
eigvals_namestr, default: “eigvals”: Name of the eigenvalues in the state object.
eigvecs_namestr, default: “eigvecs”: Name of the eigenvectors in the state object.
z_namestr, default: “z”: Name of classical coordinates in the state object.
act_surf_ind_namestr, default: “act_surf_ind”: Name of the active surface index in the state object.
dh_qc_dzc_namestr, default: “dh_qc_dzc”: Name of the gradient of the quantum-classical Hamiltonian in the state object.
z_traj_namestr, default: “z_traj”: Name of the classical coordinates for the intermediate hopping trajectory in the state object.
resc_dir_z_traj_namestr, default: “resc_dir_z_traj”: Name of the rescaling direction for the intermediate hopping trajectory in the state object.
eigval_diff_traj_namestr, default: “eigval_diff_traj”: Name of the difference in eigenvalues between the initial and final states (e_final - e_initial) for the intermediate hopping trajectory in the state object.
hop_successful_traj_namestr, default: “hop_successful_traj”: Name under which to store whether the hop was successful for the intermediate hopping trajectory in the state object.
z_shift_traj_namestr, default: “z_shift_traj”: Name under which to store the shift in classical coordinates for the intermediate hopping trajectory in the state object.

Modifications

state[z_shift_name]ndarray: Shift in coordinates for each hopping trajectory.
state[hop_successful_name]ndarray: Flags indicating if each hop was successful.

qclab.tasks.update_tasks.update_z_hop(sim, state, parameters, **kwargs)#

Updates the classical coordinates in trajectories that have hopped.

Required Constants

None

Keyword Arguments

z_shift_namestr, default: “z_shift”: Name of the shift in coordinates for each hopping trajectory in the state object.
hop_ind_namestr, default: “hop_ind”: Name of the indices of the trajectories that are attempting to hop in the state object.
z_namestr, default: “z”: Name of classical coordinates in the state object.

Modifications

state[z_name]ndarray: Classical coordinates.

qclab.tasks.update_tasks.update_act_surf_hop(sim, state, parameters, **kwargs)#

Updates the active surface, active surface index, and active surface wavefunction following a hop.

Required Constants

None

Keyword Arguments

hop_ind_namestr, default: “hop_ind”: Name of the indices of the trajectories that are attempting to hop in the state object.
hop_dest_namestr, default: “hop_dest”: Name of the destination states of the trajectories that are attempting to hop in the state object.
hop_successful_namestr, default: “hop_successful”: Name of the flags indicating if each hop was successful in the state object.
act_surf_namestr, default: “act_surf”: Name of the active surface wavefunction in the state object.
act_surf_ind_namestr, default: “act_surf_ind”: Name of the active surface index in the state object.

Modifications

state[act_surf_ind_name]ndarray: Active surface indices.
state[act_surf_name]ndarray: Active surface wavefunctions.

qclab.tasks.update_tasks.update_h_q_tot(sim, state, parameters, **kwargs)#

Updates the Hamiltonian matrix of the quantum subsystem.

Required Constants

None

Keyword Arguments

z_namestr, default: “z”: Name of classical coordinates in state object.
h_q_namestr, default: “h_q”: Name of the quantum Hamiltonian in the state object.
h_qc_namestr, default: “h_qc”: Name of the quantum-classical coupling Hamiltonian in the state object.
h_q_tot_namestr, default: “h_q_tot”: Name of the total Hamiltonian of the quantum subsystem in the state object. (h_q + h_qc)

Modifications

state[h_q_name]ndarray: Quantum Hamiltonian matrix.
state[h_qc_name]ndarray: Quantum-classical coupling matrix.
state[h_q_tot_name]ndarray: Total Hamiltonian of the quantum subsystem.

qclab.tasks.update_tasks.update_z_rk4_k123(sim, state, parameters, **kwargs)#

Computes the first three RK4 intermediates for evolving the classical coordinates.

Required Constants

None

Keyword Arguments

z_namestr, default: “z”: Name of input coordinates in state object.
z_k_namestr, default: “z_1”: Name of the output coordinates in the state object.
k_namestr, default: “z_rk4_k1”: Name of the first RK4 slope in the state object.
classical_force_namestr, default: “classical_force”: Name of the classical force in the state object.
quantum_classical_force_namestr, default: “quantum_classical_force”: Name of the quantum-classical force in the state object.
dt_factorfloat, default: 0.5: Factor to multiply the time step by. Typical values are 0.5 (for k1 and k2) and 1.0 (for k3).

Modifications

state[z_k_name]ndarray: Output coordinates after half step.
state[k_name]ndarray: First RK4 slope.

qclab.tasks.update_tasks.update_z_rk4_k4(sim, state, parameters, **kwargs)#

Computes the final RK4 update for evolving the classical coordinates.

Required Constants

None

Keyword Arguments

z_namestr, default: “z”: Name of input coordinates in state object.
k1_namestr, default: “z_rk4_k1”: Name of the first RK4 slope in the state object.
k2_namestr, default: “z_rk4_k2”: Name of the second RK4 slope in the state object.
k3_namestr, default: “z_rk4_k3”: Name of the third RK4 slope in the state object.
classical_force_namestr, default: “classical_force”: Name of the classical force in the state object.
quantum_classical_force_namestr, default: “quantum_classical_force”: Name of the quantum-classical force in the state object.

Modifications

state[z_name]ndarray: Updated classical coordinates.

qclab.tasks.update_tasks.update_dm_db_wf(sim, state, parameters, **kwargs)#

Updates the diabatic density matrix based on the wavefunction.

Required Constants

None

Keyword Arguments

wf_db_namestr, default: “wf_db”: Name of the diabatic wavefunction in the state object.
dm_db_namestr, default: “dm_db”: Name of the diabatic density matrix in the state object.

Modifications

state[dm_db_name]ndarray: Diabatic density matrix.

qclab.tasks.update_tasks.update_classical_energy(sim, state, parameters, **kwargs)#

Updates the classical energy.

Required Constants

None

Keyword Arguments

z_name : str, default: “z” classical_energy_name : str, default: “classical_energy”

Name under which to store the classical energy in the state object.

Modifications

state[classical_energy_name]ndarray: Energy of the classical subsystem.

qclab.tasks.update_tasks.update_classical_energy_fssh(sim, state, parameters, **kwargs)#

Updates the classical energy for FSSH simulations.

If deterministic, the energy in each branch is summed together with weights determined by the initial adiabatic populations. If not deterministic (and so there is only one branch), the energy is computed for the single branch.

Required Constants

None

Keyword Arguments

z_name str, default: “z”: Name of classical coordinates in state object.
classical_energy_namestr, default: “classical_energy”: Name under which to store the classical energy in the state object.
dm_adb_0_namestr, default: “dm_adb_0”: Name of the initial adiabatic density matrix in the state object.
branch_ind_namestr, default: “branch_ind”: Name of the branch indices in the state object.

Modifications

state[classical_energy_name]ndarray: Energy of the classical subsystem.

qclab.tasks.update_tasks.update_quantum_energy_wf(sim, state, parameters, **kwargs)#

Updates the quantum energy w.r.t. the wavefunction.

Required Constants

None

Keyword Arguments

wf_db_namestr, default: “wf_db”: Name of the wavefunction in the state object.
h_q_tot_namestr, default: “h_q_tot”: Name of the total Hamiltonian of the quantum subsystem in the state object. (h_q + h_qc)
quantum_energy_namestr, default: “quantum_energy”: Name under which to store the quantum energy in the state object.

Modifications

state[quantum_energy_name]ndarray: Quantum energy.

qclab.tasks.update_tasks.update_quantum_energy_act_surf(sim, state, parameters, **kwargs)#

Updates the quantum energy using the active surface wavefunction.

Accounts for both stochastic and deterministic FSSH modes.

Required Constants

None

Keyword Arguments

wf_db_namestr, default: act_surf_wf: Name of the wavefunction in the state object.
h_q_tot_namestr, default: “h_q_tot”: Name of the total Hamiltonian of the quantum subsystem in the state object. (h_q + h_qc)
quantum_energy_namestr, default: “quantum_energy”: Name under which to store the quantum energy in the state object.
dm_adb_0_namestr, default: “dm_adb_0”: Name of the initial adiabatic density matrix in the state object.

Modifications

state[quantum_energy_name]ndarray: Quantum energy.

qclab.tasks.update_tasks.update_dm_db_fssh(sim, state, parameters, **kwargs)#

Updates the diabatic density matrix for FSSH.

Accounts for both stochastic and deterministic FSSH modes.

Required Constants

None

Keyword Arguments

wf_adb_namestr, default: “wf_adb”: Name of the adiabatic wavefunction in the state object.
dm_adb_0_namestr, default: “dm_adb_0”: Name of the initial adiabatic density matrix in the state object.
act_surf_namestr, default: “act_surf”: Name of the active surface wavefunction in the state object.
dm_db_namestr, default: “dm_db”: Name of the diabatic density matrix in the state object.
dm_adb_namestr, default: “dm_adb”: Name of the adiabatic density matrix in the state object.
eigvecs_namestr, default: “eigvecs”: Name of the eigenvectors in the state object.

Modifications

state[dm_db_name]ndarray: Diabatic density matrix.
state[dm_adb_name]ndarray: Adiabatic density matrix.

Collect Tasks#

This module contains tasks that are used to collect data from the state or parameters objects into the output dictionary of the state object.

qclab.tasks.collect_tasks.collect_t(sim, state, parameters, **kwargs)#

Collects the time from the state object and stores it in the output dictionary.

Required Constants

None

Keyword Arguments

t_namestr, default“t”: Name of the time in the state object.
t_output_namestr, default“t”: Name of the time in the output dictionary.

Modifications

state[“output_dict”][t_output_name]ndarray: stores the current time in each trajectory.

qclab.tasks.collect_tasks.collect_dm_db(sim, state, parameters, **kwargs)#

Collects the diabatic density matrix from the state object and stores it in the output dictionary.

Required Constants

None

Keyword Arguments

dm_db_namestr, default“dm_db”: Name of the diabatic density matrix in the state object.
dm_db_output_namestr, default“dm_db”: Name of the diabatic density matrix in the output dictionary.

Modifications

state[“output_dict”][dm_db_output_name]ndarray: Stores the diabatic density matrix.

qclab.tasks.collect_tasks.collect_classical_energy(sim, state, parameters, **kwargs)#

Collects the classical energy from the state object and stores it in the output dictionary.

Required Constants

None

Keyword Arguments

classical_energy_namestr, default“classical_energy”: Name of the classical energy in the state object.
classical_energy_output_namestr, default“classical_energy”: Name of the classical energy in the output dictionary.

Modifications

state[“output_dict”][classical_energy_output_name]ndarray: stores the classical energy.

qclab.tasks.collect_tasks.collect_quantum_energy(sim, state, parameters, **kwargs)#

Collects the quantum energy from the state object and stores it in the output dictionary.

Required Constants

None

Keyword Arguments

quantum_energy_namestr, default“quantum_energy”: Name of the quantum energy in the state object.
quantum_energy_output_namestr, default“quantum_energy”: Name of the quantum energy in the output dictionary.

Modifications

state[“output_dict”][quantum_energy_output_name]ndarray: Stores the quantum energy.