Writing Function Sets

You can use scripting to add your own function sets to a model, after which you can use your new functions in formulas just as you would Quantrix’s built-in functions.

Conceptually, writing functions is simpler than writing actions. Because they only perform pure calculations, functions do not have a context or any special syntax, nor do they have access to Quantrix’s scripting API. A function set is simply a set of Groovy methods. To be convertible to a Quantrix function, a Groovy method can use only the following types in the argument and return positions:

• String

• Date

• Primitive (i.e. long, int, short, byte, double, boolean)

• Array of any of the above

The steps below show you how to create a simple function set. It will have two functions that compute the area and circumference of a circle given its radius.

Step 1: Add the New Function Set

Start with a new model. Open the Script Manager by clicking Scripting -> Script Manager (see the Script Manager description). Add a new function set to the default library by right-clicking on the Library and selecting Add Functions. A new function set is created, and the function set editor displays.

Tip: You can also add a function set by clicking the add functions button in the Script Manager toolbar, or by choosing Add Functions from the Scripting menu.

The box containing the text “FunctionSet1” stores the name of the function set. Change the name to “Circle”. To commit the name change, press Enter or click outside of the text box.

Step 2: Create the Code

To code a function set, supply one Groovy method for each function you want to include. Remember the requirements concerning method argument and return types for functions. Our function set will contain the methods below. Type (or paste) them into the editor’s text area.

double area(double radius)

{

return Math.PI * (radius * radius)

}

double circumference(double radius)

{

return Math.PI * 2 * radius

}

You must commit your changes to save the function set. Click the green check mark or click anywhere outside the text area to commit, then save the model. Quantrix automatically converts the two methods to two functions in a set named Circle and makes the set available in the function library.

Step 3: Test the Functions

The functions in the circle set can now be used in formulas. To demonstrate this, we will create a simple matrix that displays the area and circumference of circles based on radius. To set up the matrix, follow these steps:

1. Open Matrix1.

2. Select the A1 item and press enter twice to add two more A items. These should appear as columns in the matrix, resulting in a row of three cells. Items in B correspond to circles, while items in A correspond to their attributes. To make this clear, you may want to rename the items in Matrix1 as shown here:

3. Start a new formula by typing the following into the formula editor:

Area=

4. Now click the Function... button to display the Functions tool pane. Scroll to the bottom of the list of function categories, where you will see an entry labeled Circle:

Click that entry, then double-click the area entry that appears in the list of functions. The formula should now read:

Area=area()

5. To complete the formula, click within the parentheses following the name of the area function and type “Radius”:

Area=area(Radius)

6. Press Enter to save the formula. A green check mark should appear next to it to indicate that it is valid.

7. Press Enter again to add a second formula, and fill it in as shown below to compute circumference:

Circumference=circumference(Radius)

Now enter a radius value for Circle1. The area and circumference are calculated automatically.

Step 4: Add Documentation

When you use Quantrix’s built-in functions from the Functions tool pane, each function is accompanied by documentation that explains what it does and specifies its arguments and result. You can add the same kind of documentation to your own functions by using the @FunctionDoc annotation.

@FunctionDoc is a Java annotation that you add to your function set code immediately before the declaration of any method whose function you want to document. @FunctionDoc has the following syntax:

@FunctionDoc(description = “description”,

argNames = [“arg1”, “arg2”, ... ],

argDocs = [“doc1”, “doc2”, ... ])

Where description, arg1, doc1, etc. are any values you choose to provide. The description element is a string that gives a general explanation of your function. The argNames element is a list of strings that gives the names of the arguments to your function in order. The argDocs element is a list of strings that gives a description for each argument.

All three elements in the annotation are optional. When the documentation is displayed, arg1 will be paired with doc1, arg2 with doc2, and so on. If argNames has more items than argDocs, names will be displayed without descriptions for the extra arguments. If argDocs has more items than argNames, the extra descriptions will be ignored.

To use @FunctionDoc to document the functions in the Circle set, open the set for editing via the Script Manager, then place an annotation before each method as shown below.

@FunctionDoc(description="Returns the area of a circle given its radius.",

argNames=["radius"],

argDocs=["the radius"])

double area(double radius)

{

...

}

@FunctionDoc(description="Returns the circumference of a circle given its radius.",

argNames=["radius"],

argDocs=["the radius"])

double circumference(double radius)

{

...

}

When finished adding the annotations, commit your changes and save the model, then return to the Functions tool pane and highlight either of the functions in the Circle set. You should see your documentation displayed in the adjoining text area.

You can view the documented function set in the sample model CircleFunctionSet2.model (Samples >Scripting > Getting Started Guide folder).

See Also

Working with Libraries