GRCWA

https://github.com/weiliangjinca/grcwa
Admin
GRCWA is a Python implementation of rigorous coupled wave analysis (RCWA) for arbitrarily shaped...
Tokens:10,786
Snippets:89
Trust Score:5.8
Update:6 months ago
Show doc for...
Tokens:
Raw
### Setup Local Development Environment

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/contributing.md

Commands to clone the repository, create a virtual environment, and install the project in development mode.

```shell
$ git clone git@github.com:your_name_here/grcwa.git
$ mkvirtualenv grcwa
$ cd grcwa/
$ python setup.py develop
```

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

### Install GRCWA

Source: https://context7.com/weiliangjinca/grcwa/llms.txt

Instructions for installing the GRCWA library using pip from PyPI or from source after cloning the repository.

```bash
# Install from PyPI
pip install grcwa

# Or install from source
git clone git://github.com/weiliangjinca/grcwa
cd grcwa
pip install .
```

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

### Manage Layers and Setup

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/usage.md

Methods for adding uniform or patterned layers to the simulation stack and finalizing the setup with optional periodicity scaling and truncation methods.

```python
obj.Add_LayerUniform(thick0, ep0)
obj.Add_LayerGrid(thickp, Nx, Ny)
obj.Init_Setup(Pscale=scale, Gmethod=0)
```

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

### Initialize and Configure grcwa

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/usage.md

Basic setup steps including importing the library, enabling autograd, and initializing the RCWA object with geometric and frequency parameters.

```python
import grcwa
grcwa.set_backend('autograd')
obj = grcwa.obj(nG, L1, L2, freq, theta, phi, verbose=0)
```

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

### Install GRCWA Library

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/readme.md

Methods to install the GRCWA package using pip or by cloning the repository from GitHub.

```console
$ pip install grcwa
```

```console
$ git clone git://github.com/weiliangjinca/grcwa
$ pip install .
```

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

### RCWA Setup Options

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/usage.md

Covers advanced setup options for the RCWA, including scaling lateral periodicity and choosing the Fourier space truncation method.

```APIDOC
## RCWA Setup Options

### Description
This section describes how to configure advanced settings for the RCWA simulation, such as scaling the lateral periodicity and selecting the method for Fourier space truncation.

### Method
Python code snippets

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
# Scale the periodicity in both lateral directions simultaneously
# Pscale: scaling factor for Lx and Ly
obj.Init_Setup(Pscale=scale)

# Fourier space truncation options
# Gmethod: 0 for circular truncation, 1 for rectangular truncation
obj.Init_Setup(Gmethod=0)
```

### Response
N/A
```

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

### Initialize RCWA Setup

Source: https://context7.com/weiliangjinca/grcwa/llms.txt

Initialize the RCWA simulation after adding all layers. This step computes reciprocal lattice, eigenvalues for uniform layers, and prepares data structures for patterned layers.

```python
import grcwa
import numpy as np

L1 = [0.5, 0]
L2 = [0, 0.5]
nG = 101
obj = grcwa.obj(nG, L1, L2, freq=1.0, theta=0.0, phi=0.0, verbose=0)

obj.Add_LayerUniform(1.0, 1.0)
obj.Add_LayerGrid(0.5, 100, 100)
obj.Add_LayerUniform(1.0, 1.0)

# Initialize with default settings (circular truncation)
obj.Init_Setup()

# Or with custom settings:
# Pscale: scale the period (useful for optimization)
# Gmethod: 0 for circular truncation, 1 for rectangular
obj.Init_Setup(Pscale=1.0, Gmethod=0)
```

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

### Get Fourier Mode Amplitudes (Python)

Source: https://context7.com/weiliangjinca/grcwa/llms.txt

Retrieves the Fourier mode amplitudes (forward 'ai' and backward 'bi' propagating waves) at a specific layer and z-offset. These amplitudes are essential for custom field calculations and are returned as numpy arrays. Dependencies include numpy and grcwa.

```python
import grcwa
import numpy as np

