maxwelllink.cavity.dummy_cavity module

class maxwelllink.cavity.dummy_cavity.DummyCavity

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)

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)

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