Description

FRED's script language is the key to effecting specialized, repetitive or complex tasks. These examples describe scripts that address two often requested features; the cumulative spot diagram and an efficient method of executing large raytraces. These tasks are implemented here in the efficient form of FRED object libraries.

The FRED script containing these subroutines, FREDTools.frs, can be found in the \Resources\Samples\Scripts\Geometry subdirectory of your FRED installation.

The script commands that allow library access are:

CreateLib - Return a library object from an *.frs file

GetEmbeddedScriptLib - Return a library object from an embedded script

CompileText - Returns a library object from text using the FRED core object model

Using a library object

To use the subroutines or functions defined in a script or embedded script, declare a BASIC object name and create the object using the FRED extensions CreateLib or GetEmbeddedScriptLib. Library resources should always be released once the library is no longer needed. For example, to use the SurfAccum subroutine from the script file mytoolkit.frs,

Dim mylib As Object
Set mylib = CreateLib ("C:\Documents and Settings\My Documents\FRED files\mytoolkit.frs")

mylib.SurfAccum 20, 62, True

  :

  :

Set mylib = Nothing

Cumulative Spot Diagram Example

Spot diagrams, irradiance and intensity calculations require an Analysis Surface with Ray Filter specifications to restrict which rays are used in the calculation (the default ray filter being "AND All Rays").  While there are nearly fifty Ray Filter Specifications (see the help topic Ray Selection Criterion), none of these allow for the inclusion of rays that intersect a given surface multiple times along its path before terminating on some other surface. One solution to this is to allow the user to create temporary ray buffers that store information as the rays step through the system. When the raytrace finishes, these temporary buffers can be swapped into and out of the main buffer for calculation purposes.  Please note that in FRED, only rays in the main buffer can be analyzed.  Provided below is a script for implementing this type of cumulative analysis, which can be saved in an *.frs file and then called as a library object from other scripts.

The pseudocode for the cumulative spot diagram script is the following:

The following code shows the implementation of this method.

Sub SurfAccum (surfid As Long, anode As Long, drawray As Boolean )

Dim rtemp&
Dim success As Boolean
Dim adv As T_ADVANCEDRAYTRACE
 

'initalize the Advanced Raytrace with default settings

InitAdvancedRaytrace adv      

'step one intersection at a time

adv.hitcount=1

'create new rays for the first time

adv.traceactivesources=True

'draw the rays while tracing

adv.draw=True

'Pseudocode Step 1: add a temporary buffer
rtemp = AddRayBuffer ()

'default count value and zero out step counter

count=1

stepcount=0
 

'Pseudocode Step 2: loop until there are no more rays to trace
While count<>0

 'advance rays one intersection

 count=AdvancedRaytrace(adv)

 'track the number of intersections traced
 stepcount=stepcount+1

  'Pseudocode Step 2 (cont.): loop over all rays. if ray is on the target surface, store ray in the temporary buffer
  If count<>0 Then
   For j=0 To GetRayCount()-1
    If IsRayActive(j) Then

     If GetRayEntity(j)=surfid Then
      CopyRayBufferToBuffer j,0,rtemp
     End If
    End If

   Next j
  End If
 'set to Trace Existing for remainder of process

 adv.traceactivesources=False           

Wend
 

'empty main buffer before transfer
DeleteRays

'Pseudocode Step 3: move rays from temporary buffer to main buffer for analysis
For j=0 To GetRayBufferRayCount(rtemp)-1
 CopyRayBufferToBuffer j,rtemp,0
Next j

'delete temporary buffer after use (memory management)
DeleteRayBuffer rtemp

Print stepcount & "steps taken. Rays intersecting " & GetName(surfid) & " have been transferred to the main buffer for analysis"

End Sub

NOTE: Ray buffers use memory! Delete them after use or memory will not be relinquished until the FRED document is closed.

This subroutine can be used as a FRED library object by using the CreateLib function as shown below.  In this example it is assumed that the subroutine is defined in a script file called mytoolkit.frs.

Dim mylib As Object

Dim surfID as long, anode as long, drawRay as boolean
Set mylib = CreateLib ("C:\Documents and Settings\My Documents\FRED files\mytoolkit.frs")

mylib.SurfAccum surfID, anode, drawRay

  :

  :

Set mylib = Nothing  

Large Raytrace Example

Due to the fact that rays take up space in memory, tracing a large number of rays can often be made more efficient by breaking up the task into many smaller traces. In the case where incoherent irradiance or intensity is needed for a large collection of rays, the calculation can be done incrementally and displayed at the end.  The following subroutine traces a random source a specified number of times and accumulates the irradiance at the designated analysis surface using ARNs.  In this script, the variable numloop is the number of raytraces and anode is the node number of the analysis surface.

NOTE: Make sure that "Generate a different random number sequence for every raytrace" has been checked on the Miscellaneous Tab of the Preferences dialog.

Sub largetraceirrad ( anode As Long, numloop As Integer, fname As String)

Dim filename As String, rcount As Long, icount As Long, pwr As Double, success As Boolean

Dim singleARN As Long, accumARN As Long

Dim ana As T_ANALYSIS

Dim ent As T_ENTITY

'delete any existing rays and create two empty ARN for use in the raytrace loop

rcount = IrradianceToARN( anode, "singleARN", singleARN )

rcount = IrradianceToARN( anode, "accumARN", accumARN )

'loop over sources and scale powers based upon number of loops

For l= 0 To GetEntityCount()-1

          If IsSource(l)=True Then

                    pwr=GetSourcePower(l)

                    pwr=pwr/numloop

                    SetSourcePower l, pwr

          End If

Next l

'note the start time

t1=Time

'zero out the counters

rcount=0 : icount = 0

'loop over rays defined in Source Folder

For i=1 To numloop

          Print "running trace " & i

          'trace without rendering to use all available processors

          TraceCreate

          'calculate irradiance for current loop

          icount = IrradianceToARN( anode, "singleARN", singleARN )

          rcount = rcount + icount

          'accumulate the results for all loops, results are stored in accumARN

          ARNLinearCombination 1, accumARN, 1, singleARN

Next i

'write out irradiance calculation to PlotFile un user Current Directory

success = ARNWriteToFile( accumARN, GetDocDir() & fname, False, False )

'memory management items

DeleteRays

ARNDeleteAllNodes

'restore source powers to orginal values

For l= 0 To GetEntityCount()-1

          If IsSource(l)=True Then

                    pwr=GetSourcePower(l)

                    pwr=pwr*numloop

                    SetSourcePower l, pwr

          End If

Next l

'note ending time

t2=Time

'Print begining And ending times

Print "end time " & t2

Print "start time " & t1

Print rcount & " rays combined"

End Sub

This subroutine can be used as a FRED library object by using the CreateLib function as shown below.  In this example it is assumed that the subroutine is defined in a script file called mytoolkit.frs.

Dim mylib As Object
Dim anode As Long, escript As Long, fname As String, success As Boolean

Set mylib = CreateLib ("C:\Documents and Settings\My Documents\FRED files\mytoolkit.frs")
  :
mylib.largetraceirrad anode, 100, fname

  :

  :

Set mylib = Nothing

The output file can be loaded into the chart view using the script command DisplayPlotFile, or by navigating to Menu > Tools > Open Plot File in 3D Chart.