Source File

The Source File is a source whose ray coordinates, cosines, and intensity are defined in a user supplied file. The name of the file containing the ray data must be placed in the comment column of the object. The file extension may be either DAT, SDF or TM25RAY and the file must be placed in the <data>\Objects\Sources\Source Files folder (see "Folders" ). The extensions SDF, TM25RAY is recommended and DAT is supported only for backward compatibility. The file format may be either text or binary, both formats are described below.

Critical Raysets with an extension CRS can also be used as Source File objects.  See the discussion in the Critical Rayset Generator for details.

The parameters are:

Parameter #	Definition
1-5	See " Parameters common to all source objects " .
6	Randomize?: If set to zero, the rays will normally be traced in the order listed in the file. If non-zero, then the ray order is randomized once, when the file is read or any parameter in the NSC Editor changes for the source object and the source is updated. The randomize feature is only available if the total number of rays in the file is less than the maximum number of source rays to hold in memory. Files with more than the maximum number of source rays to hold in memory are too large to hold in memory and cannot be randomized. These large files are partially read as required as described below. The maximum number of source rays to hold in memory is a user definable parameter; see "Maximum Source File Rays In Memory."
	For parameters 7, 8, and 9, the data presented is based only open the number of analysis rays read from the source file, which may be less than the total number of rays in the file.
7	Power/Lumens In File: The value for this parameter is for reference, and is set by OpticStudio upon reading the file and should not be altered or set by the user. The behavior of this field is different for "flux only" and "spectral color" formats, as defined in "Binary Source File format" . For flux only format files: This reference value is the total power in current source units defined by the rays in the file. Only the number of rays used for analysis is considered for making this power computation. If the current source units are photometric (lumens) then the power in watts in the source file are converted to photometric units at the monochromatic wavelength defined for the source file in the parameter 4 value. Note there is no way to convert power in watts to lumens if the source is polychromatic, since the wavelengths are randomly assigned as described in "Parameters common to all source objects" . If the source is polychromatic, this parameter will be set to zero. The actual power of each ray is defined by parameter 3 above, the number of rays being traced, and the relative power of each ray as defined in the source file. For spectral color format files: The wavelength of each ray is defined in the file, and those wavelengths will be used for tracing no matter what the wavelength parameter in the NSC Editor is set to. The Power/Lumens value will be valid even if this source is polychromatic, and the actual flux and wavelengths defined in the file are used to determine the total power in current source units.
8-9	These values are for reference only, and are set by OpticStudio upon reading the file and should not be altered or set by the user. These references values are the minimum and maximum wavelength in micrometers for the source. For spectral color format files, these values are read from the file. For flux only format files these values are determined by the system wavelengths or color spectrum defined for the source, if any. See "Defining the color and spectral content of sources" .

Text vs. binary format files

The maximum number of rays currently allowed for text files is 1,000,000. If there are more than 1,000,000 rays defined in a text source file, OpticStudio will offer to convert the file to binary format automatically. The original file will be renamed with the ".OLD" extension, and the new binary SDF file will be created using the same name as the original file. After the conversion is complete, an option will be presented to save or delete the old file. This conversion is done to save disk space (binary files are about 30% as large as equivalent text files), load time (binary files read about 20x faster than text files), and system memory (large binary files can be left on disk and thus require very little RAM) even if billions of rays are being traced.

Memory requirements for source file objects

For both text and binary files, if the total number of rays to be traced is less than the maximum number of source rays in memory, OpticStudio stores the rays in system memory for maximum speed. This requires about 32 bytes of memory for each ray, or up to 32 Mb of memory for 1,000,000 rays. If the total number of rays is greater than the maximum number of source rays in memory, OpticStudio leaves the ray data on disk, and reads the file as required. This requires less memory, and allows OpticStudio to trace a huge number of rays, limited only by the systems file storage capacity. The maximum number of source rays to hold in memory is a user definable parameter; see "Maximum Source File Rays In Memory" .

Restrictions on the number of rays selected

There are restrictions on the values for the number of layout and analysis rays when using the Source File:

- The number of analysis rays must be equal to or larger than the number of layout rays. The number of analysis rays will be set to the larger of the two numbers entered in the NSC Editor.

