Raytrace and analysis loop

Introduction

This example demonstrates how to use FRED's scripting language to automate the task of performing a raytrace and analysis inside of a loop.  A Plane Wave (coherent) type Source Primitive will be tilted over a range of angles inside of the loop and the resulting irradiance distributions for each configuration will be saved to a FRED Grid Data (FGD) file on disk.

Model Setup

The simple model consists of a plane wave source incident on a singlet lens element and coming to focus on an absorbing plane.  An analysis surface, "Plane_Surface", is located on the image plane and will be used when performing an irradiance calculation.  Shown below is the raytraced model when the source is configured to be aligned with the z-axis.

A common, repetitive task to be performed is to tilt the source to some incident angle with respect to the optical system and then perform a new raytrace and analysis.  In this model, a Plane Wave (coherent) type Source Primitive is used for the source representation (see image below).  The source tilt angle will be controlled by modifying the source's Location/Orientation settings.  At the bottom of the source dialog, three Location/Orientation operations are defined that have the following purpose:

Note that each of these operations has an index (0-2) associated with it, which we will be using in the script in order to "point" to one of these specific operations for manipulation.

Scripting

There are three scripts that can be found in the Embedded Scripts folder of the example file.  For the purposes of this KB article, we will be looking at the embedded script named, "Generate FGD files".  Double click on this script to open it in the editor.

The first portion of the script performs the following tasks:

1. Update the preference setting responsible for the retention of Analysis Results Nodes in the Analysis Results folder (refer to the Help system for more information on this)
2. Retrieve the node number for the source to be raytraced and store it in the "src" variable.  Retrieve the node number for the analysis surface to be used in the analysis calculation and store it in the "ana" variable.
3. Specify the output directory path where the analysis results will be written to FGD files on disk.
4. Define the min/max angle scan range and the angle steps.  The source will be rotated over the specified range, with a raytrace and analysis being performed at each step.

Sub Main


    'Set preference to retain all Analysis Results Nodes (ARNs)
    PrefsSetARNRetainCount( -1 )


    'Source to be raytraced and analysis surface used for irradiance
    Dim src As Long, ana As Long
    src = FindFullName( "Optical Sources.Plane Wave" )
    ana = FindFullName( "Analysis Surface(s).Plane_Surface" )


    'Directory where output data will be written
    Dim outDir As String
    outDir = "C:\temp\fred\support\fgd_data\"


    'Source angle scan limits and angle step resolution
    Dim minAng As Double, maxAng As Double, angStep As Double
    minAng  = 0   'degrees
    maxAng  = 1   'degrees
    angStep = 0.1 'degrees

The next block of code retrieves operation #2 from the source node and stores the information in a variable called "tOp".  What information is stored in tOp?  In the image of the source dialog above, operation #2 contains three pieces of information; the coordinate system that the operation is defined in, the type of operation being performed (an x-axis rotation in this case), and the value associated with the operation.  The GetOperation command could also have been placed inside of the loop, though it isn't necessary to retrieve this data each time inside of the loop (and is therefore wasteful from a programming perspective).  You can think of this GetOperation call as initializing the tOp variable values, which will then be modified and applied inside of the loop later.

    'Retrieve the x-angle tilt operation definition from the source node
    Dim tOp As T_OPERATION
    GetOperation( src, 2, tOp )

The main work loop, shown below, performs three major tasks:

1. The first task is to update the x-rotation angle in the tOp variable (tOp.val1 = curAng) and then apply this new value to the source node using the SetOperation( src, 2, tOp ) call.  This SetOperation call can be read as: "take the definition in tOp and place it in operation #2 of the src node".  The Update call makes sure that the FRED document views are up to date and reflect the new changes.
2. The second task is to delete any rays that exist in the ray buffer and then trace new rays (the TraceCreate call generates rays from any active source and then traces them through the model without rendering any rays in the visualization view).
3. The third task is to generate a unique name for the current analysis result, call the Irradiance analysis and store the result in an analysis result node (ARN), and then finally write the ARN out to an FGD file on disk in the output directory.

    'Begin loop over angles of interest
    Dim arn As Long, curAng As Double, curName As String
    For curAng = minAng To maxAng Step angStep

        'Update the source's x-angle tilt
        tOp.val1 = curAng
        SetOperation( src, 2, tOp )
        Update

        'Trace new rays
        DeleteRays()
        TraceCreate

        'Calculate irradiance and write results to fies on disk
        curName = "Irradiance_" & CStr(curAng) & "_deg.fgd"
        IrradianceToARN( ana, curName, arn )
        ARNWriteToFile( arn, outDir & curName, False, False )

    Next

The last part of the script simply prints a message to the output window indicating that the script has finished its task and then deletes all of the analysis results nodes from the Analysis Results folder.  Note that this last step is not necessary, of course.  The user may wish to keep the analysis results in the Analysis Results folder for review after the script execution, in which case this code can simply be commented out or deleted.

    Print "Finished writing ARN data to file."

    'Delete all analysis results nodes from the model
    ARNDeleteAllNodes()
    Update

End Sub

After executing this script, the output directory that was specified in the script will contain a collection of *.fgd files.  There will be one FGD file for each source angle that was raytraced and analyzed.

It is important to note that FGD files can always be re-loaded back into a FRED document by right mouse clicking on the Analysis Results folder and selecting the option, "Create New ARN From a File".

FRED Example File: fgd_processing.frd