L1 = [0.5, 0]
L2 = [0, 0.5]
nG = 101

obj = grcwa.obj(nG, L1, L2, freq=1.0, theta=0.0, phi=0.0, verbose=0)
obj.Add_LayerUniform(1.0, 1.0)
obj.Add_LayerGrid(0.5, 100, 100)
obj.Add_LayerUniform(1.0, 1.0)
obj.Init_Setup()

epgrid = np.ones((100, 100)) * 4.0
obj.GridLayer_geteps(epgrid.flatten())
obj.MakeExcitationPlanewave(1, 0, 0, 0, order=0)

# Get amplitudes at layer 1, z_offset = 0.25
which_layer = 1
z_offset = 0.25

ai, bi = obj.GetAmplitudes(which_layer, z_offset)
# ai: forward propagating amplitudes (length 2*nG)
# bi: backward propagating amplitudes (length 2*nG)

print(f'Forward amplitude shape: {ai.shape}')
print(f'Backward amplitude shape: {bi.shape}')

```

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

### GRCWA Initialization and Layer Definition

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/usage.md

Demonstrates how to import the library, set the backend, initialize the RCWA object with material properties and dimensions, and add uniform and patterned layers.

```APIDOC
## GRCWA Initialization and Layer Definition

### Description
This section covers the basic setup of the grcwa library, including importing, setting the computation backend, initializing the main RCWA object, and defining different types of layers.

### Method
Python code snippets

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
import grcwa

# Enable autograd for automatic differentiation
grcwa.set_backend('autograd')

# Initialize the RCWA object
# nG: number of Fourier orders
# L1, L2: lateral dimensions of the simulation domain
# freq: frequency of the incident light
# theta, phi: incident angles
# verbose: 0 for silent, 1 to print nG
obj = grcwa.obj(nG, L1, L2, freq, theta, phi, verbose=0)

# Add a uniform layer
# thick0: thickness of the layer
# ep0: permittivity of the layer
obj.Add_LayerUniform(thick0, ep0)

# Add a patterned layer
# thickp: thickness of the layer
# Nx, Ny: number of grid points in x and y directions
obj.Add_LayerGrid(thickp, Nx, Ny)

# Finalize layer setup after adding all layers
obj.Init_Setup()
```

### Response
N/A
```

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

### Initialize RCWA Simulation Object

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/readme.md

Sets up the core RCWA object by defining lattice vectors, truncation order, frequency, and incident light angles.

```python
import grcwa
import numpy as np
grcwa.set_backend('autograd')

L1 = [0.2,0]
L2 = [0,0.2]
nG = 101
freq = 1.
theta = np.pi/10
phi = 0.

obj = grcwa.obj(nG,L1,L2,freq,theta,phi,verbose=1)
```

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

### Deploy Project Version

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/contributing.md

Commands for maintainers to bump the project version and push tags to trigger automated deployment.

```shell
$ bump2version patch
$ git push
$ git push --tags
```

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

### Topology Optimization with Autograd

Source: https://context7.com/weiliangjinca/grcwa/llms.txt

Demonstrates how to integrate GRCWA with the autograd library to perform gradient-based optimization of photonic structures. It defines an objective function for reflection and computes gradients with respect to the dielectric profile.

```python
import grcwa
grcwa.set_backend('autograd')
from autograd import grad

def fun_reflection(x, Qabs):
    obj = grcwa.obj(nG, L1, L2, freq * (1 + 1j/2/Qabs), 0., 0., verbose=0)
    obj.Add_LayerUniform(thick0, 1.0)
    obj.Add_LayerGrid(thickp, Nx, Ny)
    obj.Add_LayerUniform(thickN, 1.0)
    obj.Init_Setup()
    obj.MakeExcitationPlanewave(1, 0, 0, 0, order=0)
    obj.GridLayer_geteps(x)
    return obj.RT_Solve(normalize=1)[0]

grad_fun = grad(lambda x: fun_reflection(x, np.inf))
dR_dx = grad_fun(x0)
```

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