- The number of analysis and layout rays may not exceed the number of rays defined in the file.

Binary Source File format

The Binary Source File consists of a header structure of the form:

typedef struct
{
int Identifier; // Format version ID, current value is 1010
unsigned int NbrRays; // The number of rays in the file
char Description[100]; // A text description of the source
float SourceFlux; // The total flux in watts of this source
float RaySetFlux; // The flux in watts represented by this Ray Set
float Wavelength; // The wavelength in micrometers, 0 if a composite
float InclinationBeg, InclinationEnd; // Angular range for ray set (Degrees)
float AzimuthBeg, AzimuthEnd; // Angular range for ray set (Degrees)
long DimensionUnits; // METERS=0, IN=1, CM=2, FEET=3, MM=4
float LocX, LocY,LocZ; // Coordinate Translation of the source
float RotX,RotY,RotZ; // Source rotation (Radians)
float ScaleX, ScaleY, ScaleZ; // Currently unused
float unused1, unused2, unused3, unused4;
int ray_format_type, flux_type;
int reserved1, reserved2;
} NSC_RAY_DATA_HEADER;

The data types float, int, and unsigned int are all 32 bit types. Identifier defines the file format, currently 1010. Older formats normally can be read by OpticStudio as well, although OpticStudio only writes files in the current format.OpticStudio only uses the NbrRays, DimensionUnits, ray_format_type, and flux_type parameters. The other data is ignored.

The maximum valid number of rays in the file as defined by NbrRays is 4 billion (4,000,000,000 rays). Exceeding this number may cause problems with the reading of the data file by OpticStudio. The ray_format_type must be either 0 for flux only format, or 2 for the spectral color format (both are defined below). Other format types are not supported. If and only if the ray_format_type is 0, then the flux_type is 0 for watts, and 1 for lumens. For the spectral color format, the flux must be in watts, and the wavelength in micrometers. The flux and wavelength values and units are used in the ray structures defined below.

Note that when the spectral color format is used, OpticStudio will always trace rays at the wavelengths defined in the file, no matter what system wavelengths are defined

After the header follow NbrRays ray structures. The ray structure format depends upon the ray format type. For the flux only format, the ray structure is:

typedef struct 
{
float x, y, z;
float l, m, n;
float flux;
} FLUX_ONLY;
 
For the color spectral color format, the ray structure is:
 
typedef struct
{
float x, y, z;
float l, m, n;
float flux, wavelength;
} SPECTRAL_COLOR;
 

OpticStudio can read either the flux only or the spectral color format. The spectral color format only is used by OpticStudio when generating source files from ray trace data (see the discussion of " Save Rays on Object n" in the section "The Ray Database Viewer" ).

Text Source File format

The text Source File consists of a single line of header data with just two integer numbers of the form:

number_of_rays dimension_flag

The number_of_rays indicates the total number of rays in the file. The dimension_flag is 0 for meters, 1 for inches, 2 for centimeters, 3 for feet, and 4 for millimeters.

The remaining lines in the file are of the format:

x y z l m n intensity wavelength

Any line starting with the "!" symbol is assumed to be a comment line and is ignored. Any number of rays may be defined in a single file using this text format. However, if the number of rays exceeds 1,000,000, the file will automatically be converted to binary format by OpticStudio the first time the file is opened for a source file object. For a discussion of this conversion see "Text vs. binary format files" . The wavelength argument is optional, however, if present, the ray will always be traced at the defined wavelength in micrometers, and the source file will be treated as described by the spectral color format in the discussion on binary file formats.

Intensity normalization in source files

Each ray may have a different relative intensity. If the relative intensity value is not 1.0 for each ray, then normalization occurs as described below.

When the source file is first loaded into memory, the intensity of each ray is summed and then normalized to the average intensity. If the total flux of the source is then defined to be some number of watts, a subset of the rays can be traced and their intensities will yield approximately, but not exactly, the total flux. Normalization is required for an arbitrary subset of the rays to yield approximately the total desired power.

Read TM-25 rayfiles

