Functions

BLS signal calculation

The following functions provide different approaches to compute the BLS signal, either using the Green function formalism or the Reciprocity Theorem. Both give similar results and the reader is redirected to the source publications for further explanation:

Green function method:

Wojewoda et al., Physical Review B 110, 224428 (2024). DOI: 10.1103/PhysRevB.110.224428

Reciprocity Theorem method:

Krčma et al., Science Advances 11, eady8833 (2025). DOI: 10.1126/sciadv.ady8833

The Green function method (get_signal_GF_focal() function) takes into account more optical effects happening at the sample surface and can compute signal from below a multilayer material stack, while the Reciprocity Theorem method (get_signal_RT... functions) is more straightforward and computationally less expensive.

Currently, the fastest approach is via the Reciprocity Theorem with electric fields input in the reciprocal space (get_signal_RT_pupil()), which is the recommended approach for most cases. The other functions are suitable for comparison and validation purposes. The get_signal_... functions use the electic fields given by the respective method of the ObjectiveLens class, i.e. GetFocalField() or GetPupilField() for the electric field in the real or reciprocal space, respectively. (The correct space is also indicated by the suffix of the get_signal_... function name.)

SpinWaveToolkit.bls.get_signal_GF_focal(SweepBloch, KxKyBloch, Bloch, Exy, E, DF, PM, d, NA, Nq=30, source_layer_index=1, output_layer_index=0, wavelength=5.32e-07, collectionSpot=1e-06, focalLength=0.001, coherent_exc=False, output_analyzer='none', output_analyzer_angle_deg=0, full_output=False)

Compute Brillouin light scattering (BLS) spectrum using the Green function formalism.

Warning

This is an experimental function. Syntax and behavior may change in future releases. Please verify the results carefully.

Source paper: https://doi.org/10.1103/PhysRevB.110.224428

Parameters:

SweepBlochndarray

Sweep vector of the Bloch functions with shape (Nf,). Usually frequency of spin waves.

KxKyBlochtuple[ndarray]

(rad/m) Tuple of two vectors with shapes (Nkx,), (Nky,) containing the kx and ky coordinates of the Bloch function.

Blochndarray

Array with shape (3, Nf, Nkx, Nky) containing the Bloch function components (Mx, My, Mz) for each frequency and KxKy grid point.

Exytuple[ndarray]

(m ) XY grid for the electric field. Tuple of two vectors with shapes (Nx,), (Ny,) containing the X and Y coordinates of the electric field.

Endarray

(V/m) 3D array with shape (3, Ny, Nx) containing the X, Y, Z components of the electric field.

DFndarray

() vector of the complex dielectric functions for each material in the stack.

PMndarray

() vector of the complex permeability functions for each material in the stack.

dndarray

(m ) thickness of all layers in the stack excluding the superstrate and substrate. Usually just the thickness of the magnetic layer.

NAfloat

Numerical aperture of the optical system.

Nqint, optional

Number of points in the q-space grid. Default is 30.

source_layer_indexint, optional

Index of the source layer in the stack. Default is 1.

output_layer_indexint, optional

Index of the output layer in the stack. Default is 0.

wavelengthfloat, optional

(m ) wavelength of the light. Default is 532e-9.

collectionSpotfloat, optional

(m ) collection spot size - used here as the beam waist. Default is 1e-6.

focalLengthfloat, optional

(m ) focal length of the lens. Default is 1e-3.

coherent_excbool, optional

If True, calculates the coherent BLS signal (amplitudes sum first). If False (default), calculates the non-coherent/thermal BLS signal (intensities sum first).

output_analyzer{“none”, “linear”, “circular_r”, “circular_l”, “radial”, “azimuthal”} or callable(), optional

Output polarization analyzer applied in real space before the detector.

• "none" (default): no analyzer (keeps both Ex and Ey).

• "linear": linear analyzer at output_analyzer_angle_deg.

• "circular_r": right-circular analyzer.

• "circular_l": left-circular analyzer.

• "radial": spatially varying radial analyzer.

• "azimuthal": spatially varying azimuthal analyzer.

If a callable is provided, it must have signature f(x_scat, y_scat) -> (ax, ay) and return analyzer coefficients broadcastable to the shape of x_scat and y_scat (real space meshgrids - see Returns section).

