maxwelllink.mxl_drivers.python.models.qutip_model module¶

class maxwelllink.mxl_drivers.python.models.qutip_model.QuTiPModel[source]¶

Bases: DummyModel

General N-level quantum model driven by an external E-field using QuTiP.

The time-dependent Hamiltonian is \(H(t) = H_0 - E_x(t)\mu_x - E_y(t)\mu_y - E_z(t)\mu_z\).

Two options for constructing the N-level quantum model are provided:

Preset TLS via a simple CLI parameter, e.g.: --param "preset=tls,preset_kwargs=omega=0.242,mu12=187,orientation=2,pe_initial=1e-4"

Fully custom model via: --param "module=/path/spec.py,kwargs=..."

The module must define a callable build_model(**kwargs) that returns a dictionary with the following keys:

def build_model(**kwargs):
    return {
        "H0": qutip.Qobj,                         # (N x N)
        "mu_ops": {"x": Qobj|None, "y": Qobj|None, "z": Qobj|None},
        "c_ops": [Qobj, ...],
        "rho0":  Qobj,                             # ket or density matrix
    }

Optional fields may be omitted; defaults: no c_ops, and rho0 is the ground state if not provided.

__init__(preset='tls', preset_kwargs='', module=None, kwargs='', fd_dmudt=False, verbose=False, checkpoint=False, restart=False, **extra)[source]¶

Initialize the necessary parameters for the QuTiP quantum dynamics model.

Parameters:

preset (str, default: 'tls') – Preset model name, e.g. 'tls'. Default is 'tls'.
preset_kwargs (str) – Comma-separated key=value pairs for the preset, such as preset_kwargs=omega=0.242,mu12=187,orientation=2,pe=1e-4. All key value pairs not recognized will be treated as preset parameters.
module (str or None, default: None) – Path to a Python file defining build_model(**kwargs).
kwargs (str) – Comma-separated key=value pairs for the user module, such as kwargs=omega=0.242,mu12=187,orientation=2,pe=1e-4. All key value pairs not recognized will be treated as user module parameters if module is not None.
fd_dmudt (bool, default: False) – Whether to use finite-difference \(\mathrm{d}\mu/\mathrm{d}t\) for current density computation. Default is False. If False, an analytical derivative will be used if available.
verbose (bool, default: False) – Whether to print verbose output. Default is False.
checkpoint (bool, default: False) – Whether to enable checkpointing. Default is False.
restart (bool, default: False) – Whether to restart from a checkpoint if available. Default is False.
**extra – Additional keyword arguments for future extensions.

append_additional_data()[source]¶

Append additional data to be sent back to MaxwellLink.

The data can be retrieved by the user via the Python interface: maxwelllink.SocketMolecule.additional_data_history, where additional_data_history is a list of dictionaries.

Returns:: A dictionary containing additional data.
Return type:: dict

calc_amp_vector()[source]¶

Calculate the amplitude vector \(\mathrm{d}\langle\mu\rangle/\mathrm{d}t\) for the current time step.

If fd_dmudt is True, use finite differences (cheaper); otherwise, use the analytical derivative if available.

Returns:: The amplitude vector \([\mathrm{d}\langle\mu_x\rangle/\mathrm{d}t,\ \mathrm{d}\langle\mu_y\rangle/\mathrm{d}t,\ \mathrm{d}\langle\mu_z\rangle/\mathrm{d}t]\).
Return type:: numpy.ndarray of float, shape (3,)

commit_step()¶

Commit the previewed step and return the staged amplitude.

This method applies the changes from the staged step to the internal state and returns the calculated amplitude vector.

Notes

This method should not be overridden by subclasses.

Returns:: Amplitude vector in the form \([\mathrm{d}\mu_x/\mathrm{d}t,\ \mathrm{d}\mu_y/\mathrm{d}t,\ \mathrm{d}\mu_z/\mathrm{d}t]\).
Return type:: numpy.ndarray of float, shape (3,)

have_result()¶

Check if a staged step is ready to be committed.

Notes

This method should not be overridden by subclasses.

Returns:: Whether a staged step is ready.
Return type:: bool

initialize(dt_new, molecule_id)[source]¶

Initialize the model with the new time step and molecule ID.

Parameters:

dt_new (float) – The new time step in atomic units (a.u.).
molecule_id (int) – The ID of the molecule.

propagate(effective_efield_vec)[source]¶

Propagate the quantum molecular dynamics given the effective electric field vector.

Parameters:: effective_efield_vec (array-like of float, shape (3,)) – Effective electric field vector in the form [E_x, E_y, E_z].

stage_step(E_vec)¶

Stage a propagation step with the given effective electric field vector.

This method performs the propagation and calculates the amplitude vector, but does not commit the changes to the internal state. The result can be committed later using the self.commit_step method.

Notes

This method should not be overridden by subclasses.

Parameters:: E_vec (array-like of float, shape (3,)) – Effective electric field vector in the form [E_x, E_y, E_z].