fdtd

https://fdtd.readthedocs.io/en/latest
Admin
A 3D electromagnetic FDTD simulator written in Python with an optional PyTorch backend for GPU...
Tokens:64,484
Snippets:231
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Import fdtd Library

Source: https://fdtd.readthedocs.io/en/latest/examples/00-quick-start

Demonstrates the standard way to import the fdtd library for use in Python scripts. This is the first step before utilizing any of its functionalities.

```Python
import fdtd
```

--------------------------------

### Display Grid Summary

Source: https://fdtd.readthedocs.io/en/latest/examples/00-quick-start

Prints a detailed summary of the simulation grid, including its shape, spacing, Courant number, and configurations for sources, detectors, boundary conditions (PML), and objects. This helps in understanding the simulation setup.

```python
print(grid)
```

--------------------------------

### Run Simulation

Source: https://fdtd.readthedocs.io/en/latest/examples/00-quick-start

Executes the FDTD simulation for a specified duration. The `total_time` can be provided as an integer representing time steps or a float representing seconds. A progress bar is shown by default.

```APIDOC
grid.run(total_time: Number, progress_bar: bool = True)

  Parameters:
    total_time: The total simulation time, specified as an integer (number of time steps) or a float (in seconds).
    progress_bar: A boolean flag to display a progress bar during the simulation (defaults to True).

  Example:
    grid.run(total_time=100)
```

--------------------------------

### Create FDTD Grid Instance

Source: https://fdtd.readthedocs.io/en/latest/examples/00-quick-start

Instantiates the `fdtd.Grid` object with specified dimensions, representing a 2D simulation space. The output shows the effective grid dimensions and the calculated Courant number.

```Python
grid = fdtd.Grid(
    shape = (25e-6, 15e-6, 1), # 25um x 15um x 1 (grid_spacing) --> 2D FDTD
)

print(grid)
```

--------------------------------

### Set FDTD Backend

Source: https://fdtd.readthedocs.io/en/latest/examples/00-quick-start

Allows setting the computational backend for the fdtd library. Options include NumPy and various PyTorch configurations (CPU/GPU, float32/float64). The choice impacts performance and hardware utilization, with 'numpy' being a common default for CPU calculations.

```Python
fdtd.set_backend("numpy")
```

--------------------------------

### Create FDTD Grid

Source: https://fdtd.readthedocs.io/en/latest/examples/01-basic-example

Initializes the FDTD simulation grid with specified dimensions, grid spacing, permittivity, and permeability.

```python
grid = fdtd.Grid(
    (2.5e-5, 1.5e-5, 1),
    grid_spacing=0.1 * WAVELENGTH,
    permittivity=1.0,
    permeability=1.0,
)
```

--------------------------------

### Install fdtd Library

Source: https://fdtd.readthedocs.io/en/latest/index

Installs the fdtd library using pip. This command requires a Python environment with pip installed and is typically run from the terminal.

```shell
pip install fdtd
```

--------------------------------

### Set FDTD Backend

Source: https://fdtd.readthedocs.io/en/latest/examples/01-basic-example

Configures the backend for the FDTD library. This example sets the backend to 'numpy'.

```python
fdtd.set_backend("numpy")
```

--------------------------------

### Visualize Grid

Source: https://fdtd.readthedocs.io/en/latest/examples/00-quick-start

Generates a visualization of the simulation grid, including objects, sources, and detectors. It allows specifying a plane (x, y, or z) for visualization and customizing colors. Matplotlib integration is supported.

```APIDOC
grid.visualize(
    grid,
    x=None,
    y=None,
    z=None,
    cmap="Blues",
    pbcolor="C3",
    pmlcolor=(0, 0, 0, 0.1),
    objcolor=(1, 0, 0, 0.1),
    srccolor="C0",
    detcolor="C2",
    show=True,
)

  Parameters:
    grid: The grid object to visualize.
    x, y, z: Specify a plane for visualization by providing a coordinate value for x, y, or z.
    cmap: Colormap for the visualization (default: "Blues").
    pbcolor: Color for PML boundaries (default: "C3").
    pmlcolor: RGBA tuple for PML object color (default: (0, 0, 0, 0.1)).
    objcolor: RGBA tuple for general object color (default: (1, 0, 0, 0.1)).
    srccolor: Color for sources (default: "C0").
    detcolor: Color for detectors (default: "C2").
    show: If True, displays the plot immediately using matplotlib (default: True).

  Example:
    grid.visualize(z=0, show=False)
    import matplotlib.pyplot as plt
    plt.show()
```

--------------------------------

### Grid Initialization Example

Source: https://fdtd.readthedocs.io/en/latest/index

Demonstrates how to initialize an fdtd.Grid object. This example creates a 2D grid with specified dimensions, which internally translates to integer grid units based on the default grid_spacing.

```python
grid = fdtd.Grid(
    shape = (25e-6, 15e-6, 1), # 25um x 15um x 1 (grid_spacing) --> 2D FDTD
)
print(grid)
```

