maxwelllink.sockets.susceptibility module

SocketHub for Meep MXLSocketSusceptibility with direct driver connections.

This is the hub behind the production Meep+LAMMPS workflow: one TCP listener serves both ordinary mxl_driver/LAMMPS clients (silent at connect time) and Meep rank clients (which announce themselves with an MXLINIT banner):

Meep rank (C client) ==MXLINIT/AGGSTEP==> _SusceptibilitySocketHubServer
mxl_driver / LAMMPS  ==i-PI protocol===>      (child process, SocketHub)

The user-facing SusceptibilitySocketHub is a thin proxy: the real server runs in a child process because Meep’s C-level time-step loop holds the GIL while waiting on the socket (see _meep_hub_base.py for the shared layer and the full class diagram).

class maxwelllink.sockets.susceptibility.SusceptibilitySocketHub[source]

Bases: _HubProcessProxy

Process-backed hub for Meep MXLSocketSusceptibility connections.

The hub starts immediately during construction and exposes the endpoint fields consumed by mp.MXLSocketSusceptibility(hub=hub). The actual server (_SusceptibilitySocketHubServer) runs in a child process; see _meep_hub_base.py for why and for the shared proxy machinery.

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).

  • driver_count_file (str or None, default: "num_socket_molecule") – File that receives the total number of socket molecules required by Meep, written by the child server as a single integer after MXLINIT. Set to None to disable.

Variables:

  • host (str) – Resolved bind host of the running server.

  • port (int) – Resolved bind port of the running server.

  • address (str) – Alias of host.

  • rank_stats (dict[int, dict]) – Latest per-Meep-rank statistics drained from the child process.

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, driver_count_file='num_socket_molecule')[source]

Initialize the proxy-side state shared by every process-backed hub.

Concrete hubs validate their own arguments, call this, set any extra attributes, and then call _start_server_process(). Pre-setting the lifecycle attributes here keeps stop() and __del__ safe even when a subclass __init__ fails before the child is launched.

Parameters:

  • timeout (float) – Socket timeout (seconds) passed to the child server.

  • latency (float) – Polling interval (seconds) passed to the child server.

  • host (str | None)

  • port (int | None)

  • unixsocket (str | None)

  • driver_count_file (str | None)

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

Convert a Meep Lorentzian susceptibility to SHO driver parameters.

The numerical mapping is lorentzian_to_sho_parameters(); this template adds the launch command from _driver_command_for() (targeting this hub’s transport), prints a short report on the MPI master, and merges any _conversion_extras() into the result.

Returns:

{"rescaling_factor", "driver_command", ...extras} where rescaling_factor is the symmetric bright-state coupling scale to pass to mp.MXLSocketSusceptibility(rescaling_factor=...).

Return type:

dict

Raises:

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

Parameters:

  • frequency (float)

  • sigma (float)

  • resolution (float)

  • gamma (float)

  • dimensions (int)

  • time_units_fs (float)

  • mu0_au (float)

  • orientation (int)

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()

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