output_analyzer_angle_degfloat, optional

(deg) angle of the “linear” output analyzer (counter-clockwise from x). Ignored for other analyzer types. Default is 0.

full_outputbool, optional

If True, returns additional intermediate results: polarizations with q-space grids and scattered electric field with real-space grids). Default is False.

Returns:

sigmandarray

() calculated BLS spectrum. 1D array with shape (Nf,).

Px, Py, Pzndarray

(V/m) induced polarization in the magnetic layer. Corresponds to P in eq. (3) in Wojewoda et al. PRB 110, 224428 (2024). Each array has shape (Nf, 2*Nq-1, 2*Nq-1).

Qx, Qyndarray

(rad/m) k-space grids for polarizations Px, Py, Pz. Each array has shape (2*Nq-1, 2*Nq-1).

Ex_scat, Ey_scatndarray

(V/m) scattered real-space electric field components before the analyzer. Each array has shape (Nf, 2*Nq-1, 2*Nq-1). Can be used for custom analyzer calculations and beam masking.

x_scat, y_scatndarray

(m ) real-space grids for the scattered electric field. Each array has shape (2*Nq-1, 2*Nq-1).

See also

get_signal_RT_focal, get_signal_RT_pupil

SpinWaveToolkit.bls.getBLSsignal(SweepBloch, KxKyBloch, Bloch, Exy, E, DF, PM, d, NA, Nq=30, source_layer_index=1, output_layer_index=0, wavelength=5.32e-07, collectionSpot=1e-06, focalLength=0.001)

Compute Brillouin light scattering (BLS) spectrum using the Green function formalism.

Deprecated since version 1.3: This function is deprecated and will be removed in SpinWaveToolkit v1.5. Please use get_signal_GF_focal() instead.

Source paper: https://doi.org/10.1103/PhysRevB.110.224428

Parameters:

SweepBlochndarray

Sweep vector of the Bloch functions with shape (Nf,). Usually frequency of spin waves.

KxKyBlochtuple[ndarray]

(rad/m) Tuple of two vectors with shapes (Nkx,), (Nky,) containing the kx and ky coordinates of the Bloch function.

Blochndarray

Array with shape (3, Nf, Nkx, Nky) containing the Bloch function components (Mx, My, Mz) for each frequency and KxKy grid point.

Exytuple[ndarray]

(m ) XY grid for the electric field. Tuple of two vectors with shapes (Nx,), (Ny,) containing the X and Y coordinates of the electric field.

Endarray

(V/m) 3D array with shape (3, Ny, Nx) containing the X, Y, Z components of the electric field.

DFndarray

() vector of the complex dielectric functions for each material in the stack.

PMndarray

() vector of the complex permeability functions for each material in the stack.

dndarray

(m ) thickness of all layers in the stack excluding the superstrate and substrate. Usually just the thickness of the magnetic layer.

NAfloat

Numerical aperture of the optical system.

Nqint, optional

Number of points in the q-space grid. Default is 30.

source_layer_indexint, optional

Index of the source layer in the stack. Default is 1.

output_layer_indexint, optional

Index of the output layer in the stack. Default is 0.

wavelengthfloat, optional

(m ) wavelength of the light. Default is 532e-9.

collectionSpotfloat, optional

(m ) collection spot size - used here as the beam waist. Default is 1e-6.

focalLengthfloat, optional

(m ) focal length of the lens. Default is 1e-3.

Returns:

ExSndarray

(V/m) scattered electric field in the X axis. 1D array with shape (Nf,) containing the scattered electric field in the X direction for each frequency in SweepBloch.

EySndarray

(V/m) scattered electric field in the Y axis. 1D array with shape (Nf,) containing the scattered electric field in the Y direction for each frequency in SweepBloch.

Px, Py, Pzndarray

(V/m) induced polarization in the magnetic layer. Corresponds to P in eq. (3) in Wojewoda et al. PRB 110, 224428 (2024). Each array has shape (Nf, 2*Nq-1, 2*Nq-1).

Qx, Qyndarray

(rad/m) k-space grids for polarizations Px, Py, Pz. Each array has shape (2*Nq-1, 2*Nq-1).

See also

get_signal_GF_focal

Replacement for this deprecated function.

get_signal_RT_focal, get_signal_RT_pupil

