`RayFile`#

class ansys.speos.core.input_files.ray_file.RayFile(rays=None, radiant_flux=1.0, luminous_flux=683.0)#

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

Speos ray file, holding the rays emitted by a measured or simulated source.

save() and load() handle the binary *.ray flavor, while RayFile.save_text() and RayFile.load_text() handle the text flavor that the Speos ray file editors also accept. RayFile.save_sdf() and RayFile.load_sdf() handle Zemax spectral binary source files.

Parameters:

raysList[Ray], optional: Rays of the file. By default, [].
radiant_fluxfloat, optional: Total radiant flux of the file, in W. By default, 1.0.
luminous_fluxfloat, optional: Total luminous flux of the file, in lm. By default, 683.0.

Parameters:

rays (List[Ray] | None)
radiant_flux (float)
luminous_flux (float)

Notes

The binary layout is 7 little-endian 32-bit floats, the total radiant flux followed by 5 format markers and the total luminous flux, then 8 floats per ray: the position, the direction cosines, the wavelength and the energy. The text flavor does not carry any flux, so RayFile.load_text() leaves RayFile.radiant_flux and RayFile.luminous_flux at their default. The RayFile.rays getter copies the container but keeps ray objects shared. Assign an edited list back to replace rays. An empty list permits a draft but cannot be saved. Polarization consistency across rays is required by RayFile.save_text() only. Binary save() rejects polarized rays; use RayFile.save_text() to retain polarization.

Examples

>>> from ansys.speos.core.input_files.ray_file import Ray, RayFile
>>> rays = [Ray(position=(0.0, 0.0, 0.0), direction=(0.0, 0.0, 1.0), wavelength=633.0)]
>>> RayFile(rays=rays, radiant_flux=1.0, luminous_flux=112.0).save("laser.ray")

Overview#

Constructors

`load_sdf`	Read a Zemax spectral binary source file in millimeter coordinates.
`load_text`	Read a text ray file.

Methods

`validate`	Check the rays against the constraints of the ray file formats.
`save_sdf`	Write an unpolarized Zemax spectral binary source file.
`save_text`	Write the rays to a text ray file.

Properties

`rays`	Ray collection with a copied container and shared rays.
`radiant_flux`	Total radiant flux, in W.
`luminous_flux`	Total luminous flux, in lm.

Attributes

EXTENSION

Usual file extension of the format.

Import detail#

from ansys.speos.core.input_files.ray_file import RayFile

Property detail#

property RayFile.rays: List[Ray]#

Ray collection with a copied container and shared rays.

Parameters:

valuesList[Ray]: New rays of the file.

Returns:

List[Ray]: Editable validated ray objects.

property RayFile.radiant_flux: float#

Total radiant flux, in W.

Parameters:

valuefloat: New total radiant flux of the file, in W.

Returns:

float: Finite radiant flux.

property RayFile.luminous_flux: float#

Total luminous flux, in lm.

Parameters:

valuefloat: New total luminous flux of the file, in lm.

Returns:

float: Finite luminous flux.

Attribute detail#

RayFile.EXTENSION = '.ray'#: Usual file extension of the format.

Method detail#

RayFile.validate()#

Check the rays against the constraints of the ray file formats.

Raises:

ValueError: If the file holds no ray, or if a ray direction is not a unit vector.

RayFile.save_sdf(file_path)#

Write an unpolarized Zemax spectral binary source file.

Parameters:

file_pathUnion[str, pathlib.Path]: Path of the file to write. An existing file is overwritten after validation.

Returns:

pathlib.Path: Path of the written file.

Raises:

ValueError: If the rays are invalid or polarized, the radiant flux is negative, wavelengths are not positive, positive power has no nonzero weights, or data cannot be represented by the format’s 32-bit floats.

Notes

The 208-byte little-endian header identifies spectral records in watts with millimeter coordinates. Each 32-byte record holds x y z l m n flux wavelength. Wavelengths are converted from nm to micrometers. Ray energies are relative weights: each output flux is radiant_flux * energy / sum(energies). Zero total power writes zero ray fluxes. Neither the model nor its energy weights are modified. Luminous flux and polarization are not stored; use RayFile.save_text() for polarization.

References

[1]

Speos and Zemax Source file converter.

classmethod RayFile.load_sdf(file_path, *, luminous_flux=683.0)#

Read a Zemax spectral binary source file in millimeter coordinates.

Parameters:

file_pathUnion[str, pathlib.Path]: Path of the file to read.
luminous_fluxfloat, optional: Known photometric flux in lm. By default, 683.0, the model’s default, not a value inferred from the SDF spectrum.

Returns:

ansys.speos.core.input_files.ray_file.RayFile: Unpolarized rays with wavelengths in nm, normalized relative energy weights, and radiant flux from the header’s RaySetFlux.

Raises:

FileNotFoundError: If file_path does not point to an existing file.
ValueError: If the header, record count or ray data are invalid, coordinates are not in mm, the source has a nonneutral transform, or the file is not spectral radiometric SDF.

Notes

Identifiers 1010 and 8675309 are accepted. Monochromatic DAT and photometric formats are not supported. Wavelengths in micrometers are converted to nm. Record fluxes are normalized to relative weights; their sum need not equal RaySetFlux. Positive ray-set power requires a positive sum of record fluxes. An all-zero set is represented by zero energies without dividing by zero. Original luminous flux, description, angular limits and SourceFlux metadata are not reconstructed. Re-export preserves the ray-set power and distribution, not arbitrary original energy scaling or header-only metadata.

References

[1]

Converting a binary Source File into ASCII.

RayFile.save_text(file_path)#

Write the rays to a text ray file.

Each ray takes one line, index x y z l m n wavelength energy, extended with o p q r s when the rays are polarized. The line count opens the file.

Parameters:

file_pathUnion[str, pathlib.Path]: Path of the file to write. An existing file is overwritten.

Returns:

pathlib.Path: Path of the written file.

Raises:

ValueError: If the rays are invalid, or if only some of them carry a polarization.

classmethod RayFile.load_text(file_path)#

Read a text ray file.

Parameters:

file_pathUnion[str, pathlib.Path]: Path of the file to read.

Returns:

ansys.speos.core.input_files.ray_file.RayFile: Ray file model. The flux is not carried by the text flavor, so RayFile.radiant_flux and RayFile.luminous_flux keep their default value.

Raises:

FileNotFoundError: If file_path does not point to an existing file.
ValueError: If the count is not a positive integer, does not match the file content, or a ray line is invalid or does not hold 9 values, or 14 when polarized.

RayFile#

Overview#

Import detail#

Property detail#

Attribute detail#

Method detail#

`RayFile`#