Builder - yi-huang-1/torchrdit GitHub Wiki

Table of Contents

torchrdit.builder

flip_config

def flip_config(config: Dict[str, Any]) -> Dict[str, Any]

Create a flipped version of the configuration with reversed layer stack.

This function creates a new configuration with the layer stack reversed and the transmission and reflection materials swapped. This is useful for simulating the same structure from the opposite direction.

Arguments:

  • config Dict[str, Any] - Original configuration dictionary.

Returns:

Dict[str, Any]: Flipped configuration with reversed layer stack and swapped transmission/reflection materials.

Examples:

original_config = {
    "layers": [{"material": "Air"}, {"material": "Si"}, {"material": "SiO2"}],
    "trn_material": "Air",
    "ref_material": "SiO2"
}
flipped = flip_config(original_config)
flipped["layers"]
# [{"material": "SiO2"}, {"material": "Si"}, {"material": "Air"}]
flipped["trn_material"]
# "SiO2"
flipped["ref_material"]
# "Air"

Keywords: configuration, flip, reverse, layer stack, transmission, reflection

SolverBuilder Objects

class SolverBuilder()

Builder for creating and configuring electromagnetic solver instances.

This class implements the Builder pattern for constructing and configuring RCWA and R-DIT solver instances. It provides a fluent interface with method chaining to set various solver parameters.

The SolverBuilder is the recommended way to create and configure solvers in the TorchRDIT package, allowing for a clean and expressive API.

Attributes:

Various internal attributes storing the configuration state.

Examples:

# Create a basic RCWA solver with default settings
from torchrdit.builder import SolverBuilder
from torchrdit.constants import Algorithm
solver = SolverBuilder().build()

# Create a more customized RCWA solver
solver = SolverBuilder() \
    .with_algorithm(Algorithm.RCWA) \
    .with_wavelengths(1.55) \
    .with_k_dimensions([5, 5]) \
    .with_device("cuda") \
    .build()

# Create an R-DIT solver with custom order
solver = SolverBuilder() \
    .with_algorithm(Algorithm.RDIT) \
    .with_rdit_order(8) \
    .build()

# Load configuration from a JSON file
solver = SolverBuilder().from_config("config.json").build()

Keywords: builder pattern, solver configuration, RCWA, R-DIT, electromagnetic solver

__init__

def __init__()

Initialize the builder with default values for all solver parameters.

with_algorithm

def with_algorithm(algorithm_type: Algorithm) -> "SolverBuilder"

Set the algorithm type for the solver.

Arguments:

  • algorithm_type Algorithm - The algorithm to use, either Algorithm.RCWA or Algorithm.RDIT.

Returns:

  • SolverBuilder - The builder instance for method chaining.

Examples:

from torchrdit.constants import Algorithm
builder = SolverBuilder().with_algorithm(Algorithm.RCWA)
builder = SolverBuilder().with_algorithm(Algorithm.RDIT)

Keywords: algorithm, RCWA, R-DIT, solver configuration

with_algorithm_instance

def with_algorithm_instance(algorithm: SolverAlgorithm) -> "SolverBuilder"

Set a specific algorithm instance directly.

This is an advanced method that allows directly setting a custom algorithm instance rather than using the built-in implementations.

Arguments:

  • algorithm SolverAlgorithm - A custom algorithm instance that implements the SolverAlgorithm interface.

Returns:

  • SolverBuilder - The builder instance for method chaining.

Examples:

# Advanced usage with custom algorithm
from torchrdit.constants import Algorithm
from torchrdit.builder import SolverBuilder
custom_algorithm = RCWAAlgorithm(None)  # Configure as needed
builder = SolverBuilder().with_algorithm_instance(custom_algorithm)

Keywords: custom algorithm, algorithm instance, advanced configuration

with_precision

def with_precision(precision: Precision) -> "SolverBuilder"

Set the numerical precision for computations.

Arguments:

  • precision Precision - The precision to use, either Precision.SINGLE for float32 or Precision.DOUBLE for float64.

Returns:

  • SolverBuilder - The builder instance for method chaining.

Examples:

from torchrdit.builder import SolverBuilder
from torchrdit.constants import Precision
# Use single precision (float32)
builder = SolverBuilder().with_precision(Precision.SINGLE)
# Use double precision (float64) for higher accuracy
builder = SolverBuilder().with_precision(Precision.DOUBLE)

Keywords: precision, float32, float64, numerical accuracy

with_wavelengths

def with_wavelengths(lam0: Union[float, np.ndarray]) -> "SolverBuilder"

Set the wavelengths for the solver to compute solutions at.

Arguments:

  • lam0 Union[float, np.ndarray] - The wavelength(s) to solve for. Can be a single value or an array of values for spectral calculations.

Returns:

  • SolverBuilder - The builder instance for method chaining.

Examples:

from torchrdit.builder import SolverBuilder
import numpy as np
# Set a single wavelength (1.55 μm)
builder = SolverBuilder().with_wavelengths(1.55)
# Set multiple wavelengths for spectral calculations
wavelengths = np.linspace(1.2, 1.8, 100)  # 100 points from 1.2 to 1.8 μm
builder = SolverBuilder().with_wavelengths(wavelengths)

Keywords: wavelength, spectral, optical frequency, electromagnetic spectrum

with_length_unit

def with_length_unit(unit: str) -> "SolverBuilder"

Set the length unit for all dimensional parameters.

Arguments:

  • unit str - The length unit to use (e.g., 'um', 'nm', 'mm').

Returns:

  • SolverBuilder - The builder instance for method chaining.

Examples:

from torchrdit.builder import SolverBuilder
# Set length unit to micrometers
builder = SolverBuilder().with_length_unit('um')
# Set length unit to nanometers
builder = SolverBuilder().with_length_unit('nm')

Keywords: length unit, dimensions, scale, micrometers, nanometers

with_real_dimensions

def with_real_dimensions(rdim: List[int]) -> "SolverBuilder"

Set the dimensions in real space for discretization.

Arguments:

  • rdim List[int] - The dimensions in real space as [height, width].

Returns:

  • SolverBuilder - The builder instance for method chaining.

Examples:

from torchrdit.builder import SolverBuilder
# Set real space dimensions to 512x512
builder = SolverBuilder().with_real_dimensions([512, 512])
# Set real space dimensions to 1024x1024 for higher resolution
builder = SolverBuilder().with_real_dimensions([1024, 1024])

Keywords: real dimensions, discretization, spatial resolution, grid size

with_k_dimensions

def with_k_dimensions(kdim: List[int]) -> "SolverBuilder"

Set the dimensions in k-space (Fourier space) for harmonics.

Arguments:

  • kdim List[int] - The dimensions in k-space as [height, width]. Higher values include more harmonics for better accuracy at the cost of computational complexity.

Returns:

  • SolverBuilder - The builder instance for method chaining.

Examples:

from torchrdit.builder import SolverBuilder
# Set k-space dimensions to 3x3 (9 harmonics)
builder = SolverBuilder().with_k_dimensions([3, 3])
# Set k-space dimensions to 5x5 (25 harmonics) for higher accuracy
builder = SolverBuilder().with_k_dimensions([5, 5])

Keywords: k-space, Fourier harmonics, diffraction orders, computational accuracy

with_materials

def with_materials(materials: List[Any]) -> "SolverBuilder"

Set the list of materials for the simulation.

Arguments:

  • materials List[Any] - List of material objects to use in the simulation.

Returns:

  • SolverBuilder - The builder instance for method chaining.

Examples:

# Set materials for the simulation
from torchrdit.utils import create_material
from torchrdit.builder import SolverBuilder
air = create_material(name="Air", permittivity=1.0)
silicon = create_material(name="Si", permittivity=12.0)
builder = SolverBuilder().with_materials([air, silicon])

Keywords: materials, permittivity, dielectric properties, optical materials

add_material

def add_material(material: Any) -> "SolverBuilder"

Add a single material to the materials list.

Arguments:

  • material Any - The material object to add to the simulation.

Returns:

  • SolverBuilder - The builder instance for method chaining.

Examples:

# Add materials one by one
from torchrdit.utils import create_material
from torchrdit.builder import SolverBuilder
builder = SolverBuilder()
builder.add_material(create_material(name="Air", permittivity=1.0))
builder.add_material(create_material(name="Si", permittivity=12.0))

Keywords: material, add material, permittivity, optical properties

with_trn_material

def with_trn_material(material: Union[str, Any]) -> "SolverBuilder"

Set the transmission material for the simulation.

The transmission material defines the material properties of the medium on the transmission side of the structure.

Arguments:

  • material Union[str, Any] - Either a material name (string) that exists in the material list, or a material object that will be added to the material list.

Returns:

  • SolverBuilder - The builder instance for method chaining.

Examples:

from torchrdit.builder import SolverBuilder
# Set transmission material by name (must already be in materials list)
builder = SolverBuilder().with_trn_material("Air")
# Set transmission material by object
from torchrdit.utils import create_material
air = create_material(name="Air", permittivity=1.0)
builder = SolverBuilder().with_trn_material(air)

Keywords: transmission material, output medium, optical interface

with_ref_material

def with_ref_material(material: Union[str, Any]) -> "SolverBuilder"

Set the reflection material (or incident material) for the simulation.

The reflection material (or incident material) defines the material properties of the medium on the reflection side (or incident side) of the structure.

Arguments:

  • material Union[str, Any] - Either a material name (string) that exists in the material list, or a material object that will be added to the material list.

Returns:

  • SolverBuilder - The builder instance for method chaining.

Examples:

from torchrdit.builder import SolverBuilder
# Set reflection material by name (must already be in materials list)
builder = SolverBuilder().with_ref_material("Si")
# Set reflection material by object
from torchrdit.utils import create_material
silicon = create_material(name="Si", permittivity=12.0)
builder = SolverBuilder().with_ref_material(silicon)

Keywords: reflection material, incident material, optical interface

with_lattice_vectors

def with_lattice_vectors(t1: torch.Tensor,
                         t2: torch.Tensor) -> "SolverBuilder"

Set the lattice vectors defining the unit cell geometry.

Arguments:

  • t1 torch.Tensor - First lattice vector.
  • t2 torch.Tensor - Second lattice vector.

Returns:

  • SolverBuilder - The builder instance for method chaining.

Examples:

# Set square lattice with 1 μm period
import torch
from torchrdit.builder import SolverBuilder
t1 = torch.tensor([1.0, 0.0](/yi-huang-1/torchrdit/wiki/1.0,-0.0))
t2 = torch.tensor([0.0, 1.0](/yi-huang-1/torchrdit/wiki/0.0,-1.0))
builder = SolverBuilder().with_lattice_vectors(t1, t2)
# Set rectangular lattice
t1 = torch.tensor([1.5, 0.0](/yi-huang-1/torchrdit/wiki/1.5,-0.0))
t2 = torch.tensor([0.0, 1.0](/yi-huang-1/torchrdit/wiki/0.0,-1.0))
builder = SolverBuilder().with_lattice_vectors(t1, t2)

Keywords: lattice vectors, unit cell, periodicity, photonic crystal

with_fff

def with_fff(use_fff: bool) -> "SolverBuilder"

Set whether to use Fast Fourier Factorization for improved convergence.

Fast Fourier Factorization (FFF) improves the convergence of the RCWA algorithm, especially for metallic structures and TM polarization.

Arguments:

  • use_fff bool - Whether to use Fast Fourier Factorization.

Returns:

  • SolverBuilder - The builder instance for method chaining.

Examples:

from torchrdit.builder import SolverBuilder
# Enable Fast Fourier Factorization (default)
builder = SolverBuilder().with_fff(True)
# Disable Fast Fourier Factorization
builder = SolverBuilder().with_fff(False)

Keywords: Fast Fourier Factorization, FFF, convergence, numerical stability

with_device

def with_device(device: Union[str, torch.device]) -> "SolverBuilder"

Set the computation device (CPU or GPU).

Arguments:

  • device Union[str, torch.device] - The device to use for computations, either as a string ('cpu', 'cuda', 'cuda:0', etc.) or as a torch.device.

