ceviche

When simulating waves with angled incidence in a periodic domain, standard periodic boundary conditions will cause discontinuities at the boundaries. To simulate a plane wave that correctly wraps around the boundary with a phase shift, use the bloch_phases argument in fdfd_hz.

To implement this, calculate the phase shift required for the $y$-direction based on the wave vector component $k_y$ and the total length of the domain $L_y$: $\text{phase} = k_y \times L_y$.

# ky is the y-component of the wave vector
# Ly is the total length of the simulation in the y direction
F_Bloch = fdfd_hz(omega, dL, eps_r, npml, bloch_phases=[0, ky * Ly])

# Solve with the Bloch-enabled object
Ex, Ey, Hz = F_Bloch.solve(source_angle)

A multi-frequency FDFD simulation requires defining both physical and numerical parameters. Key parameters include:

• omega: Central frequency (rad/s).
• omega_mod: Modulation frequency (rad/s).
• Nsb: Number of sidebands on each side of the central wavelength (total bands = 2*Nsb + 1).
• dl: Spatial resolution in meters.
• Npml: Number of pixels in the Perfectly Matched Layers (PML).
• delta: Modulation depth profile.
• phi: Modulation phase profile.

This recipe demonstrates a complete workflow:

1. Loading permittivity data.
2. Initializing the fdtd object.
3. Defining a Gaussian pulsed source.
4. Running measure_fields to get time-domain responses.
5. Using plot_spectral_power to analyze the results in the frequency domain.

from ceviche import fdtd
from ceviche.utils import measure_fields, plot_spectral_power
import autograd.numpy as np

# 1. Setup
F = fdtd(eps_r, dL=5e-8, npml=[20, 20, 0])
steps = 10000

# 2. Define Source (Gaussian pulse)
omega = 2 * np.pi * 3e8 / 2e-6
omega_sim = omega * F.dt
gaussian = lambda t: np.exp(-(t - 2000)**2 / 2 / 100**2) * np.cos(omega_sim * t)
source = lambda t: J_in * 5 * gaussian(t)

# 3. Simulate
measured = measure_fields(F, source, steps, J_outs)

# 4. Analyze
plot_spectral_power(measured, dt=F.dt, f_top=1e16)

Use aniplot to create an animation of the field evolution within the FDTD simulation. The num_panels argument determines how many time steps are shown in the animation.

from ceviche.utils import aniplot

# Animate the simulation over 10 time steps
aniplot(F_wg, source, steps, num_panels=10)

The measure_fields utility runs an FDTD simulation and records the field values at specific locations over a set number of time steps.

Arguments:

• F: An instance of the fdtd class.
• source: A function (or lambda) that defines the source term as a function of time t.
• steps: Total number of time steps to simulate.
• J_probes: A single array or a list of arrays representing the spatial distribution of the source/probes (e.g., current density J).

# For a single probe/source
measured_wg = measure_fields(F_wg, source, steps, J_wg)

# For multiple probes (e.g., multiple output ports)
measured = measure_fields(F, source, steps, J_outs)

To initialize a Finite-Difference Frequency-Domain (FDFD) simulation for the $H_z$ component, use the fdfd_hz function. You must provide the angular frequency, spatial resolution, permittivity distribution, and Perfectly Matched Layer (PML) configuration.

Parameters:

• omega: Angular frequency ($\omega$).
• dL: Spatial resolution (grid spacing in meters).
• eps_r: A 2D NumPy array representing the relative permittivity ($\epsilon_r$) of the grid.
• npml: A list/array defining the number of PML pixels in each direction (e.g., [40, 0] for 40 pixels in $x$ and 0 in $y$).
• bloch_phases (optional): A list of phases applied to the periodic boundaries to implement Bloch boundary conditions.

from ceviche import fdfd_hz

# Example setup
F = fdfd_hz(omega, dL, eps_r, npml)

Use ceviche.viz.real to visualize the real part of the electric field (Ez) profiles. This function accepts an outline parameter (usually the permittivity array epsr) to show the physical structure alongside the field distribution.

import ceviche.viz

# Visualize the Ez profile at the central frequency (index Nsb)
ceviche.viz.real(Ez[Nsb], outline=epsr, ax=ax[0], cbar=False)

# Visualize the Ez profile at the first sideband (index Nsb + 1)
ceviche.viz.real(Ez[Nsb + 1], outline=epsr, ax=ax[1], cbar=False)

Once an FDFD object is initialized, use the .solve() method to compute the electromagnetic fields. You must pass a source array that matches the grid shape of the simulation.

Returns: Returns a tuple of three arrays: (Ex, Ey, Hz) representing the electric field components and the magnetic field component.

# Solve for fields using a source array
Ex, Ey, Hz = F.solve(source)

To start a Finite-Difference Time-Domain (FDTD) simulation, use the fdtd class. You must provide a permittivity distribution (eps_r) and specify the spatial resolution (dL) and the number of pixels for the Perfectly Matched Layers (npml).

eps_r should be a 3D array of shape (Nx, Ny, Nz).

from ceviche import fdtd

# dL: spatial resolution in meters
# npml: list of PML pixel counts in each direction [x, y, z]
F = fdtd(eps_r, dL=dL, npml=[20, 20, 0])

To convert time-domain field measurements into the frequency domain, use get_spectrum() or the visualization utility plot_spectral_power().

• get_spectrum(series, dt=...): Returns the frequency axis and the spectral values.
• plot_spectral_power(series, dt=..., f_top=...): Plots the spectral power of a time-series signal. Use f_top to limit the frequency range shown in the plot.

from ceviche.utils import get_spectrum, plot_spectral_power

# Get frequency and spectrum data
freq, spect = get_spectrum(measured_wg, dt=F.dt)

# Plot spectral power up to a specific frequency
plot_spectral_power(measured_wg, dt=F.dt, f_top=15e14)