--------------------------------

### Python Imports for FDTD Simulation

Source: https://fdtd.readthedocs.io/en/latest/examples/01-basic-example

Imports necessary libraries for FDTD simulations, including the main fdtd library, backend utilities, and plotting tools from matplotlib.

```python
import matplotlib.pyplot as plt

import fdtd
import fdtd.backend as bd
```

--------------------------------

### Define and Place FDTD Object

Source: https://fdtd.readthedocs.io/en/latest/examples/00-quick-start

Demonstrates how to create an fdtd.Object with specified permittivity and assign it to a region of the FDTD grid. The object's dimensions (Nx, Ny, Nz) are derived from its placement, and it can be named for easy access.

```python
fdtd.Object(
    permittivity: Tensorlike,
    name: str = None
)
```

```python
grid[11:32, 30:84, 0] = fdtd.Object(permittivity=1.7**2, name="object")
```

```python
print(grid.object)
```

```python
grid[13e-6:18e-6, 5e-6:8e-6, 0] = fdtd.Object(permittivity=1.5**2)
```

```python
print(grid.objects)
```

--------------------------------

### Define FDTD Sources

Source: https://fdtd.readthedocs.io/en/latest/examples/01-basic-example

Adds electromagnetic sources to the simulation grid. This example includes a LineSource and a PointSource.

```python
grid[50:55, 70:75, 0] = fdtd.LineSource(
    period=WAVELENGTH / SPEED_LIGHT, name="linesource"
)
grid[100, 60, 0] = fdtd.PointSource(
    period=WAVELENGTH / SPEED_LIGHT, name="pointsource",
)
```

--------------------------------

### Run FDTD Simulation

Source: https://fdtd.readthedocs.io/en/latest/examples/01-basic-example

Executes the FDTD simulation for a specified number of time steps. The progress bar can be optionally disabled.

```python
grid.run(50, progress_bar=False)
```

--------------------------------

### Setup LineProfiler

Source: https://fdtd.readthedocs.io/en/latest/examples/04-performance-profiling

Initializes the LineProfiler and adds the `grid.update_E` method to it for detailed performance analysis. The profiler is then enabled.

```python
profiler = LineProfiler()
profiler.add_function(grid.update_E)
profiler.enable()
```

--------------------------------

### Visualize FDTD Grid State

Source: https://fdtd.readthedocs.io/en/latest/examples/01-basic-example

Provides a direct visualization of the FDTD grid's state, showing the distribution of materials and fields.

```python
plt.figure()
grid.visualize(z=0)
```

--------------------------------

### Define Simulation Constants

Source: https://fdtd.readthedocs.io/en/latest/examples/01-basic-example

Defines physical constants required for the simulation, such as wavelength and the speed of light.

```python
WAVELENGTH = 1550e-9
SPEED_LIGHT: float = 299_792_458.0  # [m/s] speed of light
```

--------------------------------

### Define FDTD Detectors

Source: https://fdtd.readthedocs.io/en/latest/examples/01-basic-example

Places detectors in the grid to record electromagnetic field values during the simulation.

```python
grid[12e-6, :, 0] = fdtd.LineDetector(name="detector")
```

--------------------------------

### Add FDTD Line Source

Source: https://fdtd.readthedocs.io/en/latest/examples/00-quick-start

Shows how to add an fdtd.LineSource to the FDTD grid. Sources define the electromagnetic wave excitation and are placed similarly to objects, with their size determined by grid slicing. They can be named for direct access.

```python
fdtd.LineSource(
    period: Number = 15, # timesteps or seconds
    amplitude: float = 1.0,
    phase_shift: float = 0.0,
    name: str = None,
)
```

```python
grid[7.5e-6:8.0e-6, 11.8e-6:13.0e-6, 0] = fdtd.LineSource(
    period = 1550e-9 / (3e8), name="source"
)
```

```python
print(grid.source)
```

--------------------------------

### Define FDTD Boundaries

Source: https://fdtd.readthedocs.io/en/latest/examples/01-basic-example

Applies boundary conditions to the FDTD grid. This example uses PML (Perfectly Matched Layer) for x and y boundaries and PeriodicBoundary for z boundaries.

```python
# grid[0, :, :] = fdtd.PeriodicBoundary(name="xbounds")
grid[0:10, :, :] = fdtd.PML(name="pml_xlow")
grid[-10:, :, :] = fdtd.PML(name="pml_xhigh")

# grid[:, 0, :] = fdtd.PeriodicBoundary(name="ybounds")
grid[:, 0:10, :] = fdtd.PML(name="pml_ylow")
grid[:, -10:, :] = fdtd.PML(name="pml_yhigh")

grid[:, :, 0] = fdtd.PeriodicBoundary(name="zbounds")
```

--------------------------------

### Import Libraries for FDTD Simulation

Source: https://fdtd.readthedocs.io/en/latest/examples/06-GRIN-medium-and-analysing-refraction