### Define Excitation and Solve

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/usage.md

Configuring planewave excitation and calculating reflection (R) and transmission (T) coefficients, including normalization options.

```python
obj.MakeExcitationPlanewave(p_amp, p_phase, s_amp, s_phase, order=0)
R, T = obj.RT_Solve(normalize=1)
Ri, Ti = obj.RT_Solve(byorder=1)
```

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

### Excitation Definition

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/usage.md

Shows how to define the incident light, including standard plane wave excitation and custom incidence using forward and backward amplitude vectors.

```APIDOC
## Excitation Definition

### Description
This section explains how to define the excitation source for the RCWA simulation, covering both standard plane wave excitation and custom incidence conditions.

### Method
Python code snippets

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
# Define a plane wave excitation
# p_amp, p_phase: amplitude and phase for p-polarized component
# s_amp, s_phase: amplitude and phase for s-polarized component
# order: order of the diffracted wave (default is 0)
obj.MakeExcitationPlanewave(p_amp, p_phase, s_amp, s_phase, order = 0)

# Define custom incidence light (other than planewave)
# a0: forward amplitude vector (length 2*obj.nG)
# bN: backward amplitude vector (length 2*obj.nG)
obj.a0 = ... # forward amplitudes
obj.bN = ... # backward amplitudes
```

### Response
N/A
```

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

### Version Control Workflow

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/contributing.md

Standard git commands to stage, commit, and push changes to a remote repository.

```shell
$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature
```

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

### Set Excitation Parameters

Source: https://github.com/weiliangjinca/grcwa/blob/master/README.rst

Configures the incident plane wave excitation for the simulation.

```python
planewave={'p_amp':0,'s_amp':1,'p_phase':0,'s_phase':0}
obj.MakeExcitationPlanewave(planewave['p_amp'],planewave['p_phase'],planewave['s_amp'],planewave['s_phase'],order = 0)
```

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

### Solve RCWA System

Source: https://github.com/weiliangjinca/grcwa/blob/master/README.rst

Demonstrates the basic usage of the RT_Solve method to compute reflection and transmission coefficients. The normalize parameter is set to 1 to ensure consistent scaling.

```python
R, T = obj.RT_Solve(normalize=1)
```

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

### Solve for Reflection and Transmission

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/readme.md

Sets the incident light polarization and solves the RCWA system to obtain reflection (R) and transmission (T) coefficients.

```python
planewave={'p_amp':0,'s_amp':1,'p_phase':0,'s_phase':0}
obj.MakeExcitationPlanewave(planewave['p_amp'],planewave['p_phase'],planewave['s_amp'],planewave['s_phase'],order = 0)

R,T= obj.RT_Solve(normalize=1)
```

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

### Run Quality Assurance and Tests

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/contributing.md

Commands to verify code quality using flake8 and execute test suites using pytest or tox.

```shell
$ flake8 grcwa tests
$ python setup.py test
$ pytest
$ tox
```

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

### Compute Reflection and Transmission Coefficients

Source: https://context7.com/weiliangjinca/grcwa/llms.txt

Computes total power reflection (R) and transmission (T) coefficients. Supports normalization for oblique incidence and extraction of power per diffraction order.

```python
R, T = obj.RT_Solve(normalize=1)
Ri, Ti = obj.RT_Solve(normalize=1, byorder=1)
print(f'R = {R:.6f}, T = {T:.6f}')
```

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

### Define Patterned Layer Structure

Source: https://context7.com/weiliangjinca/grcwa/llms.txt

Demonstrates how to initialize a GRCWA object, add uniform and grid-based layers, and define a dielectric constant profile for a patterned layer using a circular hole geometry.

```python
import grcwa
import numpy as np

L1 = [1.5, 0]
L2 = [0, 1.5]
nG = 301
Nx, Ny = 400, 400

