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[source]

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, polarization_type=None)[source]
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 list 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).

  • polarization_type (str or None, optional) – Type of polarization to use in EM FDTD propagation. Six options: analytical, numerical, transverse, point, point-raw, anisotropic. Default is analytical. analytical uses analytical Gaussian polarization profile; numerical uses numerical Gaussian polarization profile; transverse uses approximate transverse components of numerical Gaussian polarization profile from FFT; point uses point dipole approximation, which might not be accurate for evaluating self-interaction; point-raw uses point dipole approximation with no sub-averaging over dx^3, which can be very inaccurate for evaluating self-interaction; anisotropic uses anisotropic and analytical Gaussian polarization profile [self.sigma should be a list of three floats for (sigma_x, sigma_y, sigma_z) instead of a single float].

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()[source]

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)[source]

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.

post_process_additional_data()[source]

Post-process the raw additional_data_history into a more compact form and store it in self.extra.

This function can be customized based on the specific data fields stored in additional_data_history.

This function should be called before closing the simulation.

propagate(efield_vec3)[source]

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[source]

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