maxwelllink.cavity.vacuum module

Free space: an empty FDTD cell with absorbing (PML) boundaries.

class maxwelllink.cavity.vacuum.Vacuum[source]

Bases: DummyCavity

An empty FDTD cell with absorbing (PML) boundaries, aka free space.

Useful for spontaneous-emission and free-propagation tests.

All placement and measurement methods are inherited from DummyCavity unchanged.

Notes

With dimensions=mxl.CYLINDRICAL the cell is an (r, z) half plane: the axis sits at r = 0, the allowed region spans r in [0, size_r] and z in [-size_z/2, +size_z/2].

Since the field of a z-polarized dipole on the axis has full rotational symmetry, an m = 0 cylindrical run (make_simulation(m=0)) reproduces 3D free-space physics at 2D cost. An on-axis x- or y-polarized dipole can instead use one complex m = +1 or m = -1 sector.

Examples

>>> from maxwelllink.cavity import Vacuum
>>> cav = Vacuum(size_nm=4000.0, omega_ref=2320.0, units="cm-1", dimensions=1)
>>> mol = cav.place_molecule(driver="tls", driver_kwargs=dict(
...     omega=0.0106,  # driver parameters are in a.u.; ~2326 cm^-1
...     mu12=187.0, orientation=2, pe_initial=1e-4))
>>> sim = cav.make_simulation(molecules=[mol])
>>> sim.run(until=200)
__init__(size_nm, omega_ref, units='cm-1', dimensions=1, resolution=None, pml_nm=None)[source]

Initialize the parameters of an empty FDTD cell (free space).

Parameters:

  • size_nm (float or sequence of floats) – Interior size (nm) of the allowed region, excluding the PML that is added outside. A scalar gives an equal extent along every active axis; a sequence must have one entry per active axis such as (x,), (x, y), (x, y, z), or (r, z) for cylindrical cells.

  • omega_ref (float) – Reference frequency (or wavelength) that sets the default resolution and PML thickness.

  • units (str, default: "cm-1") – Units of omega_ref: “cm-1”, “eV”, “au”, “nm”, or “um”.

  • dimensions (int, default: 1) – 1, 2, 3, or mxl.CYLINDRICAL.

  • resolution (float or None, optional) – Meep resolution (pixels per Meep length unit). Default: 20 pixels per reference wavelength (the DummyCavity default).

  • pml_nm (float or None, optional) – PML thickness in nm. Default: one reference wavelength.

property allowed_bounds_nm

Per-axis allowed bounds in nm, e.g. {"x": (-704.5, 704.5)}.

emission_setup(offset_nm=(0.0, 0.0, 0.0), component=None)

Return the local-dipole (Purcell) probe of this cavity as a plain dict, consumed by purcell.

Keys of the setup dict:

  • "excitation" : the point dipole ("center", zero "size"), at the hotspot by default;

  • "component" : the dipole orientation;

  • "detectors" : dict of named flux surfaces (lists of mp.FluxRegion); the required "radiated" entry is the full surface through which the cavity radiates;

  • "reference_geometry" : the homogeneous medium of the normalization run (same permittivity at the dipole as the cavity);

  • "reference_surface" : a closed surface of the (lossless) reference run, capturing the total emitted power;

  • "reference_boundary_layers" : optional boundary layers of the reference run;

  • "reference_simulation_kwargs" : optional reference-only Meep parameters such as cell_size, geometry_center, and resolution for reducing the reference computational cost;

  • "decay_monitor" : optional mp.Vector3 watched by the stopping criterion, kept away from the singular dipole self-field.

The default implemented here uses the cavity cell itself as the reference, so the Purcell factor of the template is identically 1.

Notes

This method can be optionally overridden by subclasses; see BraggResonator.emission_setup and NPoM.emission_setup.

Parameters:

  • offset_nm (sequence of three floats, default: (0, 0, 0)) – Displacement (nm) of the dipole from the hotspot.

  • component (Meep field component or None, optional) – Dipole orientation. Default: mp.Ez.

estimate_driver_count(region)

Estimate how many socket molecules (drivers) a region needs, equal to the number of FDTD grid points inside it.

The authoritative number is written by the susceptibility hub to its driver_count_file once Meep connects.

Notes

The default implemented here counts the grid points of a box-shaped region (the slab of the default place_region). This method can be optionally overridden by subclasses.

Parameters:

region (Meep geometric object) – The region returned by place_region.

Returns:

