Materials

PyOptik 3.5.1 owns catalog discovery, file loading, metadata and physical validation. Use PyMieSim.from_pyoptik to copy a PyOptik model into a native solver material. Wavelength sweeps then run entirely in C++.

Catalog materials

Initialize the RefractiveIndex.INFO catalog with python -m PyOptik setup. Use explicit PyOptik catalog IDs to select a reproducible dataset:

import PyOptik
from PyMieSim import from_pyoptik

glass = from_pyoptik(
    PyOptik.load_material(name="specs/SCHOTT-optical/P-BK7")
)
silver = from_pyoptik(
    PyOptik.load_material(name="main/Ag/Johnson")
)
water = from_pyoptik(
    PyOptik.load_material(name="main/H2O/Daimon-19.0C"), medium=True
)

These are canonical catalog IDs, including the source page, rather than PyMieSim aliases. For example, SCHOTT P-BK7 is specs/SCHOTT-optical/P-BK7 and SCHOTT N-BK7 is specs/SCHOTT-optical/N-BK7; they are distinct datasets. Use PyOptik.find_materials for discovery and inspect a loaded model’s catalog_id and provenance for identity and source metadata. The native material name retains the catalog ID.

Additional datasets used in the examples are main/Au/Olmon-ev for gold, main/Al/Rakic for aluminium and main/SiO2/Malitson for fused silica. To use an existing snapshot elsewhere, pass data_root or a PyOptik.MaterialCatalog to PyOptik.load_material.

Measured materials

Create models through PyOptik’s public constructors:

from TypedUnit import ureg

source = PyOptik.TabulatedMaterial.from_arrays(
    name="measured", wavelength=[500, 600] * ureg.nanometer,
    n=[1.5, 1.6], k=[0.01, 0.02],
)
measured = from_pyoptik(source)

source = PyOptik.TabulatedMaterial.from_csv(
    path="measurement.csv", wavelength_unit=ureg.nanometer,
)
measured = from_pyoptik(source)

CSV columns and missing-value policies are configured directly in PyOptik. For example, missing_k=0.0 explicitly interprets blank extinction cells as zero. PyMieSim supplies no CSV/JSON parsers or column aliases.

Native solver constraints

Conversion requests strict PyOptik index validation by default. Use validate=False to skip index sign and passivity checks; finite data and positive wavelengths remain required by PyOptik. Surrounding media must always be lossless because their native representation stores real indices.

The solver supports linear tabulated interpolation and formula types 1, 2, 5 and 6. Separate n/k grids are exported by PyOptik on their common grid, retaining both linear responses. Cubic interpolation and unsupported formula types are rejected during conversion.

Native range checking defaults to strict. extrapolation="linear" permits table endpoint-slope extrapolation or analytical formula evaluation outside its source range. Formula index validation samples eight points within declared bounds and does not prove validity at every wavelength.

API

from_pyoptik(model, *, medium=False, extrapolation='error', validate=True)

Copy a PyOptik model into a native particle material or surrounding medium.

PyOptik owns loading and validation. This conversion requests strict index validation by default; validate=False skips sign and passivity checks. Media must be lossless under either setting. The solver supports linear tables and formula types 1, 2, 5 and 6. Range checking defaults to strict; extrapolation="linear" enables table endpoint slopes or formula evaluation beyond declared bounds. Formula validation samples eight points within declared bounds; it is not an exhaustive check of the curve.

class BaseMaterial

Bases: pybind11_object

get_refractive_index(self: PyMieSim.material.BaseMaterial, wavelength: object) → object

Retrieves the refractive index for a specific wavelength.

This method allows for querying the refractive index of the material at a specific wavelength. The wavelength is provided as an argument, and the method returns the corresponding refractive index value. If the material has not been initialized at the specified wavelength, an error will be raised.

Parameters:

wavelength (Quantity) – The wavelength at which to retrieve the refractive index, provided as a quantity with appropriate units (e.g., nanometers, micrometers).

initialize(self: PyMieSim.material.BaseMaterial, wavelength: object) → None

Initializes the material with a specific wavelength.

This method initializes the material by computing its refractive index at a given wavelength. The wavelength is provided as an argument, and the method converts it to meters before performing the initialization. After calling this method, the material’s refractive index will be available for retrieval.

Parameters:

wavelength (Quantity) – The wavelength at which to initialize the material, provided as a quantity with appropriate units (e.g., nanometers, micrometers).

class BaseMedium

Bases: pybind11_object

BaseMedium is an abstract base class representing a medium with a refractive index.

This class defines the interface for materials that have a refractive index, which can be initialized based on a wavelength and retrieved for specific wavelengths. The class provides methods to initialize the medium and to get the refractive index, which must be implemented by derived classes.

get_refractive_index(self: PyMieSim.material.BaseMedium, wavelength: object) → object

Retrieves the refractive index for a given wavelength.

This method takes a wavelength as input and returns the corresponding refractive index of the medium. The wavelength is expected to be a quantity that can be converted to meters, and the method computes the refractive index based on the initialized state of the medium.

