`MaterialFile`#

class ansys.speos.core.input_files.material.MaterialFile(description='Optical Glass', material_type=MaterialType.isotropic, dispersion=None, absorption_wavelengths=None, absorption_values=None, measured_concentration=1.0, user_concentration=1.0, scattering_wavelengths=None, scattering_values=None, scattering=None, axis_j=_DEFAULT_AXIS_J, axis_k=_DEFAULT_AXIS_K, absorption_values_b=None, absorption_values_c=None, fluorescent_pigments=None)#

Bases: ansys.speos.core.input_files._base.SpeosTextFileFormat

Speos *.material file, holding the volume optical properties of a body.

The file always describes how the refractive index and the absorption vary with the wavelength. Setting MaterialFile.scattering adds a volume scattering block, which turns the file into the scattering flavor of the format.

MaterialFile.material_type selects the flavor of the format, and with it the models MaterialFile.dispersion accepts. A metallic material holds nothing but the complex refractive index of the metal, while a birefringent one holds an index per axis, the orientation of these axes and an absorption curve per axis.

Parameters:

descriptionstr, optional: Free text written on the second line of the file. By default, "Optical Glass"
material_typeMaterialType, optional: Type of material. By default, MaterialType.isotropic.
dispersionUnion[MaterialDispersion, MaterialBirefringence, MaterialMetallicCurve], optional: How the refractive index varies with the wavelength. A metallic material needs a ansys.speos.core.input_files.material.MaterialMetallicCurve and a birefringent one needs one of the ansys.speos.core.input_files.material.MaterialBirefringence models. By default, a ansys.speos.core.input_files.material.MaterialDispersionCurve model with its default index curve.
absorption_wavelengthsList[float], optional: Wavelengths of the absorption curve, in nm. Left empty by a metallic material, whose extinction coefficient already holds the absorption. By default, [486.0, 532.0, 643.0], or [] for a metallic material.
absorption_valuesList[float], optional: Absorption coefficient at each wavelength, in mm-1. For a birefringent material, the absorption along the a axis. By default, [0.0, 0.0, 0.0], or [] for a metallic material.
measured_concentrationfloat, optional: Concentration the absorption curve was measured at. By default, 1.0.
user_concentrationfloat, optional: Concentration the absorption curve is scaled to. By default, 1.0.
scattering_wavelengthsList[float], optional: Wavelengths of the diffusion curve, in nm. By default, [486.0, 532.0, 643.0] when scattering is given, [] otherwise.
scattering_valuesList[float], optional: Diffusion coefficient at each wavelength, in mm-1. By default, 0.1 at each default diffusion wavelength when scattering is given, [] otherwise.
scatteringOptional[VolumeScattering], optional: Scattering phase function. By default, None, which writes a non-scattering material.
axis_jSequence[float], optional: Direction of the b axis of a birefringent material. Ignored by the other flavors. By default, [1.0, 0.0, 0.0].
axis_kSequence[float], optional: Direction of the c axis of a birefringent material. Ignored by the other flavors. By default, [0.0, 1.0, 0.0].
absorption_values_bList[float], optional: Absorption of a birefringent material along its b axis, one value per wavelength of the absorption curve. By default, 0.0 per absorption wavelength for a birefringent material, [] otherwise.
absorption_values_cList[float], optional: Absorption of a birefringent material along its c axis, one value per wavelength of the absorption curve. By default, 0.0 per absorption wavelength for a birefringent material, [] otherwise.
fluorescent_pigmentsSequence[FluorescentPigment], optional: Dye entries used by a fluorescent material. By default, no dyes are included; at least one must be added before saving.

Parameters:

description (str)
material_type (MaterialType)
dispersion (Union[MaterialDispersion, MaterialBirefringence, MaterialMetallicCurve, None])
absorption_wavelengths (List[float] | None)
absorption_values (List[float] | None)
measured_concentration (float)
user_concentration (float)
scattering_wavelengths (List[float] | None)
scattering_values (List[float] | None)
scattering (Optional[VolumeScattering])
axis_j (Sequence[float])
axis_k (Sequence[float])
absorption_values_b (List[float] | None)
absorption_values_c (List[float] | None)
fluorescent_pigments (Sequence[ansys.speos.core.input_files.fluorescence.FluorescentPigment] | None)

Notes

