maxwelllink.cavity package¶

User-friendly FDTD cavity builders for Meep FDTD coupled with MXL Molecules.

Example

>>> from maxwelllink.cavity import BraggResonator
>>> cav = BraggResonator(omega=2320.0, units="cm-1", n_pairs=10, 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)

class maxwelllink.cavity.BraggResonator[source]¶

Bases: DummyCavity

A quarter-wave Bragg (DBR) cavity in 1, 2, or 3 dimensions or in cylindrical coordinates.

The mirrors are quarter-wave dielectric stacks: alternating layers of high (n_hi) and low (n_lo) refractive index, each one quarter of the design wavelength thick inside its medium.

Examples

>>> from maxwelllink.cavity import BraggResonator
>>> cav = BraggResonator(omega=2320.0, units="cm-1", n_pairs=10,
...                      n_hi=2.0, n_lo=1.0, dimensions=1)
>>> print(cav.summary())

__init__(omega, units='cm-1', n_pairs=3, n_hi=2.0, n_lo=1.0, n_defect=1.0, defect_order=1, dimensions=1, mirror_shape='auto', lateral_size_nm=None, lateral_boundary='pml', resolution=None, pml_nm=None)[source]¶

Initialize the parameters of a quarter-wave Bragg (DBR) cavity.

Parameters:

omega (float) – Target cavity resonance in units.
units (str, default: "cm-1") – Units of omega: “cm-1”, “eV”, “au”, “nm”, or “um”.
n_pairs (int, default: 3) – Number of quarter-wave layer pairs per mirror (the Q dial).
n_hi (float, default: 2.0) – High refractive index of the mirror stack (n_hi > n_lo).
n_lo (float, default: 1.0) – Low refractive index of the mirror stack.
n_defect (float, default: 1.0) – Refractive index of the defect gap between the mirrors.
defect_order (int, default: 1) – The gap has an optical length of defect_order half wavelengths; for ring mirrors, the core boundary sits at the defect_order-th zero of J0 instead.
dimensions (int, default: 1) – 1, 2, or 3 (layer stack along x), or mxl.CYLINDRICAL (the (r, z) half plane; m = 0 by default).
mirror_shape (str, default: "auto") – "planar" for flat mirror stacks (along x in Cartesian cells, disks along z in cylindrical ones) or "cylindrical" for concentric ring mirrors around the z axis (cylindrical cells only). "auto" resolves to "cylindrical" for dimensions=mxl.CYLINDRICAL and "planar" otherwise.
lateral_size_nm (float or None, optional) – Extent (nm) of the allowed region along the directions parallel to the mirrors: y (and z) in 2D/3D, the cavity radius for cylindrical cells with planar (disk) mirrors, or the cell height along z for ring mirrors. Default: 5 cavity wavelengths. Must be omitted in 1D.
lateral_boundary (str, default: "pml") – "periodic" for an infinite planar cavity (Bloch-periodic boundaries) or "pml" for absorbing lateral boundaries (the only option for cylindrical cells).
resolution (float or None, optional) – Meep resolution. Default: at least 20 pixels per wavelength in the densest medium and 8 pixels across the thinnest layer.
pml_nm (float or None, optional) – PML thickness in nm. Default: one cavity 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)[source]¶

Local-dipole (Purcell) probe of the Bragg cavity: a dipole in the defect gap, polarized parallel to the mirror planes, read out through one plane outside each mirror.

The reference is the homogeneous defect medium (n_defect), so the LDOS ratio is exact. Same keys as DummyCavity.emission_setup.

Notes

Cylindrical cells with the default ring mirrors use an on-axis z-polarized dipole (m = 0), which couples to the confined Ez mode and is regular on the axis.

Cylindrical cells with planar (disk) mirrors default to an azimuthally symmetric (m = 0) ring of radial dipole; for the m = +-1 near-axis dipole, pass component=mp.Er together with m=1.

Parameters:

offset_nm (sequence of three floats, default: (0, 0, 0)) – Displacement (nm) of the dipole from the defect center.
component (Meep field component or None, optional) – Dipole orientation. Default: mp.Ez (parallel to the mirrors) in Cartesian cells and for cylindrical ring mirrors, mp.Er for cylindrical disk mirrors.

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

