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 instances of the qclab.Variable class (see Variable Objects). 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.
    shape = (sim.settings.num_trajs, sim.model.constants.num_quantum_states)
    state.new_attribute = 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 += 1j
    return state, parameters

def my_collect_task(sim, state, parameters, **kwargs):
    # Collect results into the output dictionary.
    state.output_dict['new_attribute'] = state.new_attribute
    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 parameter and state objects with variables in the sim.initial_state object. For any numpy 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.

Any variable with name starting with an underscore is ignored.

Model Constants

None

Keyword Arguments

None

Variable Modifications

state.{initial_state.attribute.__name__}ndarray

Initialized state variable with shape (batch_size, *original_shape).

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

Assigns the normalization factor to the state object.

Model Constants

None

Keyword Arguments

norm_factor_namestr, default: “norm_factor”

Name of the normalization factor in the state object.

Variable 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.

Model 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.

Variable 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.

Model 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.

Variable 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.

Model Constants

None

Keyword Arguments

seed_namestr

Name of seed attribute in state object.

z_namestr

Name of classical coordinates in the state object.

Variable Modifications

state.{z_name}ndarray

initialized classical coordinates.

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

Creates a copy of a quantity in the state object.

Model Constants

None

Keyword Arguments

copy_namestr

Name of the copy in the state object.

orig_namestr

Name of the source in the state object.

Variable 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.

Model 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.

stochastic_sh_rand_vals_namestr, default: “stochastic_sh_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.

Variable 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.

Model Constants

None

Keyword Arguments

hopping_probs_rand_vals_namestr, default: “hopping_probs_rand_vals”

Name of the random numbers for hop decisions in the state object.

stochastic_sh_rand_vals_namestr, default: “stochastic_sh_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.

Variable Modifications

state.{hopping_probs_rand_vals_name}ndarray

Random numbers for hop decisions.

state.{stochastic_sh_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.

Model 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.

Variable 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: Simulation, state: dict, parameters: dict, t_name: str = 't')#

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

Args: sim : Simulation

Simulation object; must provide settings.batch_size, settings.dt_update, and t_ind.

statedict

State object to update; will be modified in-place.

parametersdict

Parameters object; not modified by this function.

t_namestr, optional

Key for the time variable in state. Default is "t".

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.

Parameters:
  • sim (Simulation)

  • state (dict)

  • parameters (dict)

  • t_name (str)

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

Calculates the gradient of the classical Hamiltonian using finite differences.

Model Constants#

dh_c_dzc_finite_difference_deltafloat

Finite-difference step size.

keyword z_name:

Name of the classical coordinates in the state object.

kwtype z_name:

str

keyword dh_c_dzc_name:

Name under which to store the finite-difference gradient in the state object.

kwtype dh_c_dzc_name:

str, default: “dh_c_dzc”

keyword Input Variables:

keyword —————:

keyword state[z_name]:

Classical coordinates.

kwtype state[z_name]:

ndarray

keyword Output Variables:

keyword —————-:

keyword state[dh_c_dzc_name]:

Gradient of the classical Hamiltonian.

kwtype state[dh_c_dzc_name]:

ndarray

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

One-line summary in the imperative mood.

Extended summary (optional): what the task computes and why it exists.

Parameters:
  • sim (Simulation) – Simulation object. Must provide settings, model, and algorithm.

  • state (MutableMapping[str, Any]) – Mutable container of arrays and scalars. This function mutates it in place.

  • parameters (MutableMapping[str, Any]) – Mutable container of tunables/coefficients. Mutated only if stated below.

  • **kwargs – Task-specific keyword arguments (see below).

  • <kw1> (<type>, optional) – What it controls. Default "...".

  • <kw2> (<type>, optional) – What it controls. Default "...".

Requires:

model[“ingredient_name”] – Short description of the required model ingredient or the fallback behavior.

Reads:
  • state[<key>] ((<shape>), <dtype>) – What is read and how it is used.

  • parameters[<key>] ((<shape>), <dtype>) – (List more as needed.)

Writes:
  • state[<key>] ((<shape>), <dtype>) – Whether created if missing or updated in place.

  • parameters[<key>] ((<shape>), <dtype>) – (Only list if actually mutated.)

Shapes and dtypes:
  • Let ``B = batch_size``, ``C = num_classical_coordinates``.

  • - ``state[<key_in>]`` ((B, C), complex (e.g., complex128))

  • - ``state[<key_out>]`` ((B, C), complex)

Returns:

(state, parameters) – Same objects passed in. state is mutated in place as documented above.

Return type:

tuple

Notes

Brief algorithmic note, fallbacks, and logging behavior.

See also

related_task, supporting_function

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

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

Model Constants

None

Keyword Arguments

z_namestr, default: “z”

Name of the classical coordinates in the state object.

classical_forces_namestr, default: “classical_forces”

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

Input Variables

state[z_name]ndarray, (batch_size, num_classical_coordinates), complex

Classical coordinates.

Output Variables