Called without arguments, the constructor creates an isotropic optical glass of index 1.5 that neither absorbs nor scatters light. The defaults of the curves depend on material_type and scattering only so that each flavor stays valid; a fluorescent material defaults to the Speos editor’s description and empty dye list, which must be populated before saving. The default dispersion model is always an index curve, so pass a matching model for a metallic or birefringent material.

Setters validate candidate data without partially updating the material. List getters return copies; dispersion and phase models remain shared with validated properties. Empty columns permit staged construction, while MaterialFile.validate() and save() require complete data and recheck shared child models. To resize a curve, clear all dependent value columns before changing its wavelengths, then repopulate the columns. Likewise, clear all phase parameter columns before changing phase wavelengths. To change between isotropic, metallic and birefringent flavors, construct a new material with the matching dispersion model rather than changing the flavor in place.

Examples

>>> from ansys.speos.core.input_files.material import MaterialFile, MaterialConstringence
>>> MaterialFile(
...     description="PMMA",
...     dispersion=MaterialConstringence(constringence=57.2, index=1.49),
...     absorption_wavelengths=[486.0, 643.0],
...     absorption_values=[0.0001, 0.0005],
... ).save("pmma.material")

Overview#

Methods

validate

Check the material against the constraints of the *.material format.

Properties

`description`	Single-line description.
`absorption_wavelengths`	Absorption wavelengths in nm, returned as a copy.
`absorption_values`	Absorption coefficients in mm-1, returned as a copy.
`measured_concentration`	Concentration at which absorption was measured.
`user_concentration`	Concentration to which absorption is scaled.
`scattering_wavelengths`	Diffusion wavelengths in nm, returned as a copy.
`scattering_values`	Diffusion coefficients in mm-1, returned as a copy.
`scattering`	Volume scattering phase function.
`axis_j`	Direction of the b axis, returned as a copy.
`axis_k`	Direction of the c axis, returned as a copy.
`absorption_values_b`	Absorption coefficients along b, returned as a copy.
`absorption_values_c`	Absorption coefficients along c, returned as a copy.
`fluorescent_pigments`	Fluorescent dye entries, returned as a copied list.
`material_type`	Material flavor matching the dispersion model.
`dispersion`	Dispersion model of this material flavor.

Attributes

`EXTENSION`	Usual file extension of the format.
`HEADER`	First line of the file. Empty when the format has no header line.
`HEADER_PREFIX`	Version-agnostic start of `HEADER`, used to validate a file being read.
`ISOTROPIC`	Material type of the default flavor of the format.
`METALLIC`	Material type of the metallic flavor of the format.
`BIREFRINGENT`	Material type of the birefringent flavor of the format.
`FLUORESCENT`	Material type of the fluorescent flavor of the format.
`DISPERSIONS`	Dispersion models the file can hold.
`BIREFRINGENT_DISPERSIONS`	Dispersion models a birefringent material can hold.
`SCATTERINGS`	Scattering phase functions the file can hold.

Import detail#

from ansys.speos.core.input_files.material import MaterialFile

Property detail#

property MaterialFile.description: str#

Single-line description.

Parameters:

valuestr: New free text written on the second line of the file.

Returns:

str: Free text written after the header.

property MaterialFile.absorption_wavelengths: List[float]#

Absorption wavelengths in nm, returned as a copy.

Parameters:

valuesList[float]: New wavelengths of the absorption curve, in nm. Left empty by a metallic material, whose extinction coefficient already holds the absorption.

Returns:

List[float]: Finite wavelengths.

property MaterialFile.absorption_values: List[float]#

Absorption coefficients in mm-1, returned as a copy.

Parameters:

valuesList[float]: New absorption coefficient at each wavelength, in mm-1. For a birefringent material, the absorption along the a axis.

Returns:

List[float]: Finite coefficients, along the a axis for a birefringent material.

property MaterialFile.measured_concentration: float#

Concentration at which absorption was measured.

Parameters:

valuefloat: New concentration the absorption curve was measured at.

Returns:

float: Finite concentration.

property MaterialFile.user_concentration: float#

Concentration to which absorption is scaled.

Parameters:

valuefloat: New concentration the absorption curve is scaled to.

Returns:

float: Finite concentration.

property MaterialFile.scattering_wavelengths: List[float]#

Diffusion wavelengths in nm, returned as a copy.

Parameters:

valuesList[float]: New wavelengths of the diffusion curve, in nm.

Returns:

List[float]: Finite wavelengths.

property MaterialFile.scattering_values: List[float]#

