Configure Functions¶
Under , you can create, edit and delete functions.
The Functions dialog enables you to build and edit customised calculations (called functions) that can be used in other areas of NEXUS IC, such as Asset Information fields, Event fields and Report Sources. You can drag and drop elements into the Function Editor, then connect the elements together to define the way in which data flows through your function.
Functions are integral to NEXUS IC. Functions are used within risk models (defining models, matrices and parameters), they are also used in asset information fields (for example, corrosion rates, retirement dates, pressures, wall thicknesses) and event definitions (for example, functions to calculate remaining wall thickness or span lengths).
Create Functions¶
To add a new function, proceed as follows:
Click the Add button at the top of the Configuration - Functions dialog.
Give your new function a name and (optionally) a category.
In the bottom half of the dialog, click ‘+’ next to ELEMENTS, and drag a function parameter from the ELEMENTS tree to the design area at the right. All functions are required to have at least one function parameter. For information about the individual function elements, see Function Elements.
Drag other elements as desired.
Once elements in the design are in place, you can connect two elements by dragging from the output square at the bottom of one element to a second element. Your drag must begin on the source element’s output square, but can end anywhere in the target element (not just on its input squares).
You can replace an existing connection by dragging from an output square to the specific input square whose connection you want to replace. You can break an existing connection by dragging it off an input square and dropping it on a blank part of the design area. You can connect one output to multiple inputs — there is no limit to the number of places you can connect a single output to.
To view “on the fly” values for your function, click the Show Results button.
You can also enter Input Values at the bottom of the Tests tab. The function will be evaluated using the input values you specify. If you give an element an input of a type it is not expecting, instead of a green result you will see a yellow error message at the bottom of that element, explaining the type mismatch. You will similarly get yellow error messages for other error cases, such as division by zero. These errors are only visible if the Show Results button is selected.
Click OK to save the function.
You can use the standard grid functions in the dialog as follows:
To edit an existing function, click the Edit button, then proceed as above.
To delete existing functions, select them in the dialog and click the Delete button at the top of the dialog.
To export functions, see Export for full description of the Export menu item.
To see if a function is being used elsewhere in the application, click Connections.
Functions and function elements in NEXUS IC 6 are unit aware: if you have a function with two inputs leading to an Addition operation, and one function has units in metres while the other has units in millimetres, NEXUS IC will correctly deduce that one number needs to be scaled by a factor of 1000 before the two numbers are added. (Which direction the scaling happens depends on the output unit you select for the Addition element.) For many function elements, you can select the output unit. (Note that NEXUS IC isn’t dimensionally aware: if you divide a length by a time, it won’t understand that the result is a velocity.)
Statistics¶
Statistics for individual function elements can be shown as a hint when you hover over the item with your mouse. The Statistics include the number of function calls, and the total, average, maximum and minimum time to compute the function. Also included is the time to retrieve function Parameters, and Total including Parameters.
To display this data, navigate to , and if the function has been called and its results cached, the results will be revealed when hovering over a function element. Statistics are also visible when editing a function, by clicking Show Results, then hovering over an element.
Nulls¶
Almost any calculation involving a null will return null. For example, 2 + null = null.
Any comparison involving a null will always return false. This is occasionally a bit subtle: in a Comparison element, if you compare null to null, it will return whatever value you have set for the False case.
(This is in line with accepted IT industry practice for nulls in data.)
There are some exceptions, where it’s required to produce a numeric value despite the presence of some nulls. If you use an operation object to calculate a minimum, maximum, or average value, nulls are left out and the non-null values will be used to calculate the answer. For example, the average of 1 and null is 1. (If all inputs are null, a null will of course be returned as the average of null and null is null.)
Additionally, if your function involves lookups, you must take care to correctly handle the case of null inputs. If you set your lookup filters to null, NEXUS will look for a row matching that filter. This can be a very slow way to return a null value, particularly over large datasets. Accordingly, we recommend that you always validity-check lookup inputs and filters, and bypass the lookup in the case of invalid or incorrect filters.
Test Functions¶
You can test the performance of a function on specific values by entering Input Values at the bottom of the Tests tab for the function to be evaluated on, before clicking Show Results and hovering over the function element.
You can write test cases for your functions, under the Tests tab. Test cases let you test a function as you create it, and storing your tests within the function lets you verify that a function still does what it did when you created it, and let you re-validate a function after changes. When writing tests, we recommend that you write at least one that returns a valid result, and if it’s possible for your function to return an error (see Error), write at least one test for each possible error case.
To generate a test report, navigate to , highlight all the functions in the function list to be tested, and select Execute Tests. This calls the functions and the list of the functions and their test results will be shown in the Function Tests dialog. The grid will show the columns Name, Comments, Test Result, Actual Result, and Pass/Fail for each function.
Save/Load Function Templates¶
Clicking Save Template will save the selected function and related details to a .function file. NEXUS IC will find all items related to this function (asset information forms, event definitions, chart templates, lookup tables, and so on), and will present a dialog listing all the dependencies it has found, with a checkbox for each row. Untick any that you don’t want to be saved with your function.
This function can then be loaded into this or another database via Load Template. Note that if the previously saved function still exists in this database, Load Template will overwrite that existing function and it will not create a new copy of it. This is similar for any other elements saved in the .function file: asset information fields, lookup tables, and so on.
See also