obj = grcwa.obj(nG, L1, L2, freq=1.0, theta=0.0, phi=0.0, verbose=0)
obj.Add_LayerUniform(1.0, 1.0)
obj.Add_LayerGrid(0.2, Nx, Ny)
obj.Add_LayerUniform(1.0, 1.0)
obj.Init_Setup()

epgrid = np.ones((Nx, Ny), dtype=float) * 4.0
x0 = np.linspace(0, 1., Nx)
y0 = np.linspace(0, 1., Ny)
x, y = np.meshgrid(x0, y0, indexing='ij')

hole = (x - 0.5)**2 + (y - 0.5)**2 < 0.3**2
epgrid[hole] = 1.0

obj.GridLayer_geteps(epgrid.flatten())
```

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

### Reconstruct Real-Space Dielectric Profile (Python)

Source: https://context7.com/weiliangjinca/grcwa/llms.txt

Reconstructs the real-space dielectric profile (epsilon) from its truncated Fourier expansion for a given layer. This is useful for visualizing the structure after Fourier truncation and can retrieve different tensor components for patterned layers. Dependencies include numpy and grcwa.

```python
import grcwa
import numpy as np

L1 = [0.5, 0]
L2 = [0, 0.5]
nG = 101
Nx, Ny = 100, 100

obj = grcwa.obj(nG, L1, L2, freq=1.0, theta=0.0, phi=0.0, verbose=0)
obj.Add_LayerUniform(1.0, 1.0)
obj.Add_LayerGrid(0.5, Nx, Ny)
obj.Add_LayerUniform(1.0, 1.0)
obj.Init_Setup()

epgrid = np.ones((Nx, Ny)) * 4.0
x0 = np.linspace(0, 1., Nx)
y0 = np.linspace(0, 1., Ny)
x, y = np.meshgrid(x0, y0, indexing='ij')
hole = (x - 0.5)**2 + (y - 0.5)**2 < 0.3**2
epgrid[hole] = 1.0
obj.GridLayer_geteps(epgrid.flatten())

# Reconstruct epsilon from Fourier series
which_layer = 1
ep_reconstructed = obj.Return_eps(which_layer, Nx, Ny, component='xx')
# component options for patterned layers: 'xx', 'xy', 'yx', 'yy', 'zz'
# For uniform layers, returns isotropic value

print(f'Original eps range: {epgrid.min():.2f} to {epgrid.max():.2f}')
print(f'Reconstructed eps range: {np.real(ep_reconstructed).min():.2f} to {np.real(ep_reconstructed).max():.2f}')

```

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

### Configure Layer Patterns and Epsilon

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/readme.md

Defines the geometric patterns (holes) for grid layers and updates the simulation object with the combined dielectric grid.

```python
radius = 0.5
a = 0.5
ep1 = 4.
ep2 = 6.
epbkg = 1.

x0 = np.linspace(0,1.,Nx)
y0 = np.linspace(0,1.,Ny)
x, y = np.meshgrid(x0,y0,indexing='ij')

epgrid1 = np.ones((Nx,Ny))*ep1
ind = (x-.5)**2+(y-.5)**2<radius**2
epgrid1[ind]=epbkg

epgrid2 = np.ones((Nx,Ny))*ep2
ind = np.logical_and(np.abs(x-.5)<a/2, np.abs(y-.5)<a/2)
epgrid2[ind]=epbkg

epgrid = np.concatenate((epgrid1.flatten(),epgrid2.flatten()))
obj.GridLayer_geteps(epgrid)
```

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

### Multi-Layer Patterned Structure Simulation

Source: https://context7.com/weiliangjinca/grcwa/llms.txt

Simulates structures containing multiple patterned layers. Epsilon profiles for each layer are concatenated into a single array before being passed to the simulation object.

```python
obj.Add_LayerGrid(pthick[0], Nx, Ny)
obj.Add_LayerGrid(pthick[1], Nx, Ny)
obj.Init_Setup()
epgrid = np.concatenate((epgrid1.flatten(), epgrid2.flatten()))
obj.GridLayer_geteps(epgrid)
obj.RT_Solve(normalize=1)
```

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

### Create RCWA Object

Source: https://context7.com/weiliangjinca/grcwa/llms.txt

Initialize an RCWA simulation object with lattice vectors, frequency, incident angles, and truncation order. This object is the main interface for RCWA simulations.

```python
import grcwa
import numpy as np