Imports necessary Python libraries for the FDTD simulation, including os for file operations, fdtd for the simulation engine, numpy for numerical operations, and matplotlib for plotting.

```python
import os
import fdtd
import numpy as np
import matplotlib.pyplot as plt
```

--------------------------------

### Run FDTD Simulation and Visualize Frames

Source: https://fdtd.readthedocs.io/en/latest/examples/06-GRIN-medium-and-analysing-refraction

This Python code demonstrates how to run an FDTD simulation step-by-step, visualize intermediate results, and save frames for later video generation. It includes dependencies like IPython.display for clearing output in notebooks and saving visualization frames.

```python
from IPython.display import clear_output  # only necessary in jupyter notebooks

for i in range(100):
    grid.step()  # running simulation 1 timestep a time and animating
    if i % 5 == 0:
        # saving frames during visualization
        grid.visualize(z=0, animate=True, index=i, save=True, folder=simfolder)
        plt.title(f"{i:3.0f}")
        clear_output(wait=True)  # only necessary in jupyter notebooks
grid.save_data()  # saving detector readings
```

--------------------------------

### Visualize FDTD Fields

Source: https://fdtd.readthedocs.io/en/latest/examples/01-basic-example

Generates plots of electromagnetic field components (Ex, Ey, Ez, Hx, Hy, Hz) across the simulation grid using matplotlib.

```python
fig, axes = plt.subplots(2, 3, squeeze=False)
titles = ["Ex: xy", "Ey: xy", "Ez: xy", "Hx: xy", "Hy: xy", "Hz: xy"]

fields = bd.stack(
    [
        grid.E[:, :, 0, 0],
        grid.E[:, :, 0, 1],
        grid.E[:, :, 0, 2],
        grid.H[:, :, 0, 0],
        grid.H[:, :, 0, 1],
        grid.H[:, :, 0, 2],
    ]
)

m = max(abs(fields.min().item()), abs(fields.max().item()))

for ax, field, title in zip(axes.ravel(), fields, titles):
    ax.set_axis_off()
    ax.set_title(title)
    ax.imshow(bd.numpy(field), vmin=-m, vmax=m, cmap="RdBu")

plt.show()
```

--------------------------------

### Define FDTD Objects

Source: https://fdtd.readthedocs.io/en/latest/examples/01-basic-example

Adds objects with specific material properties (permittivity, permeability) to the simulation grid.

```python
grid[11:32, 30:84, 0:1] = fdtd.AnisotropicObject(permittivity=2.5, name="object")
```

--------------------------------

### FDTD Grid Initialization

Source: https://fdtd.readthedocs.io/en/latest/examples/00-quick-start

Defines the simulation region and physical properties for FDTD calculations. The `Grid` class takes parameters like shape, grid spacing, permittivity, permeability, and Courant number. Shape can be specified in meters (floats) or grid units (integers). Grid spacing is crucial for stability and accuracy, recommended to be at least 10x smaller than the smallest wavelength. Permittivity and permeability can be scalars or arrays matching grid dimensions, supporting anisotropic materials.

```APIDOC
fdtd.Grid(
    shape: Tuple[Number, Number, Number],
    grid_spacing: float = 155e-9,
    permittivity: float = 1.0,
    permeability: float = 1.0,
    courant_number: float = None,
)

Parameters:
  shape: Tuple[Number, Number, Number]
    Defines the simulation region dimensions. If floats, specifies dimensions in meters. If integers, specifies dimensions in grid units.
  grid_spacing: float, optional
    The spacing between grid points in meters. Defaults to 155e-9.
  permittivity: float or array, optional
    The permittivity of the medium. Can be a scalar or an array matching grid dimensions (e.g., (Nx, Ny, Nz) or (Nx, Ny, Nz, 3) for anisotropic materials). Defaults to 1.0.
  permeability: float or array, optional
    The permeability of the medium. Can be a scalar or an array matching grid dimensions. Defaults to 1.0.
  courant_number: float, optional
    The Courant number, relating time step to grid spacing for stability. If None, it's automatically calculated based on the Courant-Friedrichs-Lewy condition (1 for 1D, 1/sqrt(2) for 2D, 1/sqrt(3) for 3D).

Notes:
  - Internally, permittivity and permeability are converted to their inverses and stored as arrays of shape (Nx, Ny, Nz, 3) for performance.
  - For stability, grid_spacing should be at least 10 times smaller than the smallest wavelength in the simulation.
  - The Courant number should generally not be changed from its default for stability reasons.
```

--------------------------------

### fdtd Backend Selection Overview

Source: https://fdtd.readthedocs.io/en/latest/_modules/fdtd/backend

Explains the purpose of the fdtd.backend module, detailing the available backends like 'numpy', 'torch', and 'torch.cuda'. It also discusses precision choices ('float32', 'float64') and provides an example of how to set the backend using `fdtd.set_backend()`.

