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
andstate
objects with variables in thesim.initial_state
object. For any numpy ndarray insim.initial_state
, a new array is created instate
with shape(batch_size, *original_shape)
whereoriginal_shape
is the shape of the array insim.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
, andt_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.
- 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
, andalgorithm
.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:
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
isTrue
.- 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 bystate.{basis}
and stores it instate.{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 eigenvaluesstate.{eigvals_name}
and eigenvectorsstate.{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 hamiltonianstate.{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 instate.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 instate.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 withfunctions.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 ofstate.{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 ofstate.{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:
- 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:
See also
- 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:
- 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:
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:
- 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:
- 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: