Custom materials#
PyOptik can construct optical materials directly from measured arrays, CSV files, or dispersion coefficients. Custom materials support the same unit-aware calculations, interpolation policies, provenance fields, and YAML format as catalog materials.
Tabulated data from arrays#
Attach units to the wavelength axis and provide at least one of n or k.
The arrays must be one-dimensional, finite, equal in length, and strictly
increasing in strictly positive wavelength. Negative optical constants remain
representable; the configurable evaluation policy below controls diagnostics.
from TypedUnit import ureg
from PyOptik import TabulatedMaterial
sample = TabulatedMaterial.from_arrays(
"measured-sample",
[400, 500, 600] * ureg.nanometer,
n=[1.40, 1.45, 1.50],
k=[0.01, 0.02, 0.04],
reference="Laboratory measurement",
conditions={"temperature": "293 K"},
comments="Uncoated sample",
interpolation="pchip",
)
index = sample.compute_refractive_index(550 * ureg.nanometer)
sample.to_yaml("measured-sample.yml")
When wavelengths do not carry units, they are interpreted as micrometres by
from_arrays. Unit-bearing values are recommended.
CSV import#
from_csv expects a header row and uses the columns wavelength, n,
and k by default. Either optical-constant column may be omitted.
wavelength,n,k
400,1.40,0.01
500,1.45,0.02
600,1.50,0.04
sample = TabulatedMaterial.from_csv(
"measurement.csv",
wavelength_unit=ureg.nanometer,
reference="Laboratory measurement",
)
Use wavelength_column, n_column, and k_column when a file uses
different headers.
Formula materials#
Formula types 1 through 9 follow the RefractiveIndex.INFO definitions. Coefficient order therefore follows the selected upstream formula type.
from PyOptik import SellmeierMaterial
glass = SellmeierMaterial.from_coefficients(
"fitted-glass",
[0.1, 0.2, 0.3],
formula_type=1,
wavelength_range=[400, 900] * ureg.nanometer,
reference="Internal fit",
)
glass.to_yaml("fitted-glass.yml")
Typed documents and validation#
The lower-level parser returns an immutable MaterialDocument containing
typed formula or tabulated datasets and shared metadata. It is useful for
validation, inspection, and tools that do not need to evaluate a material.
from PyOptik import parse_material
document = parse_material("measured-sample.yml")
print(document.metadata.reference)
print(document.tabulated_datasets)
document.to_yaml("validated-copy.yml")
Malformed coefficient sets, invalid table shapes, non-finite values, unsorted
wavelengths, unsupported formula types, and malformed metadata raise
ValueError with source context. YAML export writes through a temporary file
and atomically replaces the destination after successful serialization.
Exporting numerical arrays#
wavelength, n, k = sample.to_arrays() returns independent arrays suitable
for numerical tools. Wavelengths carry micrometre units. Separate n and k grids
are combined within their overlapping range, including both bounds. Missing n
is represented by 1 and missing k by 0. Linear interpolation of these arrays
preserves the source curves inside the exported range. For pchip materials,
these are samples; linear interpolation does not preserve the cubic curve.
CSV columns may be absent, but empty cells in present columns raise
ValueError with their line number. Use missing_k=0.0 in from_csv
when empty extinction cells explicitly mean zero. Empty n cells always raise;
a missing first value never causes the remaining column to be discarded.
Formula wavelength bounds must also be strictly positive.
Physical validation policies#
Material evaluation and to_arrays default to validation="warn".
A MaterialValidationWarning reports nonpositive real refractive index or
negative extinction coefficient. With PyOptik’s n + i*k convention, positive
k describes absorption and negative k describes gain. Negative-index and active
materials remain supported through explicit allowances:
index = sample.compute_refractive_index(
wavelength=450 * ureg.nanometer,
validation="raise",
allow_negative_index=True,
allow_gain=True,
)
validation="ignore" suppresses these physical-assumption diagnostics;
"raise" turns them into ValueError. These options are also forwarded by
nk, n, k and the other evaluation helpers. Diagnostics occur when
values are evaluated or exported, not merely when data is loaded. Checks cover
only those samples; they do not prove causality or validity at every wavelength.
Nonempty, finite results and positive, finite wavelengths are required under
all policies, including "ignore". Dataset construction also rejects
nonfinite values and nonpositive wavelengths.
Standalone arrays can use the same implementation:
from PyOptik import validate_refractive_indices, validate_wavelengths
indices = validate_refractive_indices(
values=[1.45 + 0.01j, 1.50 + 0.02j],
policy="raise",
)
validate_wavelengths(wavelength=[400, 500] * ureg.nanometer)
validate_refractive_indices returns a complex NumPy array with the input
shape. Its default tolerance of 1e-12 applies only to tiny negative
extinction coefficients, and can be overridden with tolerance. Negative
real indices are never silently clamped. allow_negative_index=True also
permits zero real index, including purely imaginary indices. Empty samples,
nonfinite samples, invalid policies, and invalid tolerances always raise.