```python
""" Selects the backend for the fdtd-package.

The `fdtd` library allows to choose a backend. The ``numpy`` backend is the
default one, but there are also several additional PyTorch backends:

    - ``numpy`` (defaults to float64 arrays)
    - ``torch`` (defaults to float64 tensors)
    - ``torch.float32``
    - ``torch.float64``
    - ``torch.cuda`` (defaults to float64 tensors)
    - ``torch.cuda.float32``
    - ``torch.cuda.float64``

For example, this is how to choose the \"torch\" backend: ::

    fdtd.set_backend(\"torch\")

In general, the ``numpy`` backend is preferred for standard CPU calculations
with \"float64\" precision. In general, ``float64`` precision is always
preferred over ``float32`` for FDTD simulations, however, ``float32`` might
give a significant performance boost.

The ``cuda`` backends are only available for computers with a GPU.

"""

```

--------------------------------

### Generate video from simulation frames

Source: https://fdtd.readthedocs.io/en/latest/examples/05-lenses-and-analysing-lensing-actions

Attempts to generate a video file from the saved simulation frames using ffmpeg. Includes error handling if ffmpeg is not installed.

```python
try:
    video_path = grid.generate_video(delete_frames=False)  # rendering video from saved frames
except:
    video_path = ""
    print("ffmpeg not installed?")
```

--------------------------------

### Initialize FDTD Grid and PML Boundaries

Source: https://fdtd.readthedocs.io/en/latest/examples/06-GRIN-medium-and-analysing-refraction

Initializes the FDTD simulation grid with specified dimensions and grid spacing. It then applies Perfect Matching Layers (PML) to the boundaries to absorb outgoing waves, preventing reflections. The simulation folder is initialized for saving data.

```python
grid = fdtd.Grid(shape=(9.3e-6, 15.5e-6, 1), grid_spacing=77.5e-9)
# x boundaries
grid[0:10, :, :] = fdtd.PML(name="pml_xlow")
grid[-10:, :, :] = fdtd.PML(name="pml_xhigh")
# y boundaries
grid[:, 0:10, :] = fdtd.PML(name="pml_ylow")
grid[:, -10:, :] = fdtd.PML(name="pml_yhigh")
simfolder = grid.save_simulation("GRIN")  # initializing environment to save simulation data
print(simfolder)
```

--------------------------------

### Configure Line Source for Simulation

Source: https://fdtd.readthedocs.io/en/latest/examples/06-GRIN-medium-and-analysing-refraction

Sets up a line source to emit light into the simulation domain. It uses a Hanning window pulse, specifies the frequency (derived from wavelength), and defines the pulse characteristics for the simulation.

```python
grid[3.1e-6, 1.5e-6:14e-6, 0] = fdtd.LineSource(period=1550e-9 / (3e8), name="source", pulse=True, cycle=3, hanning_dt=4e-15)
```

--------------------------------

### Display Generated Video

Source: https://fdtd.readthedocs.io/en/latest/examples/06-GRIN-medium-and-analysing-refraction

This snippet uses IPython.display.Video to embed and display the generated video within an interactive environment like a Jupyter notebook. It requires the video_path to be valid.

```python
if video_path:
    from IPython.display import Video
    display(Video(video_path, embed=True))
```

--------------------------------

### FDTD Grid and Object Setup

Source: https://fdtd.readthedocs.io/en/latest/examples/02-absorbing-object

Initializes the FDTD grid with specified dimensions and grid spacing. It configures sources, detectors, and boundary conditions using PML (Perfectly Matched Layer). An AbsorbingObject is then placed within the grid.

```python
# create FDTD Grid
grid = fdtd.Grid(
    (1.5e-5, 1.5e-5, 1),  # 2D grid
    grid_spacing=0.1 * WAVELENGTH,
    permittivity=2.5,  # same as object
)

# sources
grid[15, :] = fdtd.LineSource(period=WAVELENGTH / SPEED_LIGHT, name="source")

# detectors
grid[-15, :, 0] = fdtd.LineDetector(name="detector")

# x boundaries
# grid[0, :, :] = fdtd.PeriodicBoundary(name="xbounds")
grid[0:10, :, :] = fdtd.PML(name="pml_xlow")
grid[-10:, :, :] = fdtd.PML(name="pml_xhigh")

# y boundaries
# grid[:, 0, :] = fdtd.PeriodicBoundary(name="ybounds")
grid[:, 0:10, :] = fdtd.PML(name="pml_ylow")
grid[:, -10:, :] = fdtd.PML(name="pml_yhigh")

# The absorbing object fills the whole grid
grid[10:-10, 10:-10, :] = fdtd.AbsorbingObject(
    permittivity=2.5, conductivity=1e-6, name="absorbin_object"
)
```

--------------------------------

### Configure the simulation source

Source: https://fdtd.readthedocs.io/en/latest/examples/05-lenses-and-analysing-lensing-actions

Sets up a continuous line source for the simulation, specifying its position and frequency.

```python
grid[15, 50:150, 0] = fdtd.LineSource(period=1550e-9 / (3e8), name="source")
```

--------------------------------