initialize(self: PyMieSim.material.BaseMedium, wavelength: object) → None

Initializes the medium with a specific wavelength.

This method computes the refractive index of the medium based on the provided wavelength and sets the initialized state of the medium. The wavelength is expected to be a quantity that can be converted to meters, and the refractive index is computed accordingly.

class ConstantMaterial

Bases: BaseMaterial

get_refractive_index(self: PyMieSim.material.ConstantMaterial, wavelength: object) → object

Retrieves the refractive index for a specific wavelength.

This method allows for querying the refractive index of the ConstantMaterial instance at a specific wavelength. Since the material has a constant refractive index, the provided wavelength does not affect the returned value. However, this method is included for consistency with other material types and to allow for potential future extensions where the refractive index might depend on wavelength.

Parameters:

wavelength (Quantity) – The wavelength at which to retrieve the refractive index, provided as a quantity with appropriate units (e.g., nanometers, micrometers). This parameter is currently ignored since the refractive index is constant, but it is included for interface consistency.

property refractive_index

The constant refractive index of the material.

This property provides access to the constant refractive index of the ConstantMaterial instance. The refractive index is returned as a complex number, which can be used for calculations and analysis involving the material’s optical properties.

class ConstantMedium

Bases: BaseMedium

ConstantMedium represents a medium with a constant refractive index.

This class allows for the definition of a medium with a constant refractive index, which does not depend on the wavelength. The class provides methods to initialize the medium and to retrieve the refractive index, which will always return the same value regardless of the wavelength.

get_refractive_index(self: PyMieSim.material.ConstantMedium, wavelength: object) → object

Retrieves the refractive index for a given wavelength.

This method takes a wavelength as input and returns the constant refractive index of the medium. Since the refractive index is constant, the input wavelength does not affect the output value.

property refractive_index

The constant refractive index of the medium.

This property provides access to the constant refractive index value of the ConstantMedium instance, which can be used for analysis and representation purposes.

class SellmeierMaterial

Bases: BaseMaterial

SellmeierMaterial represents a material defined by the Sellmeier equation.

This class allows for the definition of a material whose refractive index is computed based on the Sellmeier equation, which is a common empirical relationship used to describe the wavelength dependence of the refractive index of transparent materials. The class provides methods to initialize the material and to get the refractive index for specific wavelengths.

property allow_extrapolation

Indicates whether extrapolation is allowed when computing the refractive index outside of the defined wavelength bounds.

This attribute provides access to the allow_extrapolation flag of the SellmeierMaterial instance, which determines whether the refractive index can be extrapolated beyond the specified wavelength bounds.

property coefficients

The coefficients used in the Sellmeier equation to compute the refractive index.

This attribute provides access to the coefficients of the SellmeierMaterial instance, which are used in the Sellmeier equation to calculate the refractive index based on the wavelength.

property formula_type

The type of Sellmeier formula to use for computing the refractive index.

This attribute provides access to the formula type of the SellmeierMaterial instance, which determines the specific Sellmeier equation used to calculate the refractive index.

get_refractive_index(self: PyMieSim.material.SellmeierMaterial, wavelength: object) → object

Retrieves the refractive index for a given wavelength.

This method takes a wavelength as input and returns the corresponding refractive index of the material based on the Sellmeier equation. The wavelength is expected to be a quantity that can be converted to meters, and the method computes the refractive index accordingly.

property name

The name of the material.

This attribute provides access to the name of the SellmeierMaterial instance, which can be used for identification and representation purposes.

property wavelength_bound

The wavelength bounds for which the Sellmeier equation is valid.

This property provides access to the wavelength bounds of the SellmeierMaterial instance, which indicate the range of wavelengths (in meters) for which the Sellmeier equation is applicable. The bounds are returned as a quantity with units of meters.

class SellmeierMedium

Bases: BaseMedium

SellmeierMedium represents a medium whose refractive index is computed using a Sellmeier formula.

The Sellmeier formula is an empirical relationship that describes how the refractive index of a material varies with wavelength. It is commonly used in optics to model the dispersion of light in transparent materials.

The class provides methods to initialize the medium with specific parameters and to compute the refractive index for given wavelengths. It also includes properties to access the material’s name, coefficients, formula type, and wavelength bounds.

property allow_extrapolation

Whether to allow extrapolation outside the wavelength bounds.

This property indicates whether the SellmeierMedium should allow extrapolation of the refractive index calculation beyond the specified wavelength bounds. If set to True, the medium will provide refractive index values even for wavelengths outside the defined range, which may lead to less accurate results. If set to False, an error will be raised when attempting to calculate the refractive index for out-of-bounds wavelengths.

property coefficients

The coefficients used in the Sellmeier formula.

This property provides access to the coefficients of the Sellmeier medium, which are used in the Sellmeier formula to calculate the refractive index. The coefficients are typically provided as a list of floating-point numbers.

property formula_type

The type of Sellmeier formula to use.