Build the simulation as DummyCavity.make_simulation does, after checking that a cylindrical run is consistent with its azimuthal sector m (see _check_cylindrical_sector).

Cartesian cells pass straight through.

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

Optical setup of the Bragg cavity.

Planar mirrors use the generic transmission planes of DummyCavity.optical_setup.

Cylindrical (ring) mirrors use the dark-field-type scattering probe (cf. NPoM.optical_setup): an incoming cylindrical wave from a ring source in the radial clearance outside the mirrors drives the m = 0 mode.

In both cases the reference structure is a homogeneous n_lo medium (for the default n_lo = 1: vacuum).

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

class maxwelllink.cavity.DummyCavity[source]¶

Bases: object

A dummy FDTD cavity for demonstration purposes.

This class serves as a template for implementing specific cavity builders. By itself it describes a minimal empty cell enclosed by perfect metallic walls.

Note that the Meep length unit is always fixed to 1 micrometer.

__init__(omega=3000.0, units='cm-1', dimensions=1)[source]¶

Initialize the necessary attributes for a minimal empty FDTD cavity.

Notes

This method should be overridden by subclasses to build the actual cavity.

Call super().__init__(omega, units, dimensions) first, then overwrite the attributes the new cavity changes (geometry, cell_size, allowed_bounds, …).

Parameters:

omega (float, default: 3000.0) – Design frequency (or wavelength) of the cavity in units.
units (str, default: "cm-1") – Units of omega: “cm-1”, “eV”, “au”, “nm”, or “um”.
dimensions (int, default: 1) – Dimensionality of the FDTD simulation: 1, 2, or 3 for Cartesian cells, or mxl.CYLINDRICAL for a cylindrical (r, z) cell.

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

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

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

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

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)[source]¶: Convert a length from Meep units to nanometers.

nm_to_meep(value_nm)[source]¶: Convert a length from nanometers to Meep units.

optical_setup()[source]¶

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

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

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.

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

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

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:

Return type:

dict

sim_kwargs(extra_geometry=())[source]¶

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()[source]¶: Return a human-readable description of the generated setup (MPI Safe).

class maxwelllink.cavity.NPoM[source]¶

Bases: DummyCavity

A gold nanosphere above a gold mirror, separated by a molecular spacer.

The geometry convention follows Chikkaraddy et al., Nature 535, 127 (2016), doi:10.1038/nature17974.

The gap center on the symmetry axis is the hotspot, and the allowed region is the spacer disk underneath the particle.

The gap plasmon is a rotationally symmetric mode polarized along z, so a cylindrical m = 0 run reproduces the full 3D physics at 2D cost.

The paper’s dark-field scattering spectrum comes from linear_spectrum and its classical-emitter Purcell spectrum from purcell. Both need a cell sized for the reddest measured wavelength; see the padding_nm and pml_nm parameters of __init__.

Examples

>>> from maxwelllink.cavity import NPoM
>>> cav = NPoM(resolution=5000.0)
>>> spectrum = cav.linear_spectrum(500.0, 900.0, units="nm", min_time=30.0)
>>> lam, scattering = spectrum["wavelength_nm"], spectrum["scattering"]
>>> enhancement = cav.purcell(500.0, 900.0, units="nm", min_time=30.0)
>>> purcell_factor = enhancement["purcell"]

__init__(radius_nm=RADIUS_NM, gap_nm=GAP_NM, spacer_index=SPACER_INDEX, film_nm=FILM_NM, omega_ref=REPORTED['gap_mode_nm'], units='nm', material=None, dimensions=CYLINDRICAL, resolution=None, pml_nm=None, padding_nm=None)[source]¶

Initialize the parameters of a gold nanoparticle-on-mirror cavity.

Parameters:

radius_nm (float, default: 20.0) – Radius (nm) of the gold nanosphere (40 nm diameter).
gap_nm (float, default: 1.0) – Thickness (nm) of the spacer between the particle and the mirror.
spacer_index (float, default: 1.4) – Refractive index of the spacer layer, which extends laterally across the whole cell as in the paper.
film_nm (float, default: 70.0) – Thickness (nm) of the gold mirror.
omega_ref (float, default: 660.0) – Reference frequency (or wavelength) in units, i.e. roughly where the gap plasmon is expected. It sets no length of the structure, only the default grid, padding, and boundary thickness.
units (str, default: "nm") – Units of omega_ref: “cm-1”, “eV”, “au”, “nm”, or “um”.
material (mp.Medium or None, optional) – Material of the particle and the mirror. Default: gold (meep.materials.Au).
dimensions (int, default: mxl.CYLINDRICAL) – mxl.CYLINDRICAL for the (r, z) half plane, where the cavity sets m = 0 (the sector holding the gap mode), or 3 for full 3D.
resolution (float or None, optional) – Meep resolution. Default: six pixels across the gap, and at least 20 pixels per reference wavelength in the spacer.
pml_nm (float or None, optional) – Boundary thickness in nm. Default: a quarter of the reference wavelength, sized for a far-field probe at omega_ref; a redder window needs more (see Notes).
padding_nm (float or None, optional) – Free space (nm) between the particle and the boundary layers. Default: 0.15 reference wavelengths, sized for a far-field probe at omega_ref; a redder window needs more (see Notes).

Notes

The default cell is not good enough for linear spectrum and purcell measurements over a wide wavelength range, especially for cylindrical cells.

### TOY MODEL RUNNING IN LOCAL MACHINES: 20-radius nm and 1 nm gap particle, 500-800 nm measurement window: NPoM(padding_nm=150.0, pml_nm=250.0), resolution 1000.

### PRACTICAL CALCULATIONS FOR NATURE 2016 PAPER: 20-radius nm and 1 nm gap particle, 500-800 nm measurement window: - Linear scattering spectrum: NPoM(padding_nm=300.0, pml_nm=300.0), resolution 4000. - Purcell factor: NPoM(padding_nm=500.0, pml_nm=700.0), resolution 4000.

For converged spectra, size the cell from the reddest wavelength lam_max of the window to be measured:

padding_nm >= 0.75 * lam_max - radius_nm pml_nm >= 0.9 * lam_max

Half of it is enough when linear_spectrum is only used for the resonance position and linewidth, while the full value is needed for purcell and for the long-wavelength tail of the scattering spectrum.

With a cell that is too small, the scattering resonance comes out redshifted and too broad, and the total Purcell factor rises with wavelength instead of decaying.

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

Local-dipole (Purcell) probe of the NPoM: a z-polarized dipole at the gap hotspot (the classical-emitter method of Chikkaraddy et al.).

The reference is the homogeneous spacer medium with its own closed collection box (the mirror is absent there, so an open-bottomed box would leak the downward radiation).

Same keys as DummyCavity.emission_setup.

Parameters:

offset_nm (sequence of three floats, default: (0, 0, 0)) – Displacement (nm) of the dipole from the gap hotspot.
component (Meep field component or None, optional) – Dipole orientation. Default: mp.Ez, along the gap field.

estimate_driver_count(region)[source]¶

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

The disk is a rectangle of the (r, z) half plane in cylindrical cells, and a cylinder in 3D.

Parameters:: region (mp.Cylinder) – 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()[source]¶

Far-field probe of the NPoM: the dark-field-type scattering measurement of Chikkaraddy et al., Nature 535, 127 (2016).

A grazing sheet of vertical current drives the gap mode. The reference run (the film and spacer, without the particle) records the incident fields subtracted at the collection surface.

All observables are normalized by the incident intensity at the hotspot. Same keys as DummyCavity.optical_setup.

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=None, hub=None, offset_nm=(0.0, 0.0, 0.0), width_nm=None, rescaling_factor=1.0, **susceptibility_kwargs)[source]¶

Create a disk of molecular medium inside the gap (grid-level coupling).

The disk fills the spacer thickness and is centered at the hotspot plus offset_nm.

Pass it to make_simulation via extra_geometry=[region].

Parameters:

epsilon (float or None, optional) – Background permittivity of the molecular medium. Default: that of the spacer the disk replaces (spacer_index ** 2).
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 disk center from the hotspot.
width_nm (float or None, optional) – Diameter (nm) of the disk. Default: twice the lateral radius sqrt(radius * gap) of the gap mode.
rescaling_factor (float, default: 1.0) – Rescaling factor of mp.MXLSocketSusceptibility.
**susceptibility_kwargs – Forwarded to mp.MXLSocketSusceptibility (e.g. real_field_only, timeout).

Return type:

mp.Cylinder

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:

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