SpinWaveToolkit.bls.get_signal_RT_pupil(KxKy, Ei_fields, Ej_fields, Chi, coherent_exc=False, conv_method='fft')

Compute Brillouin light scattering (BLS) spectrum using the reciprocity theorem, starting directly from the electric fields in reciprocal (k) space.

The transfer function qmEiEj requires the convolution of the k-space fields: qmEiEj = FT(Ej) * FT(Ei).

Important

To maintain a valid physical representation of the convolution integral, the input k-space grid (KxKy) MUST be strictly equidistant.

Source paper: https://doi.org/10.1126/sciadv.ady8833

Parameters:

KxKylist[ndarray]

(rad/m) list of two 1D arrays (kx, ky) with shapes (Nkx,) and (Nky,) containing the reciprocal space coordinates. Must be a uniform/equidistant grid.

Ei_fieldslist[ndarray]

(V/m) list of the three reciprocal pupil field components [Ekx, Eky, Ekz] corresponding to the driving field E_dr (incident laser). Each must have shape (Nkx, Nky).

Ej_fieldslist[ndarray]

(V/m) list of the three reciprocal pupil field components [Ekx, Eky, Ekz] corresponding to the virtual field E_v (detector side). Each must have shape (Nkx, Nky).

Chindarray

() dynamic magneto-optic susceptibility tensor with shape (3, 3, Nf, Nkx, Nky), containing the tensor components Chi_ij for each frequency and k-space grid point.

coherent_excbool, optional

If True, calculates the coherent BLS signal (amplitudes sum first). If False (default), calculates the non-coherent/thermal BLS signal (intensities sum first).

conv_method{“fft”, “direct”}, optional

The computational method used to perform the 2D convolution.

• “fft” (default): Uses scipy.signal.fftconvolve() (Convolution Theorem). Scales as O(N log N). Highly recommended for standard or large grids.

• “direct”: Uses scipy.signal.convolve2d() (Sliding window sum). Scales as O(N^2). Exceptionally slow for large arrays, but provided as an alternative for testing or very small grids.

Returns:

sigmandarray

() calculated BLS spectrum. 1D array with shape (Nf,).

qmEiEjndarray

() transfer function of the system. Array with shape (3, 3, Nkx, Nky). Uses the same coordinates as the electric fields and susceptibility tensor (KxKy).

See also

get_signal_RT_focal, get_signal_GF_focal

SpinWaveToolkit.bls.get_signal_RT_focal(Exy, Ei_fields, Ej_fields, KxKyChi, Chi, coherent_exc=False)

Compute Brillouin light scattering (BLS) spectrum using the reciprocity theorem.

Source paper: https://doi.org/10.1126/sciadv.ady8833

Parameters:

Exylist[ndarray]

(m ) XY grid for the electric field. List of two 1D arrays (x, y) with shapes (Nx,) and (Ny,) containing the spatial coordinates of the electric field grid.

Ei_fieldslist[ndarray]

(V/m) list of the three spatial components [Ex, Ey, Ez] of the focal driving electric field E_dr (incident laser). Each component must have shape (Nx, Ny).

Ej_fieldslist[ndarray]

(V/m) list of the three spatial components [Ex, Ey, Ez] of the focal virtual electric field E_v (detector side). Each component must have shape (Nx, Ny).

KxKyChilist[ndarray]

(rad/m) list of two 1D arrays (kx, ky) with shapes (Nkx,) and (Nky,) containing the reciprocal space coordinates of the magneto-optic susceptibility/Bloch function.

Chindarray

() dynamic magneto-optic susceptibility tensor. Must have shape (3, 3, Nf, Nkx, Nky) containing the tensor components Chi_ij for each frequency and k-space grid point.

coherent_excbool, optional

If True, calculates the coherent BLS signal (amplitudes sum first). If False (default), calculates the non-coherent/thermal BLS signal (intensities sum first).

Returns:

sigmandarray

() calculated BLS spectrum. 1D array with shape (Nf,).

qmEiEjndarray

() transfer function of the system. Array with shape (3, 3, Nkx, Nky). Uses the same coordinates as the susceptibility tensor (KxKyChi).

See also

get_signal_RT_pupil, get_signal_GF_focal

