maxwelllink.molecule.molecule_legacy module

Legacy module defining molecule classes for coupling quantum molecular dynamics with Maxwell’s equations using MEEP.

Coupling to other Maxwell solvers should define analogous molecule classes.

class maxwelllink.molecule.molecule_legacy.DummyMolecule[source]

Bases: object

A minimal base class for molecules coupled to MEEP.

Subclasses implement propagation, source setup, and source-amplitude updates.

__init__(dt, dx, center=mp.Vector3(), size=mp.Vector3(1, 1, 1))[source]

Initialize basic molecule metadata and storage for MEEP sources.

Parameters:

  • dt (float) – Time step (MEEP units).

  • dx (float) – Spatial resolution (MEEP units).

  • center (meep.Vector3, default: meep.Vector3()) – Molecule center in the simulation domain.

  • size (meep.Vector3, default: meep.Vector3(1, 1, 1)) – Molecule extent used for integrals and source placement.

print_dynamics()[source]

Print molecule-specific dynamical information.

Notes

Subclasses should override to report relevant observables over time.

units_helper()[source]

Explain the unit system used by MEEP and its relation to atomic units.

Notes

Subclasses may override to print or return detailed conversion helpers.

update_molecule(sources_non_molecule=[])[source]

Return a MEEP step function that advances this molecule each time step.

Parameters:

sources_non_molecule (list, optional) – Additional non-molecule sources (e.g., Gaussian pulses) to include.

Returns:

Function of signature step(sim) suitable for sim.run(step, ...).

Return type:

Callable

class maxwelllink.molecule.molecule_legacy.SocketMolecule[source]

Bases: DummyMolecule

Molecule whose dynamics are provided by an external (socket) driver.

The driver receives field–polarization integrals and returns source amplitudes per component; the amplitudes are then applied via MEEP CustomSource.

__init__(hub, molecule_id, resolution, center=mp.Vector3(), size=mp.Vector3(1, 1, 1), dimensions=2, sigma=0.1, init_payload=None, time_units_fs=0.1, rescaling_factor=1.0)[source]

Initialize a socket-coupled molecule and register it with the hub.

Parameters:

  • hub (SocketHub) – Socket hub handling driver connections.

  • molecule_id (int) – Unique molecule identifier known to the driver.

  • resolution (int) – MEEP resolution; sets dt and dx.

  • center (meep.Vector3, default: meep.Vector3()) – Molecule center.

  • size (meep.Vector3, default: meep.Vector3(1, 1, 1)) – Molecule extent for integrals and sources.

  • dimensions (int, default: 2) – Simulation dimensionality (1, 2, or 3).

  • sigma (float, default: 0.1) – Width of the polarization density.

  • init_payload (dict or None, optional) – Extra initialization parameters forwarded to the driver.

  • time_units_fs (float, default: 0.1) – Time unit (fs). Driver time step is dt * time_units_fs * fs_to_au (a.u.).

  • rescaling_factor (float, default: 1.0) – Optional scaling applied to the polarization density.

print_dynamics()

Print molecule-specific dynamical information.

Notes

Subclasses should override to report relevant observables over time.

units_helper()[source]

Explain the MEEP unit system and its relation to atomic units.

Notes

Prints commonly used conversions for the current time_units_fs and simulation resolution.

update_molecule(sources_non_molecule=[])

Return a MEEP step function that advances this molecule each time step.

Parameters:

sources_non_molecule (list, optional) – Additional non-molecule sources (e.g., Gaussian pulses) to include.

Returns:

Function of signature step(sim) suitable for sim.run(step, ...).

Return type:

Callable

class maxwelllink.molecule.molecule_legacy.TLSMolecule[source]

Bases: DummyMolecule

Two-level system (TLS) molecule model.

Implements a Gaussian-like polarization profile and TLS dynamics driven by the local electric field.

__init__(resolution, center=mp.Vector3(), size=mp.Vector3(1, 1, 1), frequency=1.0, dipole_moment=0.1, sigma=0.1, orientation=mp.Ez, dimensions=2, rescaling_factor=1.0)[source]

Initialize a TLS molecule and its polarization profile.

Parameters:

  • resolution (int) – MEEP resolution; sets dt = 0.5/resolution and dx = 1/resolution.

  • center (meep.Vector3, default: meep.Vector3()) – Molecule center.

  • size (meep.Vector3, default: meep.Vector3(1, 1, 1)) – Molecule extent for integrals and sources.

  • frequency (float, default: 1.0) – TLS transition frequency \(\omega\) (MEEP units).

  • dipole_moment (float, default: 0.1) – Effective dipole moment magnitude.

  • sigma (float, default: 0.1) – Width of the polarization density.

  • orientation (meep.EComponent, default: meep.Ez) – Polarization component (mp.Ex, mp.Ey, or mp.Ez).

  • dimensions (int, default: 2) – Dimensionality (1, 2, or 3). In 1D/2D the orientation is constrained to mp.Ez.

  • rescaling_factor (float, default: 1.0) – Optional scaling applied to the polarization density and dipole moment.