Start from Zemax OpticStudio 2024 R2, OpticStudio supports read and write of TM-25 rayfiles, which comes with extension filename ".tm25ray". The data format is defined in the standard document ANSI/IES TM-25-20. The data format can but does not require to support polarization multiple wavelengths. When the file doesn’t include wavelength or polarization data, OpticStudio will use user settings specified in Object Properties > Source section. Note that not all formats in the TM-25 standard are supported. When an invalid file is loaded into OpticStudio, an error message will show and a corresponding log is exported, with filename "sourcefilename.tm25ray.log" in the same folder as the TM-25 source files locates.

Write TM-25 rayfiles

If the TM-25 rayfile is exported from OpticStudio, phase and electric field data are added for each ray. This is useful if the user needs to load the file back to OpticStudio to further do coherent analysis or polarization analysis. Note that polarization information will not be added if "Use Polarization" is not checked during the raytracing or if the original ZRD file doesn’t include polarization data.

For users who will parse the rayfile by themselves, the phase and electric field data are added as 8 more data for each of the ray as below.

"phase", "phase_dbl_err": This data has the same meaning as the starting_phase used in the ray database file (.ZRD). The data is in optical path length in unit of µm. To get data in unit of radians, users can simply multiply the value by "2*pi/wavelength", where wavelength is in unit of µm. Users can simply read "phase" for usage. Or, users can read both data as type double and sum them up for an improved accuracy.

"exr", "exi", "eyr", "eyi", "ezr", "ezi": This data has the same meaning as the data with same name in the ray databased file (.ZRD).

See also "The ZRD Uncompressed Full Data Format (UFD)".

Read TM-25 rayfiles (Spectrum considerations)

Read TM-25 rayfiles (polarization)

In Zemax OpticStudio, polarization is saved in the form of an electric field, which is a complex vector in 3D space (Ex, Ey, Ez). When exporting a TM-25 rayfile, we will convert them to Stokes parameters so it can be read by other software. The way the Stokes parameters are exported is that the major axis will always be on the x axis of the local coordinate where the Stokes parameters are defined. In the program, they are calculated as below.

1. Calculate polarization ellipse major axis vector in global coordinate.
2. Define as ray vector in global coordinate.
3. Calculate minor axis vector in global coordinate.
4. Project the electric field at major axis .
5. Project the electric field at minor axis .
6. Calculate Stokes parameters as below

   

Although in Zemax OpticStudio, we choose major/minor axes for the local coordinates. This local coordinate can actually be arbitrary as the major axis data is written in the TM-25 and any other software can always find the correct local coordinate to restore the global coordinate. The restoration from Stokes parameters to electric field in 3D space when loading the TM-25 is done as below

1. Calculate the polarized flux:

   

2. Generate a random number rd uniform in [0,1].
3. If , randomize a polarization state.
4. If , the electric field on polarization ellipse is calculated as show in this equation

   

5. Load polarization ellipse major axis vector in global coordinate from the TM-25 rayfile.
6. Calculate Ap from E(S) as below, where
7. Get local x axis in global coordinate by rotating around ray direction by angle Ap.
8. Note that we already have local z axis in global coordinate, which is the ray direction.
9. Calculate local y axis vector in global coordinate
10. Calculate electric field in global coordinate The above restoration can be used with any TM-25 ray file that follows the standard documentation. Note that if the TM-25 ray file is generated by Zemax OpticStudio, since it saves the electric field (Ex,Ey,Ez) exactly, we will not use the data of Stokes parameters but just load these electric field data for convenience.

Data accuracy in ray files

When doing raytracing in OpticStudio, the ray data, such like position, direction, flux, and more are saved in double-precision floating-point format. However, when exporting ray files, including DAT, SDF, and TM25RAY, these data are saved in single-precision floating-point format. As a result, if we save data in the middle of the system, load it back and reply, the result can always be different. This difference is very small and won’t be noticed unless users carefully compare the exact value at each pixel, by looking at the text data or retrieving data from macro, operand, or API, between the original system and replaying system.

Use with LightningTrace

The angular distribution of the source is determined by creating a far-field map for the source upon first reading of the file. This map is stored in an FFD file located in the same folder as the source file. The map is created using all rays in the source, and thus the Randomize value (parameter 6) has no effect on the LightningTrace results. The size and spatial distribution of the source is neglected.

Next:

• Source Gaussian