Functions¶
allows you to create, edit and delete functions.
The Functions window enables you to build and edit customised functions which 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 (e.g. corrosion rates, retirement dates, pressures, wall thicknesses etc) and Event Definitions (e.g. functions to calculate remaining wall thickness or span lengths).
Add¶
To add a new function, 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 the ‘+’ 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.) Drag other elements as desired.
Once elements are in the design are at the right, 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.
To edit an existing function, click the Edit button at the top of the dialog, then proceed as above.
To save the function you’re editing, click OK.
To delete existing functions, select them in the dialog and click the Delete button at the top of the dialog.
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 do this, navigate to Configuration > Functions, and if the function has been called and its results cached, the results will be revealed when hovering over a function element. Selecting a function and clicking Execute Tests will call the function. Statistics are also visible when editing a function, by clicking Show Results, then hovering over an element.
You can also 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.
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 object, 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 the right thing is to produce a numeric value despite the presence of some nulls: if you use an operation object to calculate a Minimum, Maximum, or Average, nulls will be 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: the average of null and null is null.)
Tests¶
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, you should write at least one that returns a valid result, and if it’s possible for your function to return an Error, you should write at least one test for each possible error case.
To generate a test report, navigate to Configuration > Functions, highlight all the functions in the function list to be tested, and select Execute Tests. A list of the functions and their test results will be shown in the Function Tests window. The grid will show the columns Name, Comments, Test Result, Actual Result, and Pass/Fail for each function.
Load / Save Template¶
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, etc), and will present a dialog listing all the dependencies it’s found, with a checkbox for each row. Untick any that you don’t want 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 — it will not create a new copy of it. Similarly with any other elements saved in the .function file: asset information fields, lookup tables, etc.