state.{classical_forces_name}ndarray, (batch_size, num_classical_coordinates), complex

Gradient of the classical Hamiltonian.

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

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

Model 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.

Variable 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.

Model 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.

Variable Modifications

state.{dh_qc_dzc_name}tuple

Gradient of the quantum-classical Hamiltonian.

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

Updates the quantum-classical forces 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 forces.

Model 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_forces_namestr, default: “quantum_classical_forces”

Name under which to store the quantum-classical forces 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 forces were calculated.

Variable Modifications

state.{dh_qc_dzc_name}tuple

Gradient of the quantum-classical Hamiltonian.

state.{quantum_classical_forces_name}ndarray

Quantum-classical forces.

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

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

Model 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_forces_namestr, default: “quantum_classical_forces”

Name of the quantum-classical forces in the state object.

Variable Modifications

state.{quantum_classical_forces_name}ndarray

Quantum-classical forces 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.

Model 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.

Variable Modifications

state.{eigvals}ndarray

Eigenvalues of the matrix.

state.{eigvecs}ndarray

Eigenvectors of the matrix.

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

Fixes 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.

Model 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.

Variable Modifications

state.{output_eigvecs_name}ndarray

Gauge-fixed eigenvectors.

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

Transforms a vector state.{input} to a new basis defined by state.{basis} and stores it in state.{output}.

Model 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.

Variable 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.

Model 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.

Variable Modifications

state.{act_surf_wf_name}ndarray

Wavefunction of the active surface.

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

Evolves the diabatic wavefunction state.{wf_db_name} using the eigenvalues state.{eigvals_name} and eigenvectors state.{eigvecs_name}.

Model 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.

Variable Modifications

state.{wf_db_name}ndarray

Updated diabatic wavefunction.

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

Updates the wavefunction state.{wf_db_name} using the 4th-order Runge-Kutta method with the hamiltonian state.{h_quantum_name}.

Model Constants

None

Keyword Arguments

wf_db_namestr, default: “wf_db”

Name of the diabatic wavefunction in the state object.

h_quantum_namestr, default: “h_quantum”

Name of the quantum Hamiltonian in the state object.

Variable Modifications

state.{wf_db_name}ndarray

Updated diabatic wavefunction.

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

Calculates the hopping probabilities for FSSH.

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

Model 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.

Variable 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)#

Determines which trajectories hop based on the hopping probabilities and which state they hop to. Note that these will only hop if they are not frustrated by the hopping function.

Stores the indices of the hopping trajectories in state.hop_ind. Stores the destination indices of the hops in state.hop_dest.

Model Constants

hop_prob_namestr, default: “hop_prob”

Name of the hopping probabilities in the state object.

hopping_probs_rand_vals_namestr, default: “hopping_probs_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

Variable 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.

Model Constants

None

Keyword Arguments

z_traj_namestr, default: “z_traj”

Name of the classical coordinates for this trajectory in the state object.

delta_z_traj_namestr, default: “delta_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.

Variable 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)#

Executes the hopping function for the hopping trajectories.

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_delta_z_fssh.

Model 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.

delta_z_traj_namestr, default: “delta_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.

Variable 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_fssh(sim, state, parameters, **kwargs)#

Applies the shift in coordinates after successful hops.

Model 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.

Variable Modifications

state.{z_name}ndarray

Classical coordinates.

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

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

Model 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.

Variable Modifications

state.{act_surf_ind_name}ndarray

Active surface indices.

state.{act_surf_name}ndarray

Active surface wavefunctions.

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

Updates the Hamiltonian matrix of the quantum subsystem.

Model 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_quantum_namestr, default: “h_quantum”

Name of the total Hamiltonian of the quantum subsystem in the state object. (h_q + h_qc)

Variable Modifications

state.{h_q_name}ndarray

Quantum Hamiltonian matrix.

state.{h_qc_name}ndarray

Quantum-classical coupling matrix.

state.{h_quantum_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.

Model Constants

None

Keyword Arguments

z_namestr, default: “z”

Name of input coordinates in state object.

z_output_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_forces_namestr, default: “classical_forces”

Name of the classical forces in the state object.

quantum_classical_forces_namestr, default: “quantum_classical_forces”

Name of the quantum-classical forces 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).

Variable Modifications