append_additional_data()[source]

Append diagnostic data for the current TLS state.

Returns:

Dictionary with time, populations (Pg, Pe) and coherence terms (Pge_real, Pge_imag).

Return type:

dict

print_dynamics()[source]

Print basic TLS dynamics (e.g., excited-state population) over time.

reset_tls_population(excited_population=0.1)[source]

Reset the TLS population to a specified excited-state fraction.

Parameters:

excited_population (float, default: 0.1) – Population of the excited state (between 0 and 1).

units_helper()

Explain the unit system used by MEEP and its relation to atomic units.

Notes

Subclasses may override to print or return detailed conversion helpers.

update_molecule(sources_non_molecule=[])

Return a MEEP step function that advances this molecule each time step.

Parameters:

sources_non_molecule (list, optional) – Additional non-molecule sources (e.g., Gaussian pulses) to include.

Returns:

Function of signature step(sim) suitable for sim.run(step, ...).

Return type:

Callable

maxwelllink.molecule.molecule_legacy.atomic_to_meep_units_SourceAmp(amp_au_vec3, time_units_fs=0.1)[source]

Convert source amplitudes (dipole-rate) from atomic units to MEEP units.

The source amplitude has units of dipole moment per unit time.

Parameters:

  • amp_au_vec3 (array-like, shape (3,)) – Source amplitude(s) in atomic units.

  • time_units_fs (float, default: 0.1) – Time unit used for conversion.

Returns:

Source amplitude(s) in MEEP units.

Return type:

numpy.ndarray

maxwelllink.molecule.molecule_legacy.make_custom_time_src(key)[source]

Create a MEEP CustomSource that reads an accumulator keyed by key.

Parameters:

key (hashable) – Fingerprint identifying a shared polarization density.

Returns:

Custom source whose time-dependent amplitude is taken from the global instantaneous_source_amplitudes[key] each MEEP step.

Return type:

meep.CustomSource

maxwelllink.molecule.molecule_legacy.meep_to_atomic_units_E(Emu_vec3, time_units_fs=0.1)[source]

Convert E-field integrals from MEEP units to atomic units.

Parameters:

  • Emu_vec3 (array-like, shape (3,)) – Field integral(s) in MEEP units.

  • time_units_fs (float, default: 0.1) – Time unit \(\tau\) in femtoseconds.

Returns:

Field integral(s) in atomic units.

Return type:

numpy.ndarray

maxwelllink.molecule.molecule_legacy.reset_module_state()[source]

Clear shared global state so a new simulation starts from a clean slate.

Notes

Resets both the per–time step source amplitude cache and the fingerprint map. Call this between simulations (e.g., in test suites) to avoid cross-run bleed.

maxwelllink.molecule.molecule_legacy.update_molecules(hub, molecules, sources_non_molecule=None)[source]

MPI-safe collective step function for multiple socket molecules.

Parameters:

  • hub (SocketHub) – Socket hub used by the master rank.

  • molecules (list of SocketMolecule) – Molecules to advance.

  • sources_non_molecule (list, optional) – Non-molecule sources to include.

Returns:

Function step(sim) for use with sim.run(step, ...) on all ranks.

Return type:

Callable

Notes

Performs driver synchronization on the master, broadcasts amplitudes to workers, and updates shared accumulators without additional source changes.

maxwelllink.molecule.molecule_legacy.update_molecules_no_mpi(hub, molecules, sources_non_molecule=None)[source]

Collective step function for multiple socket molecules (no MPI).

Parameters:

  • hub (SocketHub) – Socket hub to use for communication.

  • molecules (list of SocketMolecule) – Molecules to advance.

  • sources_non_molecule (list, optional) – Non-molecule sources to include.

Returns:

Function step(sim) to be passed to sim.run(step, ...).

Return type:

Callable

Notes

Handles binding/rebinding of drivers, performs barrier-style exchanges, and accumulates amplitudes into per-fingerprint component bins.

maxwelllink.molecule.molecule_legacy.update_molecules_no_socket(sources_non_molecule=None, molecules=None)[source]

Step function for molecule collections without socket-based drivers.

Parameters:

  • sources_non_molecule (list or None) – Non-molecule sources to include in the simulation.

  • molecules (list or None) – List of molecule instances (e.g., TLSMolecule).

Returns:

Function step(sim) to be passed to sim.run(step, ...).

Return type:

Callable

Notes

Accumulates per-fingerprint source amplitudes so multiple molecules sharing the same polarization density drive a single shared CustomSource.