### Add FDTD Line Detector

Source: https://fdtd.readthedocs.io/en/latest/examples/00-quick-start

Illustrates adding an fdtd.LineDetector to the simulation grid. Detectors are used to measure electromagnetic fields at specific locations. They are placed using grid slicing and can be named.

```python
fdtd.LineDetector(
    name=None
)
```

```python
grid[12e-6, :, 0] = fdtd.LineDetector(name="detector")
```

```python
print(grid.detector)
```

--------------------------------

### Initialize and configure the simulation grid

Source: https://fdtd.readthedocs.io/en/latest/examples/05-lenses-and-analysing-lensing-actions

Sets up the FDTD simulation grid with specified dimensions and applies PML boundary conditions. It also initializes a directory for saving simulation data.

```python
grid = fdtd.Grid(shape=(260, 15.5e-6, 1), grid_spacing=77.5e-9)
# x boundaries
grid[0:10, :, :] = fdtd.PML(name="pml_xlow")
grid[-10:, :, :] = fdtd.PML(name="pml_xhigh")
# y boundaries
grid[:, 0:10, :] = fdtd.PML(name="pml_ylow")
grid[:, -10:, :] = fdtd.PML(name="pml_yhigh")
simfolder = grid.save_simulation("Lenses")  # initializing environment to save simulation data
print(simfolder)
```

--------------------------------

### Add FDTD PML Boundaries

Source: https://fdtd.readthedocs.io/en/latest/examples/00-quick-start

Details the addition of Perfectly Matched Layer (PML) boundaries to the FDTD grid. PMLs are essential for absorbing outgoing waves and preventing reflections. They are applied to grid edges using slicing.

```python
fdtd.PML(
    a: float = 1e-8, # stability factor
    name: str = None
)
```

```python
# x boundaries
grid[0:10, :, :] = fdtd.PML(name="pml_xlow")
grid[-10:, :, :] = fdtd.PML(name="pml_xhigh")

# y boundaries
grid[:, 0:10, :] = fdtd.PML(name="pml_ylow")
grid[:, -10:, :] = fdtd.PML(name="pml_yhigh")
```

--------------------------------

### Generate Video from Simulation Frames

Source: https://fdtd.readthedocs.io/en/latest/examples/06-GRIN-medium-and-analysing-refraction

This Python code attempts to generate a video from simulation frames using the grid.generate_video method, which likely calls ffmpeg internally. It includes error handling for cases where ffmpeg might not be installed.

```python
try:
    video_path = grid.generate_video(delete_frames=False)  # rendering video from saved frames
except:
    video_path = ""
    print("ffmpeg not installed?")
```

--------------------------------

### FDTD Source Initialization and Update Methods

Source: https://fdtd.readthedocs.io/en/latest/fdtd

Documentation for FDTD source classes, including their constructors and methods for updating electric and magnetic fields. Covers LineSource, PlaneSource, and PointSource.

```APIDOC
class fdtd.sources.LineSource:
    """A source along a line in the FDTD grid"""
    __init__(period: Number = 15, amplitude: float = 1.0, phase_shift: float = 0.0, name: str | None = None, pulse: bool = False, cycle: int = 5, hanning_dt: float = 10.0):
        """Create a LineSource with a gaussian profile

        Parameters:
        period (Number): The period of the source. Can be specified as integer [timesteps] or as float [seconds].
        amplitude (float): The amplitude of the source in simulation units.
        phase_shift (float): The phase offset of the source.
        name (str | None): Optional name for the source.
        pulse (bool): Set True to use a Hanning window pulse instead of continuous wavefunction.
        cycle (int): Cycles for Hanning window pulse.
        hanning_dt (float): Timestep used for Hanning window pulse width (optional).
        """
        pass

    update_E():
        """Add the source to the electric field."""
        pass

    update_H():
        """Add the source to the magnetic field."""
        pass

class fdtd.sources.PlaneSource:
    """A source along a plane in the FDTD grid"""
    __init__(period: Number = 15, amplitude: float = 1.0, phase_shift: float = 0.0, name: str | None = None, polarization: str = 'z'):
        """Create a PlaneSource.

        Parameters:
        period (Number): The period of the source. Can be specified as integer [timesteps] or as float [seconds].
        amplitude (float): The amplitude of the source in simulation units.
        phase_shift (float): The phase offset of the source.
        name (str | None): Optional name for the source.
        polarization (str): Axis of E-field polarization ('x', 'y', or 'z').
        """
        pass

    update_E():
        """Add the source to the electric field."""
        pass

    update_H():
        """Add the source to the magnetic field."""
        pass

class fdtd.sources.PointSource:
    """A source placed at a single point (grid cell) in the grid"""
    __init__(period: Number = 15, amplitude: float = 1.0, phase_shift: float = 0.0, name: str | None = None, pulse: bool = False, cycle: int = 5, hanning_dt: float = 10.0):
        """Create a PointSource.

        Parameters:
        period (Number): The period of the source. Can be specified as integer [timesteps] or as float [seconds].
        amplitude (float): The electric field amplitude in simulation units.
        phase_shift (float): The phase offset of the source.
        name (str | None): Name of the source.
        pulse (bool): Set True to use a Hanning window pulse instead of continuous wavefunction.
        cycle (int): Cycles for Hanning window pulse.
        hanning_dt (float): Timestep used for Hanning window pulse width (optional).
        """
        pass

    update_E():
        """Add the source to the electric field."""
        pass

    update_H():
        """Add the source to the magnetic field."""
        pass
```