# Lattice constants (unit cell in x-y plane)
L1 = [1.5, 0]    # First lattice vector
L2 = [0, 1.5]    # Second lattice vector

# Truncation order for Fourier expansion
nG = 301  # Actual number might be smaller

# Frequency and incident angles
freq = 1.0
theta = 0.0      # Polar angle (radians)
phi = 0.0        # Azimuthal angle (radians)

# Create RCWA object
obj = grcwa.obj(nG, L1, L2, freq, theta, phi, verbose=1)
# Output: Total nG = <actual truncation order>
```

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

### Reflection and Transmission Calculation

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/usage.md

Details how to compute the reflection (R) and transmission (T) coefficients, including options for normalization and obtaining results by diffraction order.

```APIDOC
## Reflection and Transmission Calculation

### Description
This section describes how to calculate the reflection and transmission coefficients of the structure. It includes options for normalizing the results and retrieving them broken down by diffraction order.

### Method
Python code snippets

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
# Normalize output (useful when the 0-th medium is not vacuum or for oblique incidence)
# normalize: 1 to enable normalization
R, T = obj.RT_Solve(normalize = 1)

# Get Poynting flux by order
# byorder: 1 to get results per diffraction order
Ri, Ti = obj.RT_Solve(byorder=1)
# Ri(Ti) has length obj.nG. To see which order, check obj.G; to see which kx, ky, check obj.kx, obj.ky.
```

### Response
N/A
```

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

### Patterned Layer Epsilon Profile

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/usage.md

Explains how to provide the epsilon profile for a patterned layer using a flattened 1D array of permittivity values.

```APIDOC
## Patterned Layer Epsilon Profile

### Description
This section details how to feed the permittivity profile for a patterned layer into the RCWA object. The epsilon values are expected as a flattened 1D array.

### Method
Python code snippets

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
# Assuming epgrid1, epgrid2, ... are 2D numpy arrays representing permittivity in different regions
# x is a 1D array formed by concatenating the flattened permittivity grids
x = np.concatenate((epgrid1.flatten(), epgrid2.flatten(), ...))
obj.GridLayer_geteps(x)
```

### Response
N/A
```

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

### Define Layer Structure and Dielectrics

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/readme.md

Configures the layer stack by adding uniform and grid-based layers with specific thicknesses and dielectric constants.

```python
Np = 2
Nx = 100
Ny = 100

thick0 = 0.1
pthick = [0.2,0.3]
thickN = 0.4

ep0 = 2.
epN = 3.

obj.Add_LayerUniform(thick0,ep0)
for i in range(Np):
    obj.Add_LayerGrid(pthick[i],Nx,Ny)
obj.Add_LayerUniform(thickN,epN)

obj.Init_Setup()
```

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

### Set GRCWA Backend

Source: https://context7.com/weiliangjinca/grcwa/llms.txt

Configure the computational backend for GRCWA, choosing between standard numpy operations or autograd-enabled automatic differentiation for gradient computations.

```python
import grcwa

# Use numpy backend (default)
grcwa.set_backend('numpy')

# Enable autograd for gradient computations
grcwa.set_backend('autograd')
```

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

### Configure Planewave Excitation

Source: https://context7.com/weiliangjinca/grcwa/llms.txt

Shows how to define incident planewave excitation for a GRCWA simulation, specifying p-polarization (TM) or s-polarization (TE) states and the target diffraction order.

```python
planewave = {'p_amp': 1, 's_amp': 0, 'p_phase': 0, 's_phase': 0}
obj.MakeExcitationPlanewave(
    planewave['p_amp'],
    planewave['p_phase'],
    planewave['s_amp'],
    planewave['s_phase'],
    order=0
)
```

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

### Field Calculation in Fourier and Real Space

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/usage.md

Explains how to obtain the electromagnetic fields (E and H) in both Fourier space and real space at a specified layer and z-offset.

```APIDOC
## Field Calculation in Fourier and Real Space

