maxwelllink.molecule.molecule module

A molecule class capable of operating in both socket and non-socket modes.

In socket mode, the molecule communicates with an external process (e.g., a quantum driver) via a socket connection through SocketHub. In non-socket mode, it directly instantiates a molecular dynamics driver defined in __drivers__ (e.g., tlsmodel, qutipmodel).

EM-specific source creation and field-integral computations are provided by backend modules.

class maxwelllink.molecule.molecule.Molecule

Bases: object

A molecule class which can support both socket and non-socket modes.

EM-specific source creation and field-integral computation are provided by EM backends.

__init__(hub=None, driver=None, center=None, size=None, dimensions=None, sigma=None, resolution=None, init_payload=None, driver_kwargs=None, rescaling_factor=1.0, store_additional_data=True)

Parameters:

• hub (SocketHub or None, optional) – Socket hub for socket mode. If provided, driver must be None.

• driver (str or None, optional) – Driver name for non-socket mode. If provided, hub must be None.

• center (Vector3 or None, optional) – Molecule center position.

• size (Vector3 or None, optional) – Molecule size (extent).

• dimensions (int or None, optional) – Simulation dimensionality; one of 1, 2, or 3.

• sigma (float or None, optional) – Spatial polarization kernel width.

• resolution (int or None, optional) – Optional real-space resolution for building FDTD sources.

• init_payload (dict or None, optional) – Optional initialization payload for socket communication with molecular drivers.

• driver_kwargs (dict or None, optional) – Keyword arguments passed to the selected driver in non-socket mode.

• rescaling_factor (float, default: 1.0) – Rescaling factor for polarization.

• store_additional_data (bool, default: True) – Whether to store additional data history as a growing list (if True) or only keep the latest five frames (if False).

Raises:

• ValueError – If both hub and driver are provided, or neither is provided, or if dimensions is not in {1, 2, 3}, or if an unsupported driver is requested in non-socket mode.

• ImportError – If the requested driver cannot be imported.

• Exception – If driver setup fails for other reasons (the driver docstring is printed).

calc_amp_vector()

Compute and return the source amplitude vector for the current step.

Returns:

Amplitude vector, typically \([\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,)

Raises:

• NotImplementedError – If called in socket mode (not implemented yet).

• RuntimeError – If the molecule is not properly initialized in socket or non-socket mode.

initialize_driver(dt_au, molecule_id)

Initialize the non-socket driver with the given time step (a.u.) and molecule ID.

Parameters:

• dt_au (float) – Time step in atomic units passed to the driver.

• molecule_id (int) – Molecule identifier.

Raises:

• NotImplementedError – If called in socket mode (not implemented yet).

• RuntimeError – If the molecule is not properly initialized in socket or non-socket mode.

propagate(efield_vec3)

Propagate the molecule by one step under the given effective electric field.

Parameters:

efield_vec3 (array-like of float, shape (3,)) – Effective electric field vector [E_x, E_y, E_z].

Raises:

• NotImplementedError – If called in socket mode (not implemented yet).

• RuntimeError – If the molecule is not properly initialized in socket or non-socket mode.

class maxwelllink.molecule.molecule.Vector3

Bases: object

Minimal 3D vector container used to avoid depending on mp.Vector3 in the abstract layer.

__init__(x=0.0, y=0.0, z=0.0)

Parameters:

• x (float)

• y (float)

• z (float)

Return type:

None

x: float = 0.0

y: float = 0.0

z: float = 0.0