--------------------------------

### Create FDTD Grid

Source: https://fdtd.readthedocs.io/en/latest/examples/04-performance-profiling

Initializes the FDTD grid with specified dimensions, grid spacing, permittivity, and permeability. This sets up the computational domain for the simulation.

```python
N = 100

grid = fdtd.Grid(
    (N, N, N),
    grid_spacing=0.05 * WAVELENGTH,
    permittivity=1.0,
    permeability=1.0,
)
```

--------------------------------

### Import necessary libraries

Source: https://fdtd.readthedocs.io/en/latest/examples/05-lenses-and-analysing-lensing-actions

Imports the required Python libraries for the simulation, including os, fdtd, numpy, and matplotlib.pyplot.

```python
import os
import fdtd
import numpy as np
import matplotlib.pyplot as plt
```

--------------------------------

### Run Simulation

Source: https://fdtd.readthedocs.io/en/latest/examples/02-absorbing-object

Executes the FDTD simulation for a specified number of time steps. The progress bar is disabled for this example.

```python
grid.run(250, progress_bar=False)
```

--------------------------------

### Configure the simulation detector

Source: https://fdtd.readthedocs.io/en/latest/examples/05-lenses-and-analysing-lensing-actions

Sets up a BlockDetector to capture simulation data within a specified region of the grid.

```python
grid[80:200, 80:120, 0] = fdtd.BlockDetector(name="detector")
```

--------------------------------

### Backend Initialization and Availability Checks

Source: https://fdtd.readthedocs.io/en/latest/_modules/fdtd/backend

Code snippet demonstrating the initialization of PyTorch, setting default dtype and gradient status, and checking for PyTorch and CUDA availability. This section includes imports and conditional logic for backend support.

```python
# Numpy Backend
import numpy  # numpy has to be present
from functools import wraps

# used only by test runner.
# default must be idx 0.
backend_names = [
    dict(backends="numpy"),
    dict(backends="torch.float32"),
    dict(backends="torch.float64"),
    dict(backends="torch.cuda.float32"),
    dict(backends="torch.cuda.float64"),
]

numpy_float_dtypes = {
    getattr(numpy, "float_", numpy.float64),
    getattr(numpy, "float16", numpy.float64),
    getattr(numpy, "float32", numpy.float64),
    getattr(numpy, "float64", numpy.float64),
    getattr(numpy, "float128", numpy.float64),
}

# Torch Backends (and flags)
try:
    import torch

    torch.set_default_dtype(torch.float64)  # we need more precision for FDTD
    try:  # we don't need gradients (for now)
        torch._C.set_grad_enabled(False)  # type: ignore
    except AttributeError:
        torch._C._set_grad_enabled(False)
    TORCH_AVAILABLE = True
    TORCH_CUDA_AVAILABLE = torch.cuda.is_available()
except ImportError:
    TORCH_AVAILABLE = False
    TORCH_CUDA_AVAILABLE = False

```

--------------------------------

### Imports and Backend Setup

Source: https://fdtd.readthedocs.io/en/latest/examples/02-absorbing-object

Imports necessary libraries like matplotlib for plotting and the fdtd package. It also sets the computational backend for fdtd.

```python
import matplotlib.pyplot as plt

import fdtd
fdtd.set_backend("numpy")
```

--------------------------------

### np.pad with linear_ramp padding

Source: https://fdtd.readthedocs.io/en/latest/fdtd

Pads an array with a linear ramp. The ramp starts from the last value of the edge and ends at the specified `end_values` for the padded region.

```python
>>> a = [1, 2, 3, 4, 5]
>>> np.pad(a, (2, 3), 'linear_ramp', end_values=(5, -4))
array([ 5,  3,  1,  2,  3,  4,  5,  2, -1, -4])
```

--------------------------------

### Get Total Time Passed

Source: https://fdtd.readthedocs.io/en/latest/_modules/fdtd/grid

Property to retrieve the total simulation time elapsed, calculated from the number of time steps taken and the duration of each time step.

```python
@property
    def time_passed(self) -> float:
        """get the total time passed"""
        return self.time_steps_passed * self.time_step
```

--------------------------------

### fdtd.backend Methods

Source: https://fdtd.readthedocs.io/en/latest/fdtd

API documentation for methods within the fdtd.backend module, including those in NumpyBackend.

