fields

Functions related to fields in the FMM algorithm.

Copyright (c) Meta Platforms, Inc. and affiliates.

fmmax.fields.amplitude_poynting_flux(forward_amplitude: Array, backward_amplitude: Array, layer_solve_result: LayerSolveResult) → Tuple[Array, Array]

Returns total Poynting flux for forward and backward eigenmodes.

This function decomposes the total field into components associated with the forward and backward amplitudes, and returns the time-average flux in each order for these two components. The calculation follows section 5.1 of [2012 Liu].

In the general case, a forward eigenmode may actually have negative Poynting flux, and therefore the quantities computed by this function should not be interpreted as the total forward and backward flux, but only the total flux associated with the forward and backward eigenmodes.

If the total forward and backward flux is desired, directional_poynting_flux should be used instead. This function should only be used in the specific case where the flux associated with the forward and backward eigenmodes is needed.

Parameters:

• forward_amplitude – The amplitude of the forward eigenmodes, with a trailing batch dimension.

• backward_amplitude – The amplitude of the backward eigenmodes, at the same location in space as the forward_amplitude.

• layer_solve_result – The results of the layer eigensolve.

Returns:

The Poynting flux associated with the forward and backward eigenmodes.

fmmax.fields.amplitudes_interior(s_matrix_before: ScatteringMatrix, s_matrix_after: ScatteringMatrix, forward_amplitude_0_start: Array, backward_amplitude_N_end: Array) → Tuple[Array, Array]

Computes the wave amplitudes at an interior layer within a stack.

The calculation is for a batch of amplitudes, with the batch axis being the final axis. There can also be leading batch axes. Accordingly, amplitudes should have shape (…, 2 * num_terms, num_amplitudes). The trailing batch dimension is preferred because it allows matrix-matrix multiplication instead of batched matrix-vector multiplication.

Parameters:

• s_matrix_before – The scattering matrix for the substack before the layer.

• s_matrix_after – The scattering matrix for the substack after the layer.

• forward_amplitude_0_start – The forward-propagating wave amplitude at the start of the first layer of the stack.

• backward_amplitude_N_end – The backward-propagating wave amplitude at the end of the last layer of the stack.

Returns:

The forward- and backward-propagating wave amplitude in the layer, defined at layer start and end, respectively.

fmmax.fields.colocate_amplitudes(forward_amplitude_start: Array, backward_amplitude_end: Array, z_offset: Array, layer_solve_result: LayerSolveResult, layer_thickness: Array) → Tuple[Array, Array]

Compute the forward- and backward-propagating wave amplitudes at z_offset.

The calculation is for a batch of amplitudes, with the batch dimension being final dimension.

Parameters:

• forward_amplitude_start – The amplitude of the forward eigenmodes at the start of the layer, with a trailing batch dimension.

• backward_amplitude_end – The amplitude of the backward eigenmodes at the end of the layer.

• z_offset – The location where the colocated amplitudes are sought, as an offset from the start of the layer.

• layer_solve_result – The result of the layer eigensolve.

• layer_thickness – The thickness of the layer.

Returns:

The forward- and backward-propagating wave amplitudes at z.

fmmax.fields.directional_poynting_flux(forward_amplitude: Array, backward_amplitude: Array, layer_solve_result: LayerSolveResult) → Tuple[Array, Array]

Returns total forward and backward Poynting flux.

This function decomposes the total field into components resulting from the the eigenmodes with positive and negative Poynting flux, and returns the time-average flux in each order for these two components. The calculation follows section 5.1 of [2012 Liu].

In the general case, a forward eigenmode may actually have negative Poynting flux, and so e.g. it may occur that a one-hot forward amplitude vector yields zero forward flux and nonzero backward flux.

If the flux associated with the forward and backward eigenmodes is desired, amplitude_poynting_flux should be used instead. This function serves the more typical case where the total forward flux and total backward flux is desired.

Parameters:

• forward_amplitude – The amplitude of the forward eigenmodes, with a trailing batch dimension.