The estimated number of drivers (grid points inside the region).

Return type:

int

linear_spectrum(omega_min, omega_max, units='cm-1', **kwargs)

Compute the far-field linear spectrum of the cavity: the probe declared by optical_setup().

This gives transmission/reflection/absorption for mirror cavities and scattering/absorption/extinction for plasmonic nanocavities.

For the local-dipole (Purcell) observables, use purcell instead.

Parameters:

  • omega_min (float) – Frequency window in units.

  • omega_max (float) – Frequency window in units.

  • units (str, default: "cm-1") – Units of the window: “cm-1”, “eV”, “au”, “nm”, or “um”.

  • **kwargs – Forwarded to MeepCavityMeasurement: molecules, hub, extra_geometry, nfreq, decay_by, steps, max_time, min_time, source_amplitude, and extra Meep keyword arguments.

Returns:

Dictionary with arrays omega_cminv, wavelength_nm, frequency_meep, and the observables of the declared probe.

Return type:

dict

make_simulation(molecules=None, hub=None, sources=None, extra_geometry=(), **meep_kwargs)

Build the mxl.MeepSimulation for this cavity.

  • Pass hub and molecules for molecule-level coupling via sockets;

  • Pass hub and extra_geometry for grid-level coupling via sockets;

  • Pass molecules alone for molecule-level coupling via embedded drivers (with driver and driver_kwargs in the molecules);

  • Pass nothing at all for a pure Meep simulation.

Parameters:

  • molecules (sequence of mxl.Molecule or None, optional) – Molecules to include in the simulation.

  • hub (SocketHub or None, optional) – Socket hub shared by socket-mode molecules.

  • sources (sequence or None, optional) – Additional native Meep sources (laser excitation etc.).

  • extra_geometry (sequence, optional) – Geometry appended after the cavity structure, e.g. the region from place_region.

  • **meep_kwargs – Extra keyword arguments forwarded to the simulation; they override the cavity defaults on conflicts.

meep_to_nm(value_meep)

Convert a length from Meep units to nanometers.

nm_to_meep(value_nm)

Convert a length from nanometers to Meep units.

optical_setup()

Return the far-field probe of this cavity as a plain dict, consumed by linear_spectrum and the measurement classes in maxwelllink.measurements.

Keys of the setup dict:

  • "probe" : "transmission" (partly transmitting cavities), "reflection" (opaque mirror-backed cavities), or "scattering" (localized plasmonic nanocavities);

  • "excitation" : {"center", "size"} of the source region;

  • "detectors" : dict of named detectors – "transmission" and "reflection" planes (dicts with "center" and "size"), or the "scattered" surface and closed "absorption_box" of a scattering probe (lists of mp.FluxRegion);

  • "component" : the field component injected and detected;

  • "source_amplitude" : optional overall probe amplitude;

  • "source_components" : optional phased source components, each a dict with "component" and optional relative "amplitude";

  • "source_is_integrated" : optional Meep integrated-source flag;

  • "reference_geometry" : the structure of the normalization run;

  • "reference_boundary_layers" : optional boundary layers of the normalization run (transmission probe only);

  • "normalization" : region recording the incident intensity (scattering probe only);

  • "decay_monitor" : optional mp.Vector3 watched by the stopping criterion.

The default implemented here is a transmission probe along x (along z in cylindrical cells) with a vacuum reference.

The local-dipole (Purcell) probe is declared separately by emission_setup.

Notes

This method can be optionally overridden by subclasses.

place_molecule(hub=None, driver=None, offset_nm=(0.0, 0.0, 0.0), size_nm=None, sigma_nm=None, hotspot=None, **molecule_kwargs)

Create an mxl.Molecule inside the cavity (molecule-level coupling).

The molecule sits at the cavity hotspot by default and can be shifted with offset_nm.

Its center, size, sigma, and dimensions are chosen consistently with the cavity grid, so the returned molecule can be passed directly to make_simulation.

Use place_region instead for grid-level coupling.

Notes

This method should not be overridden by subclasses.