```APIDOC
fdtd.backend:
  set_backend(backend_name: str)
    Sets the backend for FDTD computations.

  NumpyBackend:
    arange(*args, **kwargs)
      Creates an array with evenly spaced values.
    array(obj, dtype=None, copy=True)
      Converts the input to an array.
    asarray(obj, dtype=None, copy=False)
      Converts the input to an array without copying if possible.
    bmm(a, b)
      Performs matrix multiplication of batches of matrices.
    broadcast_arrays(*args, **kwargs)
      Broadcasts arrays to a common shape.
    broadcast_to(x, shape)
      Broadcasts an array to a new shape.
    complex(real, imag)
      Creates a complex number.
    cos(x)
      Computes the cosine of the input.
    divide(x1, x2)
      Performs element-wise division.
    exp(x)
      Computes the exponential of the input.
    fft(a, n=None, axis=-1, norm=None)
      Computes the one-dimensional discrete Fourier Transform.
    fftfreq(n, d=1.0)
      Returns the DFT sample frequencies.
    float(obj)
      Converts the input to a float.
    int(obj)
      Converts the input to an integer.
    is_array(obj)
      Checks if the input is a backend array.
    linspace(start, stop, num=50, endpoint=True, retstep=False, dtype=None, axis=0)
      Returns evenly spaced numbers over a specified interval.
    max(obj, axis=None, out=None, keepdims=False)
      Returns the maximum value of an array or maximum along an axis.
    numpy(obj)
      Converts a backend array to a NumPy array.
    ones(shape, dtype=None, order='C')
      Creates an array of ones.
    pad(array, pad_width, mode='constant', **kwargs)
      Pads an array with values.
    reshape(obj, newshape, order='C')
      Reshapes an array.
    sin(x)
      Computes the sine of the input.
    squeeze(a, axis=None)
      Removes axes of length one from an array.
    stack(arrays, axis=0, out=None)
      Joins a sequence of arrays along a new axis.
    sum(obj, axis=None, dtype=None, out=None, keepdims=False)
      Returns the sum of array elements over a given axis.
    transpose(a, axes=None)
      Permutes the dimensions of an array.
    zeros(shape, dtype=None, order='C')
      Creates an array of zeros.
    zeros_like(a, dtype=None, order='K', subok=True, shape=None)
      Returns an array of zeros with the same shape and type as the input.
```

--------------------------------

### Get Grid Shape

Source: https://fdtd.readthedocs.io/en/latest/_modules/fdtd/grid

Property to retrieve the shape of the FDTD grid as a tuple (Nx, Ny, Nz), representing the number of cells along each spatial dimension.

```python
@property
    def shape(self) -> Tuple[int, int, int]:
        """get the shape of the FDTD grid"""
        return (self.Nx, self.Ny, self.Nz)
```

--------------------------------

### FDTD Grid Class API

Source: https://fdtd.readthedocs.io/en/latest/fdtd

Documentation for the `fdtd.grid.Grid` class, which represents the FDTD simulation grid. It covers initialization, adding simulation components, running the simulation, and saving data.

```APIDOC
class fdtd.grid.Grid:
    """The FDTD Grid

    The grid is the core of the FDTD Library. It is where everything comes
    together and where the biggest part of the calculations are done.
    """

    __init__(shape: Tuple[Number, Number, Number], grid_spacing: float = 1.55e-07, permittivity: float = 1.0, permeability: float = 1.0, courant_number: float | None = None):
        """Initializes the FDTD grid.

        Parameters:
            shape (Tuple[Number, Number, Number]): Shape of the FDTD grid.
            grid_spacing (float, optional): Distance between the grid cells. Defaults to 1.55e-07.
            permittivity (float, optional): The relative permittivity of the background. Defaults to 1.0.
            permeability (float, optional): The relative permeability of the background. Defaults to 1.0.
            courant_number (float | None, optional): The courant number of the FDTD simulation. Defaults to the inverse of the square root of the number of dimensions > 1 (optimal value). The timestep of the simulation will be derived from this number using the CFL-condition.
        """

    add_boundary(name, boundary):
        """Adds a boundary to the grid.

        Parameters:
            name (str): The name of the boundary.
            boundary: The boundary object to add.
        """

    add_detector(name, detector):
        """Adds a detector to the grid.

        Parameters:
            name (str): The name of the detector.
            detector: The detector object to add.
        """

    add_object(name, obj):
        """Adds an object to the grid.

        Parameters:
            name (str): The name of the object.
            obj: The object to add.
        """

    add_source(name, source):
        """Adds a source to the grid.

        Parameters:
            name (str): The name of the source.
            source: The source object to add.
        """

    generate_video(delete_frames=False):
        """Compiles frames into a video.

        These frames should be saved through `fdtd.Grid.visualize(save=True)` while having `fdtd.Grid.save_simulation()` enabled.

        Parameters:
            delete_frames (bool, optional): Delete stored frames after conversion to video. Defaults to False.

        Returns:
            str: The filename of the generated video.

        Note:
            This function requires `ffmpeg` to be available in your path.
        """

    promote_dtypes_to_complex():
        """Promotes the grid's data types to complex numbers.
        """

    reset():
        """Resets the grid by setting all fields to zero.
        """

    run(total_time: Number, progress_bar: bool = True):
        """Runs an FDTD simulation.

        Parameters:
            total_time (Number): The total time for the simulation to run.
            progress_bar (bool, optional): Choose to show a progress bar during simulation. Defaults to True.
        """

    save_data():
        """Saves readings from all detectors in the grid into a numpy zip file.

        Each detector is stored in separate arrays. Electric and magnetic field readings of each detector are also stored separately with suffix ' (E)' and ' (H)' (Example: ['detector0 (E)', 'detector0 (H)']). Therefore, the numpy zip file contains arrays twice the number of detectors.

        REQUIRES 'fdtd.Grid.save_simulation()' to be run before this function.

        Parameters:
            None
        """

    save_simulation(sim_name=None):
        """Creates a folder and initializes environment to store simulation or related details.

        saveSimulation() needs to be run before running any function that stores data (generate_video(), save_data()).

        Parameters:
            sim_name (str, optional): Preferred name for simulation.
        """

    shape():
        """Gets the shape of the FDTD grid.

        Returns:
            Tuple[int, int, int]: The shape of the FDTD grid.
        """

    step():
        """Performs a single simulation step.
        """

```