Diffusion coefficients in mm-1, returned as a copy.

Parameters:

valuesList[float]: New diffusion coefficient at each wavelength, in mm-1.

Returns:

List[float]: Finite coefficients.

property MaterialFile.scattering: VolumeScattering | None#

Volume scattering phase function.

Parameters:

valueOptional[VolumeScattering]: New scattering phase function.

Returns:

Optional[VolumeScattering]: Shared phase model, or None for a nonscattering material.

property MaterialFile.axis_j: List[float]#

Direction of the b axis, returned as a copy.

Parameters:

valuesSequence[float]: New direction of the b axis of a birefringent material. Ignored by the other flavors.

Returns:

List[float]: Three finite coordinates.

property MaterialFile.axis_k: List[float]#

Direction of the c axis, returned as a copy.

Parameters:

valuesSequence[float]: New direction of the c axis of a birefringent material. Ignored by the other flavors.

Returns:

List[float]: Three finite coordinates.

property MaterialFile.absorption_values_b: List[float]#

Absorption coefficients along b, returned as a copy.

Parameters:

valuesList[float]: New absorption of a birefringent material along its b axis, one value per wavelength of the absorption curve.

Returns:

List[float]: Finite coefficients in mm-1.

property MaterialFile.absorption_values_c: List[float]#

Absorption coefficients along c, returned as a copy.

Parameters:

valuesList[float]: New absorption of a birefringent material along its c axis, one value per wavelength of the absorption curve.

Returns:

List[float]: Finite coefficients in mm-1.

property MaterialFile.fluorescent_pigments: List[ansys.speos.core.input_files.fluorescence.FluorescentPigment]#

Fluorescent dye entries, returned as a copied list.

Parameters:

valuesSequence[FluorescentPigment]: New dye entries. Only fluorescent materials can contain dyes.

Returns:

List[FluorescentPigment]: Dye entries whose nested models remain shared and editable.

property MaterialFile.material_type: MaterialType#

Material flavor matching the dispersion model.

Parameters:

valueMaterialType: New type of material.

Returns:

MaterialType: Isotropic, metallic, birefringent, or fluorescent.

Notes

Construct a new material to switch to a flavor requiring another dispersion type.

property MaterialFile.dispersion: MaterialDispersion | MaterialBirefringence | MaterialMetallicCurve#

Dispersion model of this material flavor.

Parameters:

valueUnion[MaterialDispersion, MaterialBirefringence, MaterialMetallicCurve]: New how the refractive index varies with the wavelength. A metallic material needs a ansys.speos.core.input_files.material.MaterialMetallicCurve and a birefringent one needs one of the ansys.speos.core.input_files.material.MaterialBirefringence models.

Returns:

Union[MaterialDispersion, MaterialBirefringence, MaterialMetallicCurve]: Shared model with locally validated properties.

Attribute detail#

MaterialFile.EXTENSION = '.material'#: Usual file extension of the format.

MaterialFile.HEADER = 'OPTIS - Material file v13'#: First line of the file. Empty when the format has no header line.

MaterialFile.HEADER_PREFIX = 'OPTIS - Material file'#: Version-agnostic start of HEADER, used to validate a file being read.

MaterialFile.ISOTROPIC: ClassVar[MaterialType]#: Material type of the default flavor of the format.

MaterialFile.METALLIC: ClassVar[MaterialType]#: Material type of the metallic flavor of the format.

MaterialFile.BIREFRINGENT: ClassVar[MaterialType]#: Material type of the birefringent flavor of the format.

MaterialFile.FLUORESCENT: ClassVar[MaterialType]#: Material type of the fluorescent flavor of the format.

MaterialFile.DISPERSIONS: ClassVar[tuple]#: Dispersion models the file can hold.

MaterialFile.BIREFRINGENT_DISPERSIONS: ClassVar[tuple]#: Dispersion models a birefringent material can hold.

MaterialFile.SCATTERINGS: ClassVar[tuple]#: Scattering phase functions the file can hold.

Method detail#

MaterialFile.validate()#

Check the material against the constraints of the *.material format.

Raises:

ValueError: If the dispersion model does not match MaterialFile.material_type, if the absorption curve is empty or inconsistent, if a scattering phase function is set without a matching diffusion curve, if a fluorescent material has no pigments, or if a material carries data the format cannot store.

MaterialFile#

Overview#

Import detail#

Property detail#

Attribute detail#

Method detail#

`MaterialFile`#