MaterialProxy - yi-huang-1/torchrdit GitHub Wiki
Material Proxy Module
Overview
The torchrdit.material_proxy
module provides classes for loading, processing, and converting material data with appropriate unit handling for electromagnetic simulations. It serves as a foundation for the materials system in TorchRDIT.
Key Components
UnitConverter
A class for handling unit conversions for wavelength, frequency, and derived quantities:
- Converting between different length units
- Converting between different frequency units
- Converting between wavelength and frequency domains
MaterialDataProxy
A class implementing the proxy pattern for material data handling:
- Loading material data from files with different formats (eps, n/k)
- Processing data with appropriate unit conversions
- Extracting material properties at specific wavelengths
Usage Examples
# Basic unit conversion
from torchrdit.material_proxy import UnitConverter
converter = UnitConverter()
# Convert from nanometers to micrometers
wavelength_um = converter.convert_length(1550, 'nm', 'um')
print(f"1550 nm = {wavelength_um} μm") # 1550 nm = 1.55 μm
# Convert from frequency to wavelength
wavelength = converter.freq_to_wavelength(193.5, 'thz', 'um')
print(f"193.5 THz = {wavelength:.2f} μm") # 193.5 THz = 1.55 μm
# Loading material data
from torchrdit.material_proxy import MaterialDataProxy
import numpy as np
# Initialize proxy
proxy = MaterialDataProxy()
# Load data from file (wavelength-permittivity format with units in um)
si_data = proxy.load_data('Si_data.txt', 'wl-eps', 'um')
# Extract permittivity at specific wavelengths
wavelengths = np.array([1.3, 1.55, 1.7])
eps_real, eps_imag = proxy.extract_permittivity(si_data, wavelengths)
API Reference
Below is the complete API reference for the material_proxy module, automatically generated from the source code.
Table of Contents
torchrdit.material_proxy
Module for handling material data with unit awareness in TorchRDIT.
This module provides classes for loading, processing, and converting material data with appropriate unit handling for electromagnetic simulations. It serves as a foundation for the materials system in TorchRDIT, enabling support for different data formats, units, and conversions between frequency and wavelength domains.
The module implements a proxy pattern for material data handling, separating the concerns of data loading, unit conversion, and material representation. This allows for efficient handling of both dispersive (wavelength/frequency dependent) and non-dispersive materials.
Classes: UnitConverter: Handles all unit conversions for wavelength, frequency, and derived quantities. MaterialDataProxy: Loads and processes material data files with appropriate unit handling.
Examples:
# Basic unit conversion:
from torchrdit.material_proxy import UnitConverter
converter = UnitConverter()
# Convert from nanometers to micrometers
wavelength_um = converter.convert_length(1550, 'nm', 'um')
print(f"1550 nm = {wavelength_um} μm")
# 1550 nm = 1.55 μm
# Convert from frequency to wavelength
wavelength = converter.freq_to_wavelength(193.5, 'thz', 'um')
print(f"193.5 THz = {wavelength:.2f} μm")
# 193.5 THz = 1.55 μm
# Loading material data:
from torchrdit.material_proxy import MaterialDataProxy
import numpy as np
# Load silicon data from file
proxy = MaterialDataProxy()
# File contains wavelength (um) and permittivity data
si_data = proxy.load_data('Si_data.txt', 'wl-eps', 'um')
# Extract permittivity at specific wavelengths
wavelengths = np.array([1.3, 1.55, 1.7])
eps_real, eps_imag = proxy.extract_permittivity(si_data, wavelengths)
Keywords: material data, unit conversion, wavelength, frequency, permittivity, material loading, dispersive materials, unit awareness, proxy pattern
UnitConverter Objects
class UnitConverter()
Handles unit conversions for wavelength, frequency, and derived quantities.
This class provides a centralized system for handling unit conversions in TorchRDIT, particularly for wavelength and frequency units. It validates unit specifications, converts between different units of the same type, and provides utilities for converting between frequency and wavelength domains.
The UnitConverter maintains dictionaries of supported units and their conversion factors, enabling consistent unit handling throughout the TorchRDIT package.
Attributes:
_length_units
dict - Dictionary of length unit conversion factors._freq_units
dict - Dictionary of frequency unit conversion factors.
Examples:
from torchrdit.material_proxy import UnitConverter
converter = UnitConverter()
# Length conversion
print(converter.convert_length(1.0, 'mm', 'um'))
# 1000.0
# Frequency conversion
print(converter.convert_frequency(1.0, 'ghz', 'mhz'))
# 1000.0
# Convert from frequency to wavelength
print(converter.freq_to_wavelength(200, 'thz', 'nm'))
# 1499.0
# Convert from wavelength to frequency
print(converter.wavelength_to_freq(1.55, 'um', 'thz'))
# 193.5
Keywords: unit conversion, wavelength, frequency, length units, frequency units, unit validation, unit transformation, electromagnetic units
__init__
def __init__()
Initialize the UnitConverter with supported units from constants.
Initializes the converter with dictionaries of supported length and frequency units from the constants module.
Keywords: initialization, unit converter creation
validate_units
def validate_units(unit, unit_type)
Validate that a unit string is recognized and supported.
This method checks if the provided unit string is valid for the specified unit type (length or frequency). It returns the lowercase version of the unit string if valid, making subsequent operations case-insensitive.
Arguments:
unit
str - Unit identifier to validate (e.g., 'nm', 'ghz').unit_type
str - Type of unit ('length' or 'frequency').
Returns:
str
- Lowercase validated unit string.
Raises:
ValueError
- If the unit is not recognized for the specified type.
Examples:
from torchrdit.material_proxy import UnitConverter
converter = UnitConverter()
print(converter.validate_units('um', 'length'))
# 'um'
print(converter.validate_units('THz', 'frequency'))
# 'thz'
# This would raise an error
try:
print(converter.validate_units('invalid', 'length'))
except ValueError as e:
print(f"Error: {e}")
# Error: Unknown length unit: invalid. Valid units: [...]
Keywords: unit validation, error checking, case normalization
convert_length
def convert_length(value, from_unit, to_unit)
Convert values between different length units.
This method converts a length value from one unit to another using the conversion factors defined in the length units dictionary. Both units are validated before conversion.
Arguments:
value
float or array - Length value(s) to convert.from_unit
str - Source length unit (e.g., 'nm', 'um', 'mm').to_unit
str - Target length unit (e.g., 'nm', 'um', 'mm').
Returns:
float or array: Converted length value(s) in the target unit.
Examples:
from torchrdit.material_proxy import UnitConverter
converter = UnitConverter()
print(converter.convert_length(1550, 'nm', 'um'))
# 1.55
print(converter.convert_length(0.001, 'meter', 'mm'))
# 1.0
# Converting an array of values
import numpy as np
wavelengths_nm = np.array([1310, 1550, 1625])
print(converter.convert_length(wavelengths_nm, 'nm', 'um'))
# array([1.31, 1.55, 1.625])
Keywords: length conversion, unit transformation, dimension scaling
convert_frequency
def convert_frequency(value, from_unit, to_unit)
Convert values between different frequency units.
This method converts a frequency value from one unit to another using the conversion factors defined in the frequency units dictionary. Both units are validated before conversion.
Arguments:
value
float or array - Frequency value(s) to convert.from_unit
str - Source frequency unit (e.g., 'thz', 'ghz', 'mhz').to_unit
str - Target frequency unit (e.g., 'thz', 'ghz', 'mhz').
Returns:
float or array: Converted frequency value(s) in the target unit.
Examples:
from torchrdit.material_proxy import UnitConverter
converter = UnitConverter()
print(converter.convert_frequency(1, 'thz', 'ghz'))
# 1000.0
print(converter.convert_frequency(2.5, 'ghz', 'mhz'))
# 2500.0
# Converting an array of values
import numpy as np
frequencies_ghz = np.array([100, 200, 300])
print(converter.convert_frequency(frequencies_ghz, 'ghz', 'thz'))
# array([0.1, 0.2, 0.3])
Keywords: frequency conversion, unit transformation, scale conversion
freq_to_wavelength
def freq_to_wavelength(freq, freq_unit, wl_unit)
Convert from frequency to wavelength.
This method converts frequency values to their corresponding wavelength values using the physical relationship λ = c/f, with appropriate unit conversions. Uses the speed of light constant from the constants module.
Arguments:
freq
float or array - Frequency value(s) to convert.freq_unit
str - Unit of the input frequency (e.g., 'thz', 'ghz').wl_unit
str - Desired output wavelength unit (e.g., 'um', 'nm').
Returns:
float or array: Wavelength value(s) in the target unit.
Examples:
from torchrdit.material_proxy import UnitConverter
converter = UnitConverter()
# Convert 193.5 THz to wavelength in μm
print(converter.freq_to_wavelength(193.5, 'thz', 'um'))
# 1.55
# Convert 100 GHz to wavelength in mm
print(converter.freq_to_wavelength(100, 'ghz', 'mm'))
# 3.0
# Converting an array of frequencies
import numpy as np
freqs_thz = np.array([193.5, 230.0, 350.0])
print(converter.freq_to_wavelength(freqs_thz, 'thz', 'um'))
# array([1.55, 1.30, 0.86])
Keywords: frequency to wavelength, unit conversion, electromagnetic spectrum, physical relationship, speed of light
wavelength_to_freq
def wavelength_to_freq(wavelength, wl_unit, freq_unit)
Convert from wavelength to frequency.
This method converts wavelength values to their corresponding frequency values using the physical relationship f = c/λ, with appropriate unit conversions. Uses the speed of light constant from the constants module.
Arguments:
wavelength
float or array - Wavelength value(s) to convert.wl_unit
str - Unit of the input wavelength (e.g., 'um', 'nm').freq_unit
str - Desired output frequency unit (e.g., 'thz', 'ghz').
Returns:
float or array: Frequency value(s) in the target unit.
Examples:
from torchrdit.material_proxy import UnitConverter
converter = UnitConverter()
# Convert 1.55 μm to frequency in THz
print(converter.wavelength_to_freq(1.55, 'um', 'thz'))
# 193.5
# Convert 3 mm to frequency in GHz
print(converter.wavelength_to_freq(3, 'mm', 'ghz'))
# 100.0
# Converting an array of wavelengths
import numpy as np
wavelengths_um = np.array([1.31, 1.55, 2.0])
print(converter.wavelength_to_freq(wavelengths_um, 'um', 'thz'))
# array([229.0, 193.5, 150.0])
Keywords: wavelength to frequency, unit conversion, electromagnetic spectrum, physical relationship, speed of light
MaterialDataProxy Objects
class MaterialDataProxy()
Proxy for loading and processing material property data with unit awareness.
This class implements the proxy pattern for handling material data loading and processing in TorchRDIT. It provides methods for loading material data from files with different formats and units, and extracting specific property values at desired wavelengths. The class handles unit conversions internally, providing a consistent interface regardless of the source data format.
MaterialDataProxy supports multiple data formats including:
- 'freq-eps': Frequency and complex permittivity data
- 'wl-eps': Wavelength and complex permittivity data
- 'freq-nk': Frequency and complex refractive index (n, k) data
- 'wl-nk': Wavelength and complex refractive index (n, k) data
This class is typically used internally by the MaterialClass to load and process dispersive material data, but can also be used directly for material data analysis and manipulation.
Attributes:
_converter
UnitConverter - Unit converter instance for handling unit transformations.
Examples:
from torchrdit.material_proxy import MaterialDataProxy
proxy = MaterialDataProxy()
# Load permittivity data from a file with wavelength in μm
data = proxy.load_data('materials/SiO2.txt', 'wl-eps', 'um')
# Get the first few rows of the loaded and converted data
print(f"Wavelength (μm) | ε_real | ε_imag")
for i in range(min(3, data.shape[0])):
print(f"{data[i, 0]:.2f} | {data[i, 1]:.2f} | {data[i, 2]:.4f}")
# Extract permittivity at specific wavelengths
import numpy as np
wavelengths = np.array([1.31, 1.55, 1.85])
eps_real, eps_imag = proxy.extract_permittivity(data, wavelengths)
for wl, er, ei in zip(wavelengths, eps_real(wavelengths), eps_imag(wavelengths)):
print(f"λ={wl}μm: ε={er:.4f}{'-' if ei < 0 else '+'}{abs(ei):.4f}j")
Keywords: material data, data loading, proxy pattern, permittivity, refractive index, material properties, data processing, unit conversion, dispersive materials, optical constants, electromagnetic properties
__init__
def __init__(unit_converter=None)
Initialize the MaterialDataProxy with an optional custom unit converter.
Arguments:
unit_converter
UnitConverter, optional - Custom unit converter instance to use for unit transformations. If None, a new UnitConverter instance is created. Default is None.
Examples:
from torchrdit.material_proxy import MaterialDataProxy
# Create with default unit converter
proxy = MaterialDataProxy()
# Create with custom unit converter
from torchrdit.material_proxy import UnitConverter
converter = UnitConverter()
proxy = MaterialDataProxy(unit_converter=converter)
Keywords: initialization, proxy creation, unit converter
load_data
def load_data(file_path, data_format, data_unit, target_unit="um")
Load and process material data from a file with unit conversion.
This method loads material property data from a file, processes it according to the specified format, and converts it to a standardized representation with the target wavelength unit. It handles different data formats including permittivity (eps) and refractive index (n,k) data, in both frequency and wavelength domains.
The returned data is always in the format [wavelength, eps_real, eps_imag], regardless of the input format, with wavelength values in the target_unit.
Arguments:
file_path
str - Path to the data file containing material properties.data_format
str - Format of the data file. Must be one of:'freq-eps'
- Frequency and complex permittivity'wl-eps'
- Wavelength and complex permittivity'freq-nk'
- Frequency and complex refractive index'wl-nk'
- Wavelength and complex refractive indexdata_unit
str - Unit of the first column (frequency or wavelength). For wavelength: 'nm', 'um', etc. For frequency: 'thz', 'ghz', etc.target_unit
str, optional - Length unit to convert wavelength data to. Default is 'um' (micrometers).
Returns:
numpy.ndarray
- Array with shape (N, 3) containing [wavelength, eps_real, eps_imag] for each of N data points, with wavelength values in target_unit and sorted in ascending order.
Raises:
ValueError
- If the file doesn't exist, the format is invalid, or other errors occur during loading or processing.
Examples:
from torchrdit.material_proxy import MaterialDataProxy
proxy = MaterialDataProxy()
# Load wavelength-permittivity data (wavelengths in nm)
silica_data = proxy.load_data('SiO2.txt', 'wl-eps', 'nm', 'um')
print(f"Loaded {silica_data.shape[0]} data points")
# Load frequency-based n,k data (frequencies in THz)
silicon_data = proxy.load_data('Si.txt', 'freq-nk', 'thz', 'um')
print(f"Wavelength range: {silicon_data[:, 0].min():.2f} - "
f"{silicon_data[:, 0].max():.2f} μm")
Keywords: data loading, file reading, unit conversion, data processing, material properties, permittivity, refractive index
extract_permittivity
def extract_permittivity(data, wavelengths, fit_order=10)
Extract permittivity values at specific wavelengths using polynomial fitting.
This method interpolates/extrapolates permittivity values for specified wavelengths from a set of material data. It uses polynomial fitting to generate smooth curves for both real and imaginary parts of the permittivity.
Arguments:
data
numpy.ndarray - Material data from load_data with shape (N, 3).wavelengths
numpy.ndarray - Target wavelengths to extract permittivity for.fit_order
int, optional - Polynomial fit order. Higher values provide more accurate fits for complex curves but may lead to overfitting. Default is 10.
Returns:
tuple
- (real_permittivity, imaginary_permittivity) at requested wavelengths. Each is a numpy.ndarray with the same shape as the input wavelengths.
Examples:
import numpy as np
from torchrdit.material_proxy import MaterialDataProxy
proxy = MaterialDataProxy()
# Load material data
data = proxy.load_data('SiO2.txt', 'wl-eps', 'um')
# Extract permittivity at specific wavelengths
operating_wl = np.array([1.31, 1.55, 1.7])
eps_real, eps_imag = proxy.extract_permittivity(data, operating_wl)
# Display the results
for wl, er, ei in zip(operating_wl, eps_real(operating_wl), eps_imag(operating_wl)):
print(f"At {wl} μm: ε = {er:.4f} {ei:.4f}j")
Keywords: permittivity extraction, interpolation, polynomial fitting, material properties, dispersion, wavelength-dependent properties