Parameters:

  • hub (SocketHub or None, optional) – Socket hub for socket-mode molecules, exclusive with driver.

  • driver (str or None, optional) – Embedded driver name for non-socket molecules (e.g. "tls"), exclusive with hub.

  • offset_nm (sequence of three floats, default: (0, 0, 0)) – Displacement (nm) from the hotspot; only components along active axes may be nonzero. Cylindrical molecule coupling supports only an on-axis molecule, so only (0, 0, dz) is accepted there.

  • size_nm (float or None, optional) – Extent of the molecular polarization region along every active axis. Default: ten times sigma.

  • sigma_nm (float or None, optional) – Width of the regularized polarization kernel. Default: two grid points, which keeps the kernel resolvable at any resolution.

  • hotspot (str or None, optional) – Name of an entry in self.hotspots to place the molecule at, for cavities with several field maxima. Default: hotspot_center.

  • **molecule_kwargs – Forwarded verbatim to mxl.Molecule (e.g. driver_kwargs, rescaling_factor, polarization_type). For the anisotropic polarization type, construct mxl.Molecule directly instead (it needs a three-component sigma).

Return type:

maxwelllink.Molecule

place_region(epsilon=1.0, hub=None, offset_nm=(0.0, 0.0, 0.0), width_nm=None, rescaling_factor=1.0, **susceptibility_kwargs)

Create a region of molecular medium inside the cavity (grid-level coupling), where every FDTD grid point inside the region becomes one socket molecule (TCP sockets only).

Pass the returned region to make_simulation via extra_geometry=[region]. Use place_molecule instead for molecule-level coupling.

The shape of the region is a convention of each cavity type. The default implemented here is a slab along x filling the allowed region (e.g. the defect gap of a Bragg resonator), with width_nm shrinking the slab thickness along x.

Notes

This method can be optionally overridden by subclasses whose region is not a slab (see NPoM.place_region).

Parameters:

  • epsilon (float, default: 1.0) – Background permittivity of the molecular medium.

  • hub (SusceptibilitySocketHub or None, optional) – Socket hub of the grid-level route.

  • offset_nm (sequence of three floats, default: (0, 0, 0)) – Displacement (nm) of the region center from the hotspot.

  • width_nm (float or None, optional) – Size (nm) of the region under the cavity-specific convention (here: the slab thickness along x). Default: fill the natural region of the cavity.

  • rescaling_factor (float, default: 1.0) – Rescaling factor of mp.MXLSocketSusceptibility.

  • **susceptibility_kwargs – Forwarded to mp.MXLSocketSusceptibility (e.g. real_field_only, timeout).

Returns:

Pass it to make_simulation via extra_geometry=[region].

Return type:

mp.Block

plot(ax=None, **kwargs)

Visualize the cavity structure and its optical setup.

Parameters:

  • ax (matplotlib Axes or None, optional) – Axes to draw into. A new figure is created when None.

  • **kwargs – Forwarded to mp.Simulation.plot2D in 2D and 3D.

Returns:

The axes containing the plot.

Return type:

matplotlib Axes

purcell(omega_min, omega_max, units='cm-1', offset_nm=(0.0, 0.0, 0.0), component=None, **kwargs)

Compute the Purcell spectrum of the cavity.

A point dipole at the hotspot drives the cavity in one run and the homogeneous reference structure of emission_setup() in another, and every observable is the ratio of the two runs.

Parameters:

  • omega_min (float) – Frequency window in units.

  • omega_max (float) – Frequency window in units.

  • units (str, default: "cm-1") – Units of the window: “cm-1”, “eV”, “au”, “nm”, or “um”.

  • offset_nm (sequence of three floats, default: (0, 0, 0)) – Displacement (nm) of the dipole from the hotspot.

  • component (Meep field component or None, optional) – Dipole orientation (e.g. mp.Er). Default: the orientation chosen by the cavity (mp.Ez).

  • **kwargs – Forwarded to MeepCavityMeasurement: molecules, hub, extra_geometry, nfreq, decay_by, steps, max_time, min_time, and extra Meep keyword arguments.

Returns:

Dictionary with arrays omega_cminv, wavelength_nm, frequency_meep, and the Purcell observables: purcell (total decay-rate enhancement), purcell_radiative (far-field enhancement), radiative_efficiency (their ratio), plus the raw LDOS and flux arrays.

Return type:

dict

sim_kwargs(extra_geometry=())

Return the generated Meep ingredients as a plain dict, for users who prefer to assemble mp.Simulation(**kwargs) themselves.

Parameters:

extra_geometry (sequence, optional) – Geometry appended after the cavity structure.

Returns:

Keyword arguments for mp.Simulation: cell_size, geometry, boundary_layers, resolution, and k_point when the cavity is periodic.

Return type:

dict

summary()

Return a human-readable description of the generated setup (MPI Safe).