--------------------------------

### fdtd.grid Methods

Source: https://fdtd.readthedocs.io/en/latest/fdtd

API documentation for the Grid class and its methods in the fdtd package.

```APIDOC
fdtd.grid:
  Grid:
    __init__(**kwargs)
      Initializes the simulation grid.
    add_boundary(boundary)
      Adds a boundary condition to the grid.
    add_detector(detector)
      Adds a detector to the grid.
    add_object(obj)
      Adds an object (e.g., material, source) to the grid.
    add_source(source)
      Adds a source to the grid.
    generate_video(filename, **kwargs)
      Generates a video from simulation data.
```

--------------------------------

### Get Detector Values

Source: https://fdtd.readthedocs.io/en/latest/_modules/fdtd/detectors

Outputs the detected electric (E) and magnetic (H) field data stored by the detector. Returns a dictionary containing the captured field arrays.

```python
def detector_values(self):
        """ outputs what detector detects """
        return {"E": self.E, "H": self.H}

```

--------------------------------

### Import necessary libraries

Source: https://fdtd.readthedocs.io/en/latest/examples/04-performance-profiling

Imports required modules for plotting, line profiling, and the fdtd package itself, including its backend functionalities.

```python
import matplotlib.pyplot as plt
from line_profiler import LineProfiler

import fdtd
import fdtd.backend as bd
```

--------------------------------

### Get Grid Dimensions (x, y, z)

Source: https://fdtd.readthedocs.io/en/latest/_modules/fdtd/grid

Properties to retrieve the number of grid cells in the x, y, and z directions, scaled by grid spacing. These provide the physical extent of the grid in each dimension.

```python
@property
    def x(self) -> int:
        """get the number of grid cells in the x-direction"""
        return self.Nx * self.grid_spacing

    @property
    def y(self) -> int:
        """get the number of grid cells in the y-direction"""
        return self.Ny * self.grid_spacing

    @property
    def z(self) -> int:
        """get the number of grid cells in the y-direction"""
        return self.Nz * self.grid_spacing
```

--------------------------------

### Initialize FDTD Grid and Components

Source: https://fdtd.readthedocs.io/en/latest/examples/03-objects-of-arbitrary-shape

Initializes the FDTD simulation grid with specified dimensions and grid spacing. It then configures a line source, a detector, and Perfect Matched Layer (PML) boundary conditions for the simulation domain.

```python
grid = fdtd.Grid(
    shape = (300, 300, 1), # 25um x 15um x 1 (grid_spacing) --> 2D FDTD
    grid_spacing = 1e-7,
    permittivity = 1,
)

grid[50:250, 50, 0] = fdtd.LineSource(
    period = 1550e-9 / (3e8), name="source"
)

grid[50:250, 250, 0] = fdtd.LineDetector(name="detector")

grid[0:10, :, :] = fdtd.PML(name="pml_xlow")
grid[-10:, :, :] = fdtd.PML(name="pml_xhigh")
grid[:, 0:10, :] = fdtd.PML(name="pml_ylow")
grid[:, -10:, :] = fdtd.PML(name="pml_yhigh")
```

--------------------------------

### FDTD DomainBorderPML Function

Source: https://fdtd.readthedocs.io/en/latest/fdtd

Documentation for the DomainBorderPML function. This is a convenience function to add a layer of PML around an existing FDTD grid, useful for setups requiring boundary absorption on all sides. It modifies the grid in-place.

```APIDOC
fdtd.boundaries.DomainBorderPML(grid, border_cells=5)
  Some problem setups require a layer of PML all the way around the problem.
  This is a convenience function to add such a layer to an existing grid.
  Caution: Alters grid in-place.
```
Tokens:
Raw