state.{z_output_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.

Model Constants

None

Keyword Arguments

z_namestr, default: “z”

Name of input coordinates in state object.

z_output_namestr, default: z_name

Name of the output coordinates in the 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_forces_namestr, default: “classical_forces”

Name of the classical forces in the state object.

quantum_classical_forces_namestr, default: “quantum_classical_forces”

Name of the quantum-classical forces in the state object.

Variable Modifications

state.{z_output_name}ndarray

Output coordinates after a full step.

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

Updates the diabatic density matrix based on the wavefunction.

Model 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.

Variable Modifications

state.{dm_db_name}ndarray

Diabatic density matrix.

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

Updates the classical energy.

Model 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.

Variable 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.

Model 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.

Variable Modifications

state.{classical_energy_name}ndarray

Energy of the classical subsystem.

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

Updates the quantum energy w.r.t. the wavefunction specified by state.{wf_db_name} by taking the expectation value of state.{h_quantum_name}.

Model Constants

None

Keyword Arguments

wf_db_namestr, default: “wf_db”

Name of the wavefunction in the state object.

h_quantum_namestr, default: “h_quantum”

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.

Variable Modifications

state.{quantum_energy_name}ndarray

Quantum energy.

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

Updates the quantum energy w.r.t. the wavefunction specified by state.{wf_db_name} by taking the expectation value of state.{h_quantum_name}. Accounts for both stochastic and deterministic FSSH modes. Typically, the wavefunction used is that of the active surface.

Model Constants

None

Keyword Arguments

wf_db_namestr, default: act_surf_wf

Name of the wavefunction in the state object.

h_quantum_namestr, default: “h_quantum”

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.

Variable 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.

Model 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.

Variable 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: Simulation, state: dict, parameters: dict, t_var_name: str = 't', t_output_name: str = 't')#

Collects the time into the output dictionary of the state object.

Parameters:
  • sim (Simulation) – The simulation object.

  • state (dict) – The state object.

  • parameters (dict) – The parameters object.

  • t_var_name (str) – Name of the time variable in the state object.

  • t_output_name (str) – Name of the output variable for the time.

Reads:

state[t_var_name] (ndarray, (B), float64) – The time in each trajectory.

Writes:

state[“output_dict”][t_output_name] (ndarray, (B), float64) – stores the current time in each trajectory.

Shapes and dtypes:

B = sim.settings.batch_size

Requires:

None

Returns:

(state, parameters) – The updated state and parameters objects.

Return type:

tuple(dict, dict)

qclab.tasks.collect_tasks.collect_dm_db(sim: Simulation, state: dict, parameters: dict, dm_db_var_name: str = 'dm_db', dm_db_output_name: str = 'dm_db')#

Collects the diabatic density matrix into the output dictionary of the state object.

Parameters:
  • sim (Simulation) – The simulation object.

  • state (dict) – The state object.

  • parameters (dict) – The parameters object.

  • dm_db_var_name (str) – Name of the diabatic density matrix in the state object.

  • dm_db_output_name (str) – Name of the diabatic density matrix in the output dictionary.

Reads:

state[dm_db_var_name] (ndarray, (B, N, N), complex128) – The diabatic density matrix in each trajectory.

Writes:

state[“output_dict”][dm_db_output_name] (ndarray, (B, N, N), complex128) – The diabatic density matrix in each trajectory.

Shapes and dtypes:
  • B = sim.settings.batch_size

  • N = sim.model.constants.num_quantum_states

Requires:
  • sim.model.constants.num_quantum_states (int) – Number of quantum states.

  • sim.settings.batch_size (int) – Number of trajectories in the batch.

Returns:

(state, parameters) – The updated state and parameters objects.

Return type:

tuple(dict, dict)

See also

qclab.tasks.update_tasks.update_dm_db, qclab.tasks.update_tasks.update_dm_db_fssh

qclab.tasks.collect_tasks.collect_classical_energy(sim: Simulation, state: dict, parameters: dict, classical_energy_var_name: str = 'classical_energy', classical_energy_output_name: str = 'classical_energy')#

Collects the classical energy into the output dictionary of the state object.

Parameters:
  • sim (Simulation) – The simulation object.

  • state (dict) – The state object.

  • parameters (dict) – The parameters object.

  • classical_energy_var_name (str) – Name of the classical energy variable in the state object.

  • classical_energy_output_name (str) – Name of the output variable for the classical energy.

Reads:

state[classical_energy_var_name] (ndarray, (B), float64) – The classical energy in each trajectory.

Writes:

state[“output_dict”][classical_energy_output_name] (ndarray, (B), float64) – stores the classical energy.

Shapes and dtypes:

B = sim.settings.batch_size

Requires:

None

Returns:

(state, parameters) – The updated state and parameters objects.

Return type:

tuple(dict, dict)

qclab.tasks.collect_tasks.collect_quantum_energy(sim: Simulation, state: dict, parameters: dict, quantum_energy_var_name: str = 'quantum_energy', quantum_energy_output_name: str = 'quantum_energy')#

Collects the quantum energy into the output dictionary of the state object.

Parameters:
  • sim (Simulation) – The simulation object.

  • state (dict) – The state object.

  • parameters (dict) – The parameters object.

  • quantum_energy_var_name (str) – Name of the quantum energy variable in the state object.

  • quantum_energy_output_name (str) – Name of the output variable for the quantum energy.

Reads:

state[quantum_energy_var_name] (ndarray, (B), float64) – The quantum energy in each trajectory.

Writes:

state[“output_dict”][quantum_energy_output_name] (ndarray, (B), float64) – The quantum energy in each trajectory.

Shapes and dtypes:

B = sim.settings.batch_size

Requires:

None

Returns:

(state, parameters) – The updated state and parameters objects.

Return type:

tuple(dict, dict)