SpinWaveToolkit.bls.get_signal_RT_focal_3d(Exy, Ei_fields, Ej_fields, KxKyChi, Chi, coherent_exc=False)

Compute Brillouin light scattering (BLS) spectrum using the reciprocity theorem, evaluating signal contribution from multiple depths.

Warning

This is an experimental function. Syntax and behavior may change in future releases. Please verify the results carefully.

Source paper: https://doi.org/10.1126/sciadv.ady8833

Parameters:

Exylist[ndarray]

(m ) XY grid for the electric field. List of two 1D arrays (x, y) with shapes (Nx,) and (Ny,) containing the spatial coordinates of the electric field grid.

Ei_fieldslist[ndarray]

(V/m) list of the three spatial components [Ex, Ey, Ez] of the driving electric field E_dr (incident laser). Each component must have shape (Nx, Ny) for a single layer or (Nx, Ny, Nz) for multiple depths.

Ej_fieldslist[ndarray]

(V/m) list of the three spatial components [Ex, Ey, Ez] of the virtual electric field E_v (detector side). Each component must have shape (Nx, Ny) for a single layer or (Nx, Ny, Nz) for multiple depths.

KxKyChilist[ndarray]

(rad/m) list of two 1D arrays (kx, ky) with shapes (Nkx,) and (Nky,) containing the reciprocal space coordinates of the Bloch function.

Chindarray

() dynamic magneto-optic susceptibility tensor with shape (Nz, 3, 3, Nf, Nkx, Nky). If inputs are 2D (Nz=1), the first dimension can be omitted resulting in shape (3, 3, Nf, Nkx, Nky), which will be reshaped automatically.

coherent_excbool, optional

If True, calculates the coherent BLS signal (amplitudes sum first). If False (default), calculates the non-coherent/thermal BLS signal (intensities sum first).

Returns:

sigmandarray

() calculated BLS spectrum. 1D array with shape (Nf,).

qmEiEjndarray

() transfer function of the system. Array with shape (3, 3, Nkx, Nky, Nz). Uses the same coordinates as the susceptibility tensor (KxKyChi).

See also

get_signal_RT_focal

A similar function without z-resolution.

get_signal_RT_pupil, get_signal_GF_focal

Helper functions

Functions used internally for the BLS signal calculations, especially using the Green function method, but may also be useful for other purposes.

SpinWaveToolkit.bls.fresnel_coefficients(lambda_, DF, PM, d, source_layer_index, output_layer_index)

Create functions, htp and hts, that compute the Fresnel transmission coefficients for p- and s-polarized light, respectively, for a given lateral wavevector q.

Parameters:

lambda_float

(m ) wavelength of the calculated light.

DFarray_like

() array of dielectric functions (complex) for each layer, ordered from top (superstrate) downward.

PMarray_like

() array of relative permeabilities for each layer (typically ones).

darray_like

(m ) array of thicknesses for the layers between the superstrate and substrate. Length should be len(DF) - 2.

source_layer_indexint

0-indexed index of the layer where the source (induced polarization) is located.

output_layer_indexint

0-indexed index of the layer where the output is desired.

Returns:

htpfunction

A function that computes the p-polarized Fresnel transmission coefficients for given q.

htsfunction

A function that computes the s-polarized Fresnel transmission coefficients for given q.

Notes

The returned functions htp and hts take single argument q, which can be a float or ndarray in units rad/m. The shape of their output depends on the shape of q and the chosen output_layer_index:

• if 0 or N-1 (top or bottom layer), output shape is (2, ...) where ... is the shape of q,

• elsewhere (any interior layer), output shape is (2, 2, ...).

SpinWaveToolkit.bls.sph_green_function(Kx, Ky, DFMagLayer, wavelength, tp, ts)

Compute the spherical Green’s functions for p- and s-polarized fields.

Parameters:

Kx, Kyndarray

(rad/m) lateral wavevector components.

DFMagLayerfloat

() dielectric function (permitivity) of the magnetic layer.

wavelengthfloat

(m ) wavelength of the light.

tp, tslist or array_like

Fresnel coefficients for p- and s-polarization, respectively. Each is expected to have two elements (e.g. tp[0] and tp[1]).

Returns:

pGFlist[list]

A 3×2 list containing the p-polarized Green’s function components.

sGFlist[list]

A 3×2 list containing the s-polarized Green’s function components.