Configure Functions
Under , you can create, edit and delete functions.
The Functions dialog lets you build and maintain customised calculations, referred to as functions, which can be reused throughout NEXUS IC. Functions can be referenced, for example, from Asset Information Groups (AIGs) fields, Event fields and Report Sources.
You define a function by dragging and dropping individual elements into the Function Editor (right-hand side of the dialog) and connecting them to control how data flows through the calculation.
Functions are a core building block in NEXUS IC. They are used extensively in risk models (for example, to define models, matrices and parameters), asset information (such as corrosion rates, retirement dates, pressures and wall thicknesses) and event definitions (for example, calculating remaining wall thickness or span lengths).
See the sections below for detailed information:
Create Functions
To create a new function:
Click Add at the top of the Configuration - Functions dialog.
Enter a name for the function and optionally assign it to a category.
In the lower part of the dialog, click
next to ELEMENTS to expand the element list. Drag a function parameter from the ELEMENTS tree into the design area on the right.Every function must contain at least one function parameter.
For information about individual function elements, see Function Elements.
Add further elements as required. For example, to create a function that converts temperature from Kelvin to Celsius, add:
A function parameter to capture the temperature in Kelvin
A constant element with the value 273.15
An operator element for subtracting the constant value from the value in Kelvin
A result element to output the value in Celsius
Double-click each element to define its properties. The available parameters depend on the type of the element, but typically include name, type, unit and default value. For the temperature conversion example, configure the elements as follows:
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
Right-click an element to view, edit or delete it using the context menu.
Connect the elements by dragging from the output square at the bottom of a source element to a target element. The drag must start from the source element’s output square, but can end anywhere on the target element.
Note
To replace an existing connection, drag from an output square to the specific input square you want to overwrite.
To remove a connection, drag it off the input square and drop it onto an empty part of the design area.
A single output can be connected to multiple inputs.
Click Show Results to display intermediate values for the function elements in the design area.
You can test the function as described in Test Functions.
Click OK to save the function.
Manage Functions
Under , in the Configuration - Functions dialog, you can manage functions using the standard grid functionality:
To edit a function, double-click it 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 functionality.
To see if a function is being used elsewhere in the application, click Connections.
Functions and function elements in NEXUS IC are unit aware. For example, if an Addition element receives one input in metres and another in millimetres, NEXUS IC automatically applies the appropriate scaling factor before performing the calculation. The direction of the scaling depends on the output unit selected for the operation.
For many elements, you can explicitly select the output unit. NEXUS IC is not dimensionally aware; for example, dividing a length by a time does not automatically result in a velocity unit.
View Statistics
NEXUS IC can record performance statistics for individual function elements. These are displayed as a hint when you hover over an element and include:
Number of function calls
Total, average, maximum and minimum computation time
Time spent retrieving function parameters
Total time including parameter retrieval
To view statistics, navigate to . If a function has been executed and its results cached, the statistics appear when you hover over its elements.
When editing a function, statistics are only shown if Show Statistics is enabled.
Handling Null Values
Null values can significantly affect calculations and comparisons. The following rules apply.
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
For some operations, a numeric result is required even if some inputs are null. For minimum, maximum and average operations, null values are ignored.
For example, the average of 1 and null is 1. If all inputs are null, the result is null.
Note
When using lookups, handle null inputs carefully. If a lookup filter is set to null, NEXUS IC attempts to find a matching row with a null value, which can be inefficient for large datasets. To avoid performance issues, validate lookup inputs and skip the lookup when filters are null or invalid.
Test Functions
You can test functions both individually while editing them and in bulk across multiple functions. Testing helps verify that a function produces the expected results and continues to behave correctly after changes.
Test Individual Functions
You can test a function while editing it in the Edit Function Definition dialog.
Check Intermediate Results
To evaluate a function using specific input values and see intermediate results:
Open the function for editing.
On the Tests tab, enter values in the Input Values section at the bottom of the tab.
Make sure the Show Results button is enabled.
The function is evaluated using the entered inputs. The values of input parameters, intermediate elements and the final result are shown next to the corresponding elements in the design area.
Create Test Cases
You can define test cases for a function on the Tests tab. Test cases allow you to verify a function as you create it and to re‑validate its behaviour after changes.
To create and run a test case:
On the Tests tab, click Add.
In the Add Function Test dialog, enter the test details:
Field/Checkbox Name
Description
Name
Enter a name the uniquely identifies the test case.
Comments
Optional notes describing the purpose or expected behaviour of the test.
Error Result
Select this option if the function is expected to return an error defined by an error element. The test passes if the expected error is returned and fails if no error occurs.
Result
The expected result of the function for this test case.
Fields under Test Values
The fields under this dialog section correspond to the input parameters that you specified for the function. Enter the input values that you want to test for each parameter.
Click OK to save the test case.
Back on the Tests tab in the Edit Function Definition dialog, click Execute Tests to run all test cases for the function.
Result
The test result columns are updated for each test case:
Test Result shows the expected result defined in the test.
Actual Result shows the value calculated by the function.
Pass/Fail shows Pass if the actual result matches the expected result, or if an expected error is correctly returned. Fail is shown in all other cases.
Error Result shows Yes if the test case was configured to expect an error.
If Show Results is enabled, the values shown next to the elements in the design area are updated. If an element receives an input of an unexpected type, a yellow error message appears at the bottom of that element explaining the issue. Similar messages are shown for other error conditions, such as division by zero.
By default, the element values shown correspond to the first test case in the list. To inspect values for a different test case, select the test case and click Inspect in the toolbar.
Tip
When creating test cases, it is recommended that you include at least one test that produces a valid result. If the function can return errors (see Error), include at least one test case for each possible error condition.
Test Functions in Bulk
If test cases are defined for multiple functions, you can execute them together from the Configuration – Functions dialog under .
To generate a test report:
In the Configuration – Functions dialog, select the functions to test.
Click Execute Tests on the toolbar.
NEXUS IC executes all test cases for the selected functions and displays the results in the Function Tests dialog. Results are grouped by function and can be expanded to view individual test case outcomes.
Tip
To quickly identify failed and passed functions, you can group the results by pass or fail status. Right-click the Pass/Fail column header in the Function Tests dialog and select Group.
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