• backward_amplitude – The amplitude of the backward eigenmodes, at the same location in space as the forward_amplitude.

• layer_solve_result – The results of the layer eigensolve.

Returns:

The Poynting flux associated with the forward and backward eigenmodes.

fmmax.fields.eigenmode_poynting_flux(layer_solve_result: LayerSolveResult) → Array

Returns the total Poynting flux for each eigenmode.

The result is equivalent to summing over the orders of the flux calculated by amplitude_poynting_flux, if the calculation is done for each eigenmode with a one-hot forward amplitude vector.

Parameters:

layer_solve_result – The results of the layer eigensolve.

Returns:

The per-eigenmode Poynting flux, with the same shape as the eigenvalues.

fmmax.fields.field_conversion_matrix(layer_solve_result: LayerSolveResult) → Array

Returns the matrix which converts wave amplitudes to transverse fields.

fmmax.fields.fields_from_wave_amplitudes(forward_amplitude: Array, backward_amplitude: Array, layer_solve_result: LayerSolveResult) → Tuple[Tuple[Array, Array, Array], Tuple[Array, Array, Array]]

Computes the electric and magnetic fields inside a layer.

The calculation is for a batch of amplitudes, with the batch axis being the final axis. There can also be leading batch axes. Accordingly, amplitudes should have shape (…, 2 * num_terms, num_amplitudes). The trailing batch dimension is preferred because it allows matrix-matrix multiplication instead of batched matrix-vector multiplication.

Parameters:

• forward_amplitude – The amplitude of the forward-propagating waves.

• backward_amplitude – The amplitude of the backward-propagating waves, at the same location in space as the forward_amplitude.

• layer_solve_result – The results of the layer eigensolve.

Returns:

The electric and magnetic fields, ((ex, ey, ez), (hx, hy, hz)).

fmmax.fields.fields_on_coordinates(electric_field: Tuple[Array, Array, Array], magnetic_field: Tuple[Array, Array, Array], layer_solve_result: LayerSolveResult, x: Array, y: Array) → Tuple[Tuple[Array, Array, Array], Tuple[Array, Array, Array], Tuple[Array, Array]]

Computes the fields at specified coordinates.

The calculation is for a batch of fields, with the batch axis being the final axis. There can also be leading batch axes. Accordingly, fields should have shape (…, 2 * num_terms, num_amplitudes). The trailing batch dimension is preferred because it allows matrix-matrix multiplication instead of batched matrix-vector multiplication.

Parameters:

• electric_field – (ex, ey, ez) electric field Fourier amplitudes.

• magnetic_field – (hx, hy, hz) magnetic field Fourier amplitudes.

• layer_solve_result – The results of the layer eigensolve.

• x – The x-coordinates where the fields are sought.

• y – The y-coordinates where the fields are sought, with shape matching that of x.

Returns:

The electric field (ex, ey, ez), magnetic field (hx, hy, hz), and the grid coordinates (x, y). The field arrays each have shape batch_shape + coordinates_shape + (num_amplitudes).

fmmax.fields.fields_on_grid(electric_field: Tuple[Array, Array, Array], magnetic_field: Tuple[Array, Array, Array], layer_solve_result: LayerSolveResult, shape: Tuple[int, int], num_unit_cells: Tuple[int, int]) → Tuple[Tuple[Array, Array, Array], Tuple[Array, Array, Array], Tuple[Array, Array]]

Transforms the fields from fourier representation to the grid.

The fields within an array of unit cells is returned, with the number of cells in each direction given by num_unit_cells.

The calculation is for a batch of fields, with the batch axis being the final axis. There can also be leading batch axes. Accordingly, fields should have shape (…, 2 * num_terms, num_amplitudes). The trailing batch dimension is preferred because it allows matrix-matrix multiplication instead of batched matrix-vector multiplication.

Parameters:

• electric_field – (ex, ey, ez) electric field Fourier amplitudes.

• magnetic_field – (hx, hy, hz) magnetic field Fourier amplitudes.

