maxwelllink.sockets.susceptibility module

SocketHub for Meep MXLSocketSusceptibility connections.

This module bridges Meep’s C-level MXLSocketSusceptibility to MaxwellLink socket molecule drivers. A single TCP listener accepts two kinds of clients and tells them apart by what they send first:

  • Ordinary mxl_driver clients stay silent at connect time and are handed to the inherited SocketHub binding/stepping machinery (see _SusceptibilitySocketHubServer._register_driver_socket()).

  • Meep rank clients send an MXLINIT header immediately and are served by a dedicated per-rank handler (see _SusceptibilitySocketHubServer._serve_meep_rank()).

The user-facing entry point is SusceptibilitySocketHub, which launches the server in a child process (so Meep holding the GIL cannot deadlock the handshake) and exposes the host/port consumed by mp.MXLSocketSusceptibility(hub=hub).

class maxwelllink.sockets.susceptibility.SusceptibilitySocketHub[source]

Bases: object

Process-backed hub for Meep MXLSocketSusceptibility connections.

The public object starts immediately during construction and exposes the endpoint fields consumed by mp.MXLSocketSusceptibility(hub=hub). The actual server runs in a child process because Meep’s long C-level time-step loop can hold Python’s GIL while waiting on the socket; an in-process Python thread would therefore deadlock at the first MXLINIT/MXLREADY handshake. The child server is _SusceptibilitySocketHubServer, which is the SocketHub-derived implementation that reuses MaxwellLink’s optimized driver binding and stepping path.

Under MPI only the master rank launches the child server; every rank then learns the resolved endpoint through mpi_bcast_from_master(), so all ranks agree on the host/port to connect to.

Parameters:

  • host (str or None, optional) – Bind host for the server. None uses the server default.

  • port (int or None, default: 31415) – Bind port. 0 requests an OS-chosen ephemeral port.

  • timeout (float, default: 60000.0) – Socket timeout in seconds passed to the server.

  • latency (float, default: 0.05) – Polling interval in seconds passed to the server.

  • unixsocket (str or None, optional) – Reserved; must be falsy (TCP only).

host

Resolved bind host of the running server.

Type:

str

port

Resolved bind port of the running server.

Type:

int

address

Alias of host.

Type:

str

rank_stats

Latest per-Meep-rank statistics drained from the child process.

Type:

dict[int, dict]

Raises:

  • ValueError – If unixsocket is given.

  • RuntimeError – If the child server fails to start.

__init__(host=None, port=31415, timeout=60000.0, latency=0.05, unixsocket=None)[source]
Parameters:

  • host (str | None)

  • port (int | None)

  • timeout (float)

  • latency (float)

  • unixsocket (str | None)

lorentzian_conversion(frequency, sigma, resolution, *, gamma=0.0, dimensions=1, time_units_fs=0.1, mu0_au=187.0819866, orientation=0)[source]

Convert a Meep Lorentzian susceptibility to SHO driver parameters.

Maps the standard Meep Lorentzian dielectric parameters (resonance frequency, oscillator strength sigma) onto the simple-harmonic oscillator (SHO) molecular driver: a resonance omega in atomic units, the fixed transition dipole mu0_au, and the rescaling_factor that the Meep MXLSocketSusceptibility applies so one socket molecule reproduces the per-cell Lorentzian response.

Parameters:

  • frequency (float) – Lorentzian resonance frequency in Meep units (must be > 0).

  • sigma (float) – Lorentzian oscillator strength (must be >= 0).

  • resolution (float) – Meep grid resolution in pixels per unit length (must be > 0); sets the grid-cell measure (1 / resolution) ** dimensions.

  • gamma (float, default: 0.0) – Lorentzian damping rate. Accepted for API symmetry but ignored: the current SHO driver is lossless (a warning is printed if nonzero).

  • dimensions (int, default: 1) – Simulation dimensionality, used to form the cell measure (>= 1).

  • time_units_fs (float, default: 0.1) – Meep time unit in femtoseconds; sets the Meep<->a.u. conversions.

  • mu0_au (float, default: 187.0819866) – SHO transition dipole moment in atomic units (must be nonzero).

  • orientation (int, default: 0) – Dipole axis: 0 (x), 1 (y), or 2 (z).

Returns:

Dictionary with two keys:

  • "rescaling_factor" : float Value to pass to mp.MXLSocketSusceptibility(rescaling_factor=...).

  • "driver_command" : str Ready-to-run shell command that launches one matching mxl_driver --model sho client against this hub.

Return type:

dict

Raises:

ValueError – If any argument is outside its documented valid range.

property rank_stats: dict[int, dict]

Latest per-Meep-rank statistics from the running server.

Returns:

Mapping from rank to its stats row (molecule_count, steps, requests, peer). Empty on non-master ranks.

Return type:

dict[int, dict]

stop()[source]

Stop the hub and tear down the child server process.

Idempotent and safe on non-master ranks. Signals the child via the stop event, joins it, and falls back to terminate() if it does not exit; a final stats drain captures any closing counters.

Return type:

None