### Description
This section details how to compute the electromagnetic field components (E and H) within the structure, both in the Fourier domain and in real space on a grid.

### Method
Python code snippets

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
# Get Fourier amplitude of fields at a specific layer and z-offset
# E = [Ex, Ey, Ez], H = [Hx, Hy, Hz]
E, H = obj.Solve_FieldFourier(which_layer, z_offset)

# Get fields in real space on grid points
# E = [Ex, Ey, Ez], H = [Hx, Hy, Hz]
E, H = obj.Solve_FieldOnGrid(which_layer, z_offset)
```

### Response
N/A
```

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

### Compute Maxwell Stress Tensor Integral (Python)

Source: https://context7.com/weiliangjinca/grcwa/llms.txt

Calculates the Maxwell stress tensor integrated over a z-plane, returning the force components (Tx, Ty, Tz). This is valuable for determining optical forces acting on structures within the simulation. Dependencies include numpy and grcwa.

```python
import grcwa
import numpy as np

L1 = [0.5, 0]
L2 = [0, 0.5]
nG = 101
Nx, Ny = 100, 100

obj = grcwa.obj(nG, L1, L2, freq=1.0, theta=0.0, phi=0.0, verbose=0)
obj.Add_LayerUniform(1.0, 1.0)
obj.Add_LayerGrid(0.5, Nx, Ny)
obj.Add_LayerUniform(1.0, 1.0)
obj.Init_Setup()

epgrid = np.ones((Nx, Ny)) * 4.0
obj.GridLayer_geteps(epgrid.flatten())
obj.MakeExcitationPlanewave(1, 0, 0, 0, order=0)


```

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

### Volume Integration and Stress Tensor Calculation

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/usage.md

Covers advanced calculations including volume integration with a custom convolution matrix and computation of the integrated Maxwell stress tensor.

```APIDOC
## Volume Integration and Stress Tensor Calculation

### Description
This section describes advanced computational functions, including performing volume integrals with specified convolution matrices and calculating the Maxwell stress tensor integrated over a z-plane.

### Method
Python code snippets

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
# Compute volume integration with respect to a convolution matrix M
# which_layer: index of the layer
# Mx, My, Mz: convolution matrices for x, y, and z directions
# normalize: 1 to enable normalization
val = obj.Volume_integral(which_layer, Mx, My, Mz, normalize=1)

# Compute Maxwell stress tensor, integrated over the z-plane
# which_layer: index of the layer
Tx, Ty, Tz = obj.Solve_ZStressTensorIntegral(which_layer)
```

### Response
N/A
```

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

### Field and Flux Analysis

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/usage.md

Advanced methods for extracting field amplitudes, Poynting flux, stress tensors, and real-space epsilon profiles at specific layers and offsets.

```python
ai, bi = obj.GetAmplitudes(which_layer, z_offset)
E, H = obj.Solve_FieldFourier(which_layer, z_offset)
E_grid, H_grid = obj.Solve_FieldOnGrid(which_layer, z_offset)
Tx, Ty, Tz = obj.Solve_ZStressTensorIntegral(which_layer)
```

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

### Run Specific Test Suite

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/contributing.md

Command to execute a specific subset of tests using pytest.

```shell
$ pytest tests.test_grcwa
```

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

### Field Amplitude and Epsilon Profile Retrieval

Source: https://github.com/weiliangjinca/grcwa/blob/master/docs/usage.md

Provides methods to retrieve the amplitude of eigenvectors at a specific layer and z-offset, and to reconstruct the real-space epsilon profile from Fourier orders.

```APIDOC
## Field Amplitude and Epsilon Profile Retrieval

### Description
This section covers functions to retrieve detailed information about the electromagnetic fields and the material properties within the simulated structure.

### Method
Python code snippets

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
# Get amplitude of eigenvectors at a specific layer and z-offset
# which_layer: index of the layer
# z_offset: offset in the z-direction within the layer
ai, bi = obj.GetAmplitudes(which_layer, z_offset)

# Get real-space epsilon profile reconstructed from Fourier orders
# which_layer: index of the layer
# Nx, Ny: grid dimensions for reconstruction
# component: 'xx', 'xy', 'yx', 'yy', 'zz' for patterned layers; assumed isotropic for uniform layers
ep = obj.Return_eps(which_layer, Nx, Ny, component='xx')
```

### Response
N/A
```

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

### Compute Real-Space Fields on Grid (Python)

Source: https://context7.com/weiliangjinca/grcwa/llms.txt

Computes real-space electromagnetic fields (E and H) on a spatial grid at a specified layer and z-offset using an inverse Fourier transform. It can return fields at a single z-offset or a list of fields at multiple z-offsets. Dependencies include numpy and grcwa.

```python
import grcwa
import numpy as np

L1 = [0.5, 0]
L2 = [0, 0.5]
nG = 101
Nx, Ny = 100, 100

obj = grcwa.obj(nG, L1, L2, freq=1.0, theta=0.0, phi=0.0, verbose=0)
obj.Add_LayerUniform(1.0, 1.0)
obj.Add_LayerGrid(0.5, Nx, Ny)
obj.Add_LayerUniform(1.0, 1.0)
obj.Init_Setup()

epgrid = np.ones((Nx, Ny)) * 4.0
obj.GridLayer_geteps(epgrid.flatten())
obj.MakeExcitationPlanewave(1, 0, 0, 0, order=0)

# Get real-space fields at layer 1, z = 0.1
which_layer = 1
z_offset = 0.1

E, H = obj.Solve_FieldOnGrid(which_layer, z_offset)
# E = [Ex, Ey, Ez], each is Nx x Ny array
# H = [Hx, Hy, Hz], each is Nx x Ny array

Ex, Ey, Ez = E
Hx, Hy, Hz = H

# Compute field intensity
intensity = np.abs(Ex)**2 + np.abs(Ey)**2 + np.abs(Ez)**2
print(f'Max |E|^2: {np.max(intensity):.4f}')

# Get fields at multiple z positions
z_offsets = [0.0, 0.1, 0.2, 0.3]
eh_list = obj.Solve_FieldOnGrid(which_layer, z_offsets)
# Returns list of [[Ex,Ey,Ez], [Hx,Hy,Hz]] for each z

```

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

### Set Grid Layer Dielectric Profile

Source: https://context7.com/weiliangjinca/grcwa/llms.txt

Set the dielectric profile for all patterned (grid) layers in the RCWA simulation. The epsilon array must be a 1D concatenation of flattened 2D epsilon grids for each patterned layer.

```python
import grcwa
import numpy as np

```

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

### Solve Electromagnetic Fields in Fourier Space

Source: https://context7.com/weiliangjinca/grcwa/llms.txt

Computes the Fourier coefficients of the E and H fields at a specific layer and z-offset, useful for field analysis in k-space.

```python
which_layer = 1
z_offset = 0.25
eh = obj.Solve_FieldFourier(which_layer, z_offset)
E_fourier = eh[0][0]
H_fourier = eh[0][1]
```

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

### Compute Volume Integral of Field Intensities (Python)

Source: https://context7.com/weiliangjinca/grcwa/llms.txt

Computes the volume integral of field intensities weighted by convolution matrices over a specified layer. This function is useful for calculating absorbed power, where the result should be multiplied by the angular frequency (omega). Dependencies include numpy and grcwa.