• layer_solve_result – The results of the layer eigensolve.

• shape – The shape of the grid.

• num_unit_cells – The number of unit cells along each direction.

Returns:

The electric field (ex, ey, ez), magnetic field (hx, hy, hz), and the grid coordinates (x, y).

fmmax.fields.layer_fields_3d(forward_amplitude_start: Array, backward_amplitude_end: Array, layer_solve_result: LayerSolveResult, layer_thickness: Array, layer_znum: int, grid_shape: Tuple[int, int], num_unit_cells: Tuple[int, int]) → Tuple[Array, Array, Tuple[Array, Array, Array]]

Computes the three-dimensional fields in a layer on the real-space grid.

Parameters:

• forward_amplitude_start – The forward-going wave amplitudes, defined at the start of the layer.

• backward_amplitude_end – The backward-going wave amplitudes, defined at the end of the layer.

• layer_solve_result – The results of the layer eigensolve.

• layer_thickness – The layer thickness.

• layer_znum – The number of gridpoints in the z-direction for the layer.

• grid_shape – The shape of the xy real-space grid.

• num_unit_cells – The number of unit cells along each direction.

Returns:

The electric and magnetic fields and grid coordinates, (ef, hf, (x, y, z)).

fmmax.fields.layer_fields_3d_on_coordinates(forward_amplitude_start: Array, backward_amplitude_end: Array, layer_solve_result: LayerSolveResult, layer_thickness: Array, layer_znum: int, x: Array, y: Array) → Tuple[Array, Array, Tuple[Array, Array, Array]]

Computes the three-dimensional fields in a layer at specified coordinates

This function may be significantly faster than layer_fields_3d in cases where fields in the full simulation domain are not required.

Parameters:

• forward_amplitude_start – The forward-going wave amplitudes, defined at the start of the layer.

• backward_amplitude_end – The backward-going wave amplitudes, defined at the end of the layer.

• layer_solve_result – The results of the layer eigensolve.

• layer_thickness – The layer thickness.

• layer_znum – The number of gridpoints in the z-direction for the layer.

• x – The x-coordinates where the fields are sought.

• y – The y-coordinates where the fields are sought, with shape matching that of x.

Returns:

The electric and magnetic fields and grid coordinates, (ef, hf, (x, y, z)).

fmmax.fields.propagate_amplitude(amplitude: Array, distance: Array, layer_solve_result: LayerSolveResult) → Array

Propagates waves with the given amplitude by distance.

The propagation is along the wave direction, i.e. when distance is positive, amplitudes for forward-propagating waves are those associated with a positive shift along the z-axis, while the reverse is true for backward-propagating wave amplitudes.

Parameters:

• amplitude – The amplitudes to be propagated, with a trailing batch dimension.

• distance – The distance to be propagated.

• layer_solve_result – The result of the layer eigensolve.

Returns:

The propagated amplitudes.

fmmax.fields.stack_amplitudes_interior(s_matrices_interior: Tuple[Tuple[ScatteringMatrix, ScatteringMatrix], ...], forward_amplitude_0_start: Array, backward_amplitude_N_end: Array) → Tuple[Tuple[Array, Array], ...]

Computes the wave amplitudes at interior layers within a stack.

The calculation is for a batch of amplitudes, with the batch axis being the final axis. There can also be leading batch axes. Accordingly, amplitudes should have shape (…, 2 * num_terms, num_amplitudes). The trailing batch dimension is preferred because it allows matrix-matrix multiplication instead of batched matrix-vector multiplication.

Parameters:

• s_matrices_interior – The scattering matrices for the substacks before and after each layer, as computed by stack_s_matrices_interior.

• forward_amplitude_0_start – The forward-propagating wave amplitude at the start of the first layer of the stack.

• backward_amplitude_N_end – The backward-propagating wave amplitude at the end of the last layer of the stack.

Returns:

The forward- and backward-propagating wave amplitude for each layer, defined at the start and end of each layer, respectively.

