This tutorial provides an introduction to the basic principles of using the FRED scripting environment. First, we describe the editing environment. Then fundamental programming methods are described. Finally, we will write a script to trace the rays from the source to the detector and calculate the position of the best focus.
As we work through the tutorial you will probably find it very helpful to run FRED at the same time. You may also find it convenient to position the tutorial window on one side of your computer screen and FRED on the other.
In addition, you may find it useful to examine some of the sample scripts provided in the samples subdirectory of your FRED installation.
Create a new script document There are three ways to create a new standalone script file: 1.From the main menu select File > New > Script Type 2.From the Dashboard screen, press the New Script button 3.From the toolbar, press the
Any of these actions will open a new script editor window. The script may be, but isn't necessarily, "associated" with a FRED document. As many FRED documents may be simultaneously open within one application instance of FRED, the script will be operating on the FRED document that the script is associated with. If there is only one FRED document open, then the script is automatically associated with that document.
The rules for script-document association are as follows: •If a script generates a new FRED document, the association is with that document. •If a script window is opened and no FRED document is open, the script is not associated with any document. •If a scripting window is opened and one or more FRED documents are open, the script is associated with the FRED document that was active when the script was opened. •Scripts cannot be associated with other scripts. •If a script is open and not associated with any other open documents, FRED does not assume an association at runtime. •If more than one document is opened and you tell FRED to associate a script with a document, FRED asks which one you want for the association. If only one is open, FRED assumes you want that document. •If at runtime a script is not associated with any document, FRED assumes that the open document (if there is one) is the intended association. If no document is open, execution halts with an error.
Association is indicated in the title bar of the script document window. As shown in the image below, "Script1" is associated with the FRED document titled, "tutorialScripting.frd".
If no association is made, the title bar of the Script window indicates only the title of the script. To set or change the association of a Script, select the Script menu, then "Associate with FRED Document...".
After a script is created, it is executed using the Run command on the Script menu, or the keyboard shortcut Ctrl+B. FRED will automatically compile and run the script, halting if there are errors.
A script's execution will stop at any breakpoints that are set. Breakpoints are places in the script where FRED will pause its execution and allow you to examine the script's current condition, including variable values. FRED allows you to toggle a breakpoint on or off (Script > Toggle Debug Breakpoint) and to remove all breakpoints (Script > Clear All Debug Breakpoints). Once at a breakpoint, FRED allows you to continue running the script (Script > Debug Run Continue), take a single step in the code (Script > Debug Step Into), skip the next line (Script > Debug Step Over), and end the script execution (Script > Debug End).
The programming language for FRED is similar from Microsoft Visual Basic. It uses the same syntax as Basic, as well as the same structure. Photon Engineering has extended it to include data structures, functions, and subroutines useful to FRED models. A summary of the data structures can be found here and a listing of the functions and subroutines can be found here.
In programming, there are only four basic operations that can be done. 1. Data types can be created and modified. 2. Loops can be executed. 3. Decisions can be made. 4. Other sections of code (called subroutines and functions) can be called in sequence.
Data Types Basic has several built in data types, summarized in the following tabe:
To declare a variable of a particular data type, use the Dim keyword and the variable type:
Dim x As Long
The Dim statement (as in "dimension a variable") creates a variable but does not initialize it. To initialize a variable, use an equals sign.
x = 4
Basic does not require a punctuation mark at the end of a line of code (like the semicolon in C/C++). Basic also allows you to create variables without the Dim keyword. The line above would also suffice to create the variable x.
Decision Making Decisions in Basic are made with the If ... Then ... End If keywords. Between the If and the Then is a Boolean condition or variable. If the condition evaluates to True, the code between the Then and the End If is executed. If not, the execution skips to the first line after the End If. See the Loops example below.
Loops In Basic you can iterate through a loop to perform a task or set of tasks multiple times. The next loop iteration can be determined with either a Boolean condition (using a While loop) or an integer condition (using a for loop). As an example, here is a for loop that increases a variable i by 1 until i is 100:
Dim i As Long, j As Long i = 0 For j = 0 To 99 i = i + 1 Next j Print i
Here is the same example using a while loop:
Dim NotOneHundred As Boolean Dim i As Long i = 0 NotOneHundred = True While NotOneHundred i = i+1 If i = 100 Then NotOneHundred = False End If Wend Print i
Calling Subroutines & Functions Subroutines are defined in Basic with the Sub ... End Sub keywords. Functions are defined by the Function ... End Function keywords. The difference between the two is that functions return values while subroutines do not. The purpose of Subroutines and Functions is to encapsulate chunks of code that serve a single purpose. This makes it easier to create code that can be called many times; you don't have to write out the entire function each time, you can write it once and then call the function (or subroutine) every time you need to.
Let's begin by opening the file tutorialScripting.frd, located in the <install dir>\Resources\Samples\Tutorials & Examples\ directory. This is a simple file with a light source propagating to a mirror which focuses the rays on another surface.
Create a new script as shown above, then select Script > Associate with FRED Document... to associate it with the tutorialScripting.frd file.
On the first line make a call to the built-in function TraceCreateDraw:
TraceCreateDraw
This will cause FRED to create the rays, perform the optical raytrace, and draw the rays in the visualization window. On the second line create a variable of type T_BESTFOCUS:
Dim focusInfo As T_BESTFOCUS
Then insert a call to the BestFocus subroutine:
BestFocus -1, -1, focusInfo
The details of the parameters can be found in the BestFocus help article. Finally, use print statements to report the results to the output window:
Print "" Print "Best Focus Result" Print "x = " & focusInfo.x Print "y = " & focusInfo.y Print "z = " & focusInfo.z
The final script should look like this:
Sub Main
TraceCreateDraw
Dim focusInfo As T_BESTFOCUS BestFocus -1, -1, focusInfo
Print "" Print "Best Focus Result" Print "x = " & focusInfo.x Print "y = " & focusInfo.y Print "z = " & focusInfo.z
End Sub
After navigating to Script > Run, you should see the following printed to the output window:
Best Focus Result x = 0.175870720434085 y = 7.04233536022349E-02 z = -1.99029955183314
FRED script reference: Help > Scripting > FRED Extensions. BASIC language reference: Help > Scripting > BASIC Language Reference.
|
.png)