class maxwelllink.cavity.PlasmonicRod[source]¶

Bases: DummyCavity

A gold-cylinder plasmonic cavity with a molecular side annulus.

Geometries adapted from: Brawley et al. Nat. Chem. 17, 439–447 (2025). https://doi.org/10.1038/s41557-024-01723-6

In 3D, one cylinder occupies a square, Bloch-periodic unit cell in the xy plane, with PML only along z. The cylindrical path is a rotationally symmetric, effective-radius approximation on the (r, z) half plane with radial and z-directed PML; it does not reproduce the square-periodic 3D boundary exactly. The transverse plasmon belongs to an m = +1 or m = -1 sector, rather than the z-polarized m = 0 sector used by NPoM.

Molecular matter occupies an annulus around the metal cylinder. Repeated calls to place_molecule() place localized molecules in this annulus in 3D. place_region() creates a continuous socket-susceptibility annulus in either 3D or cylindrical coordinates.

A localized off-axis molecule breaks rotational symmetry and cannot be represented by one cylindrical Fourier sector. Consequently, the cylindrical path supports the continuous annular region, while discrete annular molecules require the 3D path.

Examples

Continuous cylindrical molecular medium:

>>> from maxwelllink.cavity import PlasmonicRod
>>> cav = PlasmonicRod()
>>> region = cav.place_region(hub=hub, real_field_only=False)
>>> sim = cav.make_simulation(hub=hub, extra_geometry=[region])

Multiple localized molecules in the 3D unit cell:

>>> cav = PlasmonicRod(dimensions=3)
>>> molecules = [
...     cav.place_molecule(hub=hub, hotspot="x_plus"),
...     cav.place_molecule(hub=hub, hotspot="x_minus"),
... ]
>>> sim = cav.make_simulation(hub=hub, molecules=molecules)

__init__(radius_nm=RADIUS_NM, lattice_gap_nm=LATTICE_GAP_NM, rod_height_nm=ROD_HEIGHT_NM, mirror_nm=MIRROR_NM, substrate_nm=SUBSTRATE_NM, adhesion_nm=ADHESION_NM, film_nm=FILM_NM, air_nm=AIR_NM, annulus_width_nm=ANNULUS_WIDTH_NM, background_index=1.7, omega_ref=3550.0, units='cm-1', material=None, adhesion_material=None, substrate_material=None, dimensions=CYLINDRICAL, m=-1, polarization='y', source_amplitude=SOURCE_AMPLITUDE, resolution=RESOLUTION, top_pml_nm=TOP_PML_NM, bottom_pml_nm=BOTTOM_PML_NM, radial_padding_nm=RADIAL_PADDING_NM, radial_pml_nm=RADIAL_PML_NM, cell_radius_mode='equal-area', monitor_radius_nm=None)[source]¶

Initialize the plasmonic cylinder-on-mirror cavity.

Parameters:

radius_nm (float, default: 280.0) – Radius of the gold cylinder.
lattice_gap_nm (float, default: 500.0) – Edge-to-edge separation between neighboring cylinders. The 3D lattice period is 2 * radius_nm + lattice_gap_nm.
rod_height_nm (float, default: 100.0) – Height of the gold cylinder.
mirror_nm (float, default: 200.0) – Thickness of the bottom gold mirror.
substrate_nm (float, default: 40.0) – Thickness of the Al2O3 layer above the mirror.
adhesion_nm (float, default: 4.0) – Thickness of the Cr adhesion layer beneath the cylinder.
film_nm (float, default: 200.0) – Height of the dielectric film containing the cylinder. It must be thicker than rod_height_nm + adhesion_nm.
air_nm (float, default: 200.0) – Vacuum height between the film and the top PML.
annulus_width_nm (float, default: 50.0) – Default radial width of molecular matter around the cylinder.
background_index (float, default: 1.7) – Refractive index of the nonresonant film.
omega_ref (float, default: 3550.0) – Reference frequency (or wavelength) in units.
units (str, default: "cm-1") – Units of omega_ref: “cm-1”, “eV”, “au”, “nm”, or “um”.
material (mp.Medium or None, optional) – Cylinder and mirror material. Default: meep.materials.Au.
adhesion_material (mp.Medium or None, optional) – Adhesion material. Default: meep.materials.Cr.
substrate_material (mp.Medium or None, optional) – Substrate material. Default: meep.materials.Al2O3_aniso.
dimensions (int, default: mxl.CYLINDRICAL) – mxl.CYLINDRICAL for the (r, z) reduction or 3 for the full periodic unit cell.
m (int, default: -1) – Cylindrical azimuthal sector, +1 or -1. Ignored in 3D.
polarization ({"x", "y"}, default: "y") – Transverse incident polarization. The two choices are degenerate in the cylindrical geometry but select Ex or Ey in 3D.
source_amplitude (float, default: 1e2) – Gaussian probe amplitude used by linear_spectrum(). The large default follows the finite-temperature LAMMPS-water amplitude ladder and suppresses thermal-emission noise relative to the driven response. It can also be overridden for one measurement with linear_spectrum(..., source_amplitude=...).
resolution (float, default: 125.0) – Meep pixels per micrometer.
top_pml_nm (float) – Top and bottom z-directed PML thicknesses.
bottom_pml_nm (float) – Top and bottom z-directed PML thicknesses.
radial_padding_nm (float, default: 500.0) – Cylindrical clearance between the effective unit-cell radius and the radial PML.
radial_pml_nm (float, default: 800.0) – Cylindrical outer radial PML thickness.
cell_radius_mode ({"equal-area", "half-period", "manual"}) – Effective unit-cell radius used by the cylindrical flux monitor. "equal-area" preserves the area of the square 3D unit cell.
monitor_radius_nm (float or None, optional) – Effective cylindrical radius when cell_radius_mode="manual".

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)[source]¶: Reject the unvalidated local-dipole setup inherited from the base.

estimate_driver_count(region)[source]¶

Estimate the number of FDTD grid points in an annular region.

This geometric estimate is not the actual socket-driver count. The modified Meep susceptibility writes the authoritative count to its hub’s driver_count_file after the material grid is initialized.

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

Normal-incidence reflection probe used by linear_spectrum().

The reference is the empty cell. The full structure is backed by a thick gold mirror, so the returned loss/absorption spectrum is 1 - reflection, matching the reference simulations.

place_molecule(hub=None, driver=None, offset_nm=(0.0, 0.0, 0.0), size_nm=None, sigma_nm=None, hotspot=None, **molecule_kwargs)[source]¶

Create one localized molecule inside the 3D molecular annulus.

Call this method repeatedly, selecting a named cardinal hotspot and/or supplying offset_nm, to place multiple molecules. The defaults are one grid point for sigma and four grid points for the molecular box, which fit the reference 50 nm annulus at resolution 125.

Cylindrical cells cannot use this route because an off-axis localized molecule is not representable in one azimuthal Fourier sector. Use place_region() for cylindrical annular matter.

place_region(epsilon=None, hub=None, width_nm=None, rescaling_factor=1.0, **susceptibility_kwargs)[source]¶

Create a continuous molecular annulus around the metal cylinder.

The annulus extends from radius_nm to radius_nm + width_nm and vertically across the Cr-plus-cylinder height. Pass the returned object to make_simulation() as extra_geometry=[region]. The cavity inserts it before the metal geometry, whose precedence carves out the inner radius exactly.

Parameters:

epsilon (float or None, optional) – Background permittivity of the molecular medium. Default: background_index ** 2.
hub (SusceptibilitySocketHub or None, optional) – Socket hub of the grid-level route.
width_nm (float or None, optional) – Radial annulus width. Default: annulus_width_nm from the constructor.
rescaling_factor (float, default: 1.0) – Rescaling factor of mp.MXLSocketSusceptibility.
**susceptibility_kwargs – Forwarded to mp.MXLSocketSusceptibility, for example real_field_only=True.

Returns:

Molecular outer disk (a radial block in cylindrical coordinates, a cylinder in 3D); the metal geometry carves out its center during simulation assembly.

Return type:

mp.Block or mp.Cylinder

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)[source]¶: Reject Purcell calculations until a rod-specific setup is available.

sim_kwargs(extra_geometry=())[source]¶: Assemble geometry while preserving the molecular-annulus precedence.

summary()[source]¶: Return an accurate summary of the plasmonic reflection setup (MPI safe)

class maxwelllink.cavity.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.

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:

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

maxwelllink.cavity package¶

Submodules¶