fmmax.fields.stack_amplitudes_interior_with_source(s_matrices_interior_before_source: Tuple[Tuple[ScatteringMatrix, ScatteringMatrix], ...], s_matrices_interior_after_source: Tuple[Tuple[ScatteringMatrix, ScatteringMatrix], ...], backward_amplitude_before_end: Array, forward_amplitude_after_start: Array) → Tuple[Tuple[Array, Array], ...]

Computes the wave amplitudes in the case of an internal source.

Parameters:

• s_matrices_interior_before_source – The interior scattering matrices for the layer substrack before the source, as computed by stack_s_matrices_interior.

• s_matrices_interior_after_source – The interior scattering matrices for the layer substack after the source.

• backward_amplitude_before_end – The backward-going wave amplitude at the end of the layer before the source.

• forward_amplitude_after_start – The forward-going wave amplitude at the start of the layer after the source.

Returns:

The forward- and backward-propagating wave amplitude for each layer, defined at the start and end of each layer, respectively.

fmmax.fields.stack_fields_3d(amplitudes_interior: Sequence[Tuple[Array, Array]], layer_solve_results: Sequence[LayerSolveResult], layer_thicknesses: Sequence[Array], layer_znum: Sequence[int], grid_shape: Tuple[int, int], num_unit_cells: Tuple[int, int]) → Tuple[Array, Array, Tuple[Array, Array, Array]]

Computes the three-dimensional fields in a stack on the real-space grid.

Parameters:

• amplitudes_interior – The forward- and backward-propagating wave amplitude for each layer, defined at the start and end of each layer, respectively.

• layer_solve_results – The results of the layer eigensolve for each layer.

• layer_thicknesses – The thickness of each layer.

• layer_znum – The number of gridpoints in the z-direction for each layer.

• grid_shape – The shape of the xy real-space grid.

• num_unit_cells – The number of unit cells along each direction.

Returns:

The electric and magnetic fields and grid coordinates, (ef, hf, (x, y, z)).

fmmax.fields.stack_fields_3d_auto_grid(amplitudes_interior: Sequence[Tuple[Array, Array]], layer_solve_results: Sequence[LayerSolveResult], layer_thicknesses: Sequence[Array], grid_spacing: float, num_unit_cells: Tuple[int, int]) → Tuple[Array, Array, Tuple[Array, Array, Array]]

Computes the three-dimensional fields in a stack on the real-space grid.

The grid is automatically determined from the layer dimensions and the resolution.

Parameters:

• amplitudes_interior – The forward- and backward-propagating wave amplitude for each layer, defined at the start and end of each layer, respectively.

• layer_solve_results – The results of the layer eigensolve for each layer.

• layer_thicknesses – The thickness of each layer.

• grid_spacing – The approximate spacing of gridpoints on which the field is computed. The actual grid spacing is modified to align with the layer and unit cell boundaries.

• num_unit_cells – The number of unit cells along each direction.

Returns:

The electric and magnetic fields and grid coordinates, (ef, hf, (x, y, z)).

fmmax.fields.stack_fields_3d_on_coordinates(amplitudes_interior: Sequence[Tuple[Array, Array]], layer_solve_results: Sequence[LayerSolveResult], layer_thicknesses: Sequence[Array], layer_znum: Sequence[int], x: Array, y: Array) → Tuple[Array, Array, Tuple[Array, Array, Array]]

Computes the three-dimensional fields in a stack at specified coordinates.

This function may be significantly faster than stack_fields_3d in cases where fields in the full simulation domain are not required.

Parameters:

• amplitudes_interior – The forward- and backward-propagating wave amplitude for each layer, defined at the start and end of each layer, respectively.

• layer_solve_results – The results of the layer eigensolve for each layer.

• layer_thicknesses – The thickness of each layer.

• layer_znum – The number of gridpoints in the z-direction for each layer.

• x – The x-coordinates where the fields are sought.

• y – The y-coordinates where the fields are sought, with shape matching that of x.

Returns:

The electric and magnetic fields and grid coordinates, (ef, hf, (x, y, z)).