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 Groups (AIGs) 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 to expand the list, 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. For example, if you want to create a function for converting temperature from Kelvin to Celsius, you add the following elements:
A function parameter for capturing the value to be converted in Kelvin
A constant element for the value 273.15
An operator element for subtracting the constant value from the value in Kelvin
A result element for the value in Celsius
Double-click each element to define their parameters. The available parameters depend on the type of the element, but in general, you can define a name, a type, unit, default value and so on. In our temperature conversion example, you can make the following settings:
Function Parameter
Name: Kelvin
Type: Numeric
Unit: Kelvin
Constant:
Name: 273.15
Type: Numeric
Value: 273.15
Operation
Name: Subtraction
Operation: Subtraction
Type: Numeric
Result
Name: Result
Type: Numeric
Unit: Celsius
Tip
You can right-click an element and use the context menu options to view, edit or delete it.
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).
Note
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.
Manage Functions
You can use the standard grid functions in the dialog as follows:
To edit an existing function, double-click the function or select it and click Edit.
To delete existing functions, select them in the dialog and click the Delete button at the top of the dialog. You can also right-click the function and select Delete from the context menu.
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.)
View Statistics
NEXUS IC provides detailed performance statistics for individual function elements, which can be shown as a hint when you hover over an item with your mouse. These statistics include:
Number of function calls
Total, average, maximum, and minimum computation time
Time to retrieve function parameters
Total time including parameter retrieval
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.
When editing a function, statistics are only shown if you enable the Show Statistics option and then hover over an element.
Handling Null Values
Null values can significantly affect calculations and comparisons.
General Behaviour
Arithmetic Operations: Any calculation involving a null will return null. Example: 2 + null = null
Comparisons: Any comparison involving a null will return false. Note that this includes comparing null to null, which also returns the value defined for the False case in a Comparison element. This behavior aligns with standard practices in the IT industry for handling nulls in data.
Exceptions
In some cases, it’s required to produce a numeric value despite the presence of some nulls. When using operations such as minimum, maximum, or average, null values are excluded from the calculation. For instance, the average of 1 and null is 1. However, if all inputs are null, the result will also be null.
Note
When working with lookups, it’s important to handle null inputs carefully. If a lookup filter is set to null, NEXUS will attempt to find a row matching that null value. This can be inefficient, especially with large datasets. To avoid performance issues, always validate lookup inputs and filters, and skip the lookup if the filters are invalid or null.
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