This property indicates the specific type of Sellmeier formula that should be applied when calculating the refractive index. Common types include 1, 2, 5, and 6, each corresponding to a different mathematical form of the Sellmeier equation.

get_refractive_index(self: PyMieSim.material.SellmeierMedium, wavelength: object) → object

Computes the refractive index for a given wavelength.

This method calculates the refractive index of the SellmeierMedium at a specified wavelength using the defined Sellmeier formula and coefficients. The input wavelength should be provided as a quantity with units (e.g., using Pint), and the method will handle the conversion to meters internally. The output is the computed refractive index, which may be a complex number depending on the material properties.

Parameters:

wavelength (Quantity) – The wavelength at which to compute the refractive index. This should be a quantity with appropriate units (e.g., nanometers, micrometers, etc.) that can be converted to meters.

property name

The name of the Sellmeier medium.

This property provides access to the name of the Sellmeier medium, which is a string identifier for the material. The name can be used for reference and identification purposes when working with multiple materials in simulations or calculations.

property wavelength_bound

The wavelength bounds for the Sellmeier formula.

This property provides access to the lower and upper bounds of the wavelength range for which the Sellmeier formula is valid. The bounds are returned as a list of two floating-point numbers, representing the minimum and maximum wavelengths in meters. If no bounds were specified during initialization, this property will return an empty list.

class TabulatedMaterial

Bases: BaseMaterial

TabulatedMaterial represents a material defined by tabulated refractive index data.

This class allows for the definition of a material whose refractive index is defined by tabulated data, which consists of specific wavelength values and their corresponding refractive indices. The class provides methods to initialize the material, retrieve the refractive index for specific wavelengths, and access the material’s properties such as its name, the wavelengths for which data is available, and whether extrapolation is allowed when querying outside of the defined wavelength range.

property allow_extrapolation

Indicates whether extrapolation is allowed when computing the refractive index outside of the defined wavelength range.

This attribute indicates whether the TabulatedMaterial instance allows for extrapolation when querying the refractive index for wavelengths that fall outside of the defined range of wavelengths. If allow_extrapolation is set to True, the material will provide an extrapolated refractive index value based on the available data; if set to False, an error will be raised when attempting to query outside of the defined wavelength range.

get_refractive_index(self: PyMieSim.material.TabulatedMaterial, wavelength: object) → object

Retrieves the refractive index for a specific wavelength.

This method allows for querying the refractive index of the TabulatedMaterial instance at a specific wavelength. The wavelength is provided as an argument, and the method returns the corresponding refractive index value. If the wavelength falls outside of the defined range and allow_extrapolation is set to False, an error will be raised.

property name

The name of the material.

This attribute holds the name of the TabulatedMaterial instance, which can be used for identification and representation purposes.

property refractive_indices

The refractive indices corresponding to the provided wavelengths.

This property provides access to the refractive index values that correspond to the wavelengths defined in the wavelengths property. The refractive indices are returned as a list of complex values, which can be used for analysis and interpolation of the material’s optical properties.

property wavelengths

The wavelengths for which the refractive index data is provided.

This property provides access to the wavelengths (in meters) for which the refractive index data of the TabulatedMaterial instance is defined. The wavelengths are returned as a list of values with appropriate units.

class TabulatedMedium

Bases: BaseMedium

TabulatedMedium represents a medium whose refractive index is defined by tabulated data.

This class allows for the definition of a medium based on tabulated values of refractive index at specific wavelengths. The refractive index can be interpolated for wavelengths within the range of the provided data, and optionally extrapolated outside that range if allowed. The class provides methods to initialize the medium and to retrieve the refractive index for given wavelengths.

property allow_extrapolation

Indicates whether extrapolation of the refractive index is allowed.

This property indicates whether the TabulatedMedium instance allows for extrapolation of the refractive index values outside the range of the provided wavelengths. If set to True, the get_refractive_index method will return extrapolated values for wavelengths outside the data range; if False, it will raise an error for such cases.

get_refractive_index(self: PyMieSim.material.TabulatedMedium, wavelength: object) → object

Retrieves the refractive index for a given wavelength.

This method takes a wavelength as input and returns the corresponding refractive index. If the wavelength is within the range of the provided data, it will return an interpolated value. If the wavelength is outside the range and extrapolation is allowed, it will return an extrapolated value; otherwise, it will raise an error.

Parameters:

wavelength (float) – The wavelength for which to retrieve the refractive index, in meters.

Returns:

The refractive index corresponding to the given wavelength.

Return type:

complex

property name

The name of the tabulated medium.

This property provides access to the name of the TabulatedMedium instance, which can be used for identification and representation purposes.

property refractive_indices

The refractive index values corresponding to the wavelengths.

This property returns a list of complex refractive index values that correspond to the wavelengths provided in the wavelengths property. These values can be used for interpolation and analysis of the medium’s optical properties.

property wavelengths

The wavelengths corresponding to the tabulated refractive index values.

This property returns a list of wavelengths for which the refractive index values are provided. The wavelengths are returned in meters, and can be used to understand the range of data available for the TabulatedMedium.