Returns:

  • SolverBuilder - The builder instance for method chaining.

Examples:

from torchrdit.builder import SolverBuilder
# Use CPU for computations
builder = SolverBuilder().with_device('cpu')
# Use GPU for computations
builder = SolverBuilder().with_device('cuda')
# Use specific GPU
builder = SolverBuilder().with_device('cuda:1')

Keywords: device, CPU, GPU, CUDA, computation acceleration

with_rdit_order

def with_rdit_order(order: int) -> "SolverBuilder"

Set the R-DIT order for the R-DIT algorithm.

The R-DIT order determines the approximation used in the diffraction interface theory. Higher orders provide better accuracy at the cost of computational efficiency.

Notes:

This parameter is only used when the R-DIT algorithm is selected.

Arguments:

  • order int - The order of the R-DIT algorithm (typically 1-10). Higher values provide more accurate results.

Returns:

  • SolverBuilder - The builder instance for method chaining.

Examples:

# Use R-DIT algorithm with order 8
from torchrdit.constants import Algorithm
from torchrdit.builder import SolverBuilder
builder = SolverBuilder() \
    .with_algorithm(Algorithm.RDIT) \
    .with_rdit_order(8)

Keywords: R-DIT, order, approximation, accuracy, performance

add_layer

def add_layer(layer_config: Dict[str, Any]) -> "SolverBuilder"

Add a layer configuration to be added after solver creation.

Arguments:

  • layer_config Dict[str, Any] - Configuration dictionary for a layer, containing at minimum "material" and "thickness" keys.

Returns:

  • SolverBuilder - The builder instance for method chaining.

Examples:

from torchrdit.builder import SolverBuilder
# Add a homogeneous silicon layer
builder = SolverBuilder()
builder.add_layer({
    "material": "Si",
    "thickness": 0.5,
    "is_homogeneous": True
})
# Add a non-homogeneous (patterned) layer
builder.add_layer({
    "material": "SiO2",
    "thickness": 0.2,
    "is_homogeneous": False
})

Keywords: layer, material, thickness, homogeneous, patterned

from_config

def from_config(config: Union[str, Dict[str, Any]],
                flip: bool = False) -> "SolverBuilder"

Configure the builder from a JSON configuration file or dictionary.

This method allows loading all solver configuration from a JSON file or dictionary, which is useful for storing and sharing complex configurations.

Arguments:

  • config Union[str, Dict[str, Any]] - Either a path to a JSON configuration file or a configuration dictionary.
  • flip bool, optional - Whether to flip the configuration (reverse layer stack and swap transmission/reflection materials). Defaults to False.

Returns:

  • SolverBuilder - The builder instance for method chaining.

Examples:

from torchrdit.builder import SolverBuilder
# Load configuration from a JSON file
builder = SolverBuilder().from_config("config.json")
# Load and flip configuration (reverse layer stack)
builder = SolverBuilder().from_config("config.json", flip=True)
# Load from a dictionary
config_dict = {
    "algorithm": "RDIT",
    "wavelengths": [1.55],
    "kdim": [5, 5],
    "materials": {...},
    "layers": [...]
}
builder = SolverBuilder().from_config(config_dict)

Raises:

  • ValueError - If unknown configuration keys are detected.

    Keywords: configuration, JSON, file loading, serialization, flip

build

def build()

Build and return the configured solver instance.

This method creates a solver instance based on all the configuration parameters that have been set on the builder.

Returns:

Union[RCWASolver, RDITSolver]: The configured solver instance.

Examples:

from torchrdit.builder import SolverBuilder
from torchrdit.constants import Algorithm
# Build a basic RCWA solver
solver = SolverBuilder().with_algorithm(Algorithm.RCWA).build()
# Build a fully configured solver
solver = SolverBuilder() \
    .with_algorithm(Algorithm.RDIT) \
    .with_rdit_order(8) \
    .with_wavelengths([1.3, 1.4, 1.5, 1.6]) \
    .with_k_dimensions([5, 5]) \
    .with_device("cuda") \
    .build()

Keywords: build, create solver, instantiate, solver instance