```python
import grcwa
import numpy as np

L1 = [0.5, 0]
L2 = [0, 0.5]
nG = 101
Nx, Ny = 100, 100

obj = grcwa.obj(nG, L1, L2, freq=1.0, theta=0.0, phi=0.0, verbose=0)
obj.Add_LayerUniform(1.0, 1.0)
obj.Add_LayerGrid(0.5, Nx, Ny)
obj.Add_LayerUniform(1.0, 1.0)
obj.Init_Setup()

# Lossy dielectric layer
epgrid = np.ones((Nx, Ny)) * (4.0 + 0.1j)  # Complex epsilon for absorption
obj.GridLayer_geteps(epgrid.flatten())
obj.MakeExcitationPlanewave(1, 0, 0, 0, order=0)

# Define convolution matrices (identity for simple integral)
nG_actual = obj.nG
Mx = np.eye(nG_actual, dtype=complex)
My = np.eye(nG_actual, dtype=complex)
Mz = np.eye(nG_actual, dtype=complex)

which_layer = 1
val = obj.Volume_integral(which_layer, Mx, My, Mz, normalize=1)
# Absorbed power = omega * val
absorbed_power = 2 * np.pi * 1.0 * val  # omega = 2*pi*freq
print(f'Volume integral: {val}')

```

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

### Hexagonal Lattice Simulation

Source: https://context7.com/weiliangjinca/grcwa/llms.txt

Configures a photonic crystal simulation using non-orthogonal lattice vectors. It transforms coordinates to Cartesian space to define geometric features like circular holes.

```python
angle = np.pi / 3
L1 = [0.1, 0]
L2 = [0.1 * np.cos(angle), 0.1 * np.sin(angle)]
obj = grcwa.obj(nG, L1, L2, freqcmp, theta=0., phi=0., verbose=1)
# ... define grid and hole geometry ...
obj.GridLayer_geteps(epgrid.flatten())
obj.RT_Solve(normalize=1)
```

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

### Compute Stress Tensor Integral

Source: https://context7.com/weiliangjinca/grcwa/llms.txt

Calculates the stress tensor integral for a specific layer in a GRCWA simulation object. It returns the force components Tx, Ty, and Tz.

```python
which_layer = 1
Tx, Ty, Tz = obj.Solve_ZStressTensorIntegral(which_layer)
print(f'Stress tensor components:\n  Tx = {Tx:.6f}\n  Ty = {Ty:.6f}\n  Tz = {Tz:.6f}')
```

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

### Add Patterned Layer to RCWA

Source: https://context7.com/weiliangjinca/grcwa/llms.txt

Add a patterned layer with a spatially-varying dielectric profile defined on a grid. The grid resolution affects accuracy and computation time.

```python
import grcwa
import numpy as np

# Setup RCWA
L1 = [0.5, 0]
L2 = [0, 0.5]
nG = 101
obj = grcwa.obj(nG, L1, L2, freq=1.0, theta=0.0, phi=0.0, verbose=0)

# Grid resolution for patterned layer
Nx = 100
Ny = 100
thickp = 0.5    # Layer thickness

# Add layers: vacuum + patterned + vacuum
obj.Add_LayerUniform(1.0, 1.0)       # Incident vacuum
obj.Add_LayerGrid(thickp, Nx, Ny)    # Patterned layer
obj.Add_LayerUniform(1.0, 1.0)       # Exit vacuum
```

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

### Add Uniform Layer to RCWA

Source: https://context7.com/weiliangjinca/grcwa/llms.txt

Add a uniform (homogeneous) dielectric layer to the RCWA structure. Layers are added sequentially from the incident side.

```python
import grcwa
import numpy as np

# Setup RCWA object
L1 = [1.5, 0]
L2 = [0, 1.5]
nG = 301
obj = grcwa.obj(nG, L1, L2, freq=1.0, theta=0.0, phi=0.0, verbose=0)

# Add uniform vacuum layer (incident medium)
thick0 = 1.0     # Thickness
ep0 = 1.0        # Dielectric constant (vacuum)
obj.Add_LayerUniform(thick0, ep0)

# Add uniform substrate layer
thickN = 1.0
epN = 2.25       # Glass substrate (n=1.5)
obj.Add_LayerUniform(thickN, epN)
```
Tokens:
Raw