Function Elements

Function Parameter

A function parameter is an input to the function. For example, in a function that calculates the circumference of a circle given a radius value, you can add a Function Parameter element, that provides the ability to enter a value for the radius. This value is then multiplied by 2 and by the value of pi to calculate the circumference of the circle. When defining a Function Parameter, you need to give it a name and a data type. Function Parameters may be alphanumeric, whole numbers, real numbers, boolean values (true or false), dates, times, or combined date/time values.

If you tick “Allow Null Inputs”, you can specify a Default Value to be used when the input is null.

Constant

Constant function elements are used when a data value is known and will remain the same for every situation where the function is run. When defining a Constant, you need to supply a name for the constant, the value of the Constant and the field type. Constants (like Input function elements) can be alphanumeric, numbers, Boolean values (true or false), or date/time values.

Colour

Colour function elements are like a Constant element, but they are always Whole Numbers. When you edit a Colour, it presents you with a colour picker. Click the arrow to choose a colour from the list, or click the button to choose a custom colour.

Operation

Operation function elements provide data manipulation functions. Operators take input data from various sources such as Input, Constant or Decision elements, or even other system or user-defined functions. You can drag in as many inputs as you like to an Operation.

Addition, Subtraction, Multiplication, Division, Modulus and Power are all arithmetic operations. Note that Modulus only works with whole numbers as inputs.

Minimum, Maximum and Average take the minimum or maximum or average of all their inputs. (If some inputs to a Minimum, Maximum or Average are null, those null inputs will be ignored.)

Coalesce works the same as SQL’s COALESCE operator: if the first input is not null, it will return that first input. If the first input is null, it will look at the second input. It will keep looking along its inputs until it finds one that is not null. If all are null, it returns null.

Any True and All True are logical operations. They expect inputs of type Yes/No, and you should set their output type to Yes/No.

For some operations the behaviour with more than two inputs is obvious; for others, less so, and you should experiment to confirm that you understand it.

Bitwise / Logical Operation

These are similar to Operation elements, but carry out bitwise operations. Bitwise / Logical Operation elements can be configured for And, Or, Xor (eXclusive Or), or Not. You should set the Result Type of a Bitwise / Logical Operation to “Whole Number”. They differ from Any True and All True in that Bitwise / Logical Operations work on all bits of a whole number, rather than just on a yes/no basis. For example, 1010 AND 1001 = 1000; 1010 OR 1001 = 1011; etc.

Concatenate

These are similar to Operation elements, but are designed to concatenate several inputs together (converting them to Alphanumeric if necessary) and give an Alphanumeric as an output. You should set the Result Type of a Concatenate element to “Alphanumeric”.

The Format property can be used to control how values are converted to strings, and how the final concatenated string appears. (Programmers may find this similar to the concept of printf format strings in C.) If the input is a whole number, you can put %d in the format string at the point where you’d like that whole number to appear. If the input is a numeric, you can put %f. You can put other text in the string literally as desired, and to get a % symbol, put %%. So a format string like “There are %d apples, which fill %f%% of the basket” would result in output like “There are 1 apples, which fill 12.34% of the basket”. If your input types don’t match the format string you’ve specified, you’ll get an error message. So in this example we’ve assumed that the first input is a whole number. If it was in fact a numeric, you’d see an error like “Format is invalid for for the inputs.”

You can put a number between the “%” and the letter to specify the width. If the number turns out to be less characters than the width you’ve specified, it will be padded with spaces. You can put a “.” after that width (or just directly before the “%”) followed by a precision, to specify the number of decimal places for a numeric. So “%2d” might result in output like ” 1”; “%.3f” might result in output like “12.340”.

You can use types other than “d” for Whole Number and “f” for Numeric. Here’s a list:

Type	Output
d	Decimal. Input must be a Whole Number.
u	Unsigned decimal. If input is negative, it will be shown as positive. Input must be a Whole Number.
e	Scientific: you will get output like “1.234E1”.
f	Fixed: you will get output like “12.34”.
g	General: you will get fixed or scientific output, whichever is shorter.
n	Number: you will get a number with thousand separators, like “123,456.78”.
m	Money: you will get a currency output, formatted as specified by your settings in Windows control panel.
s	String. If one of your inputs is a string, you can use “%s” to put it in the format string: “There are %d %s, which fill %f%% of the %s”. If you specify a precision, like “%.3s”, the string will be limited to at most that many characters — any remainder will be truncated.
x	Hexadecimal. Input must be a Whole Number.

Decision

Decision function elements in the NEXUS IC database are explained below:

Case

Evaluates a list of conditions and returns one of multiple possible result expressions. If the Case input does not equal any of the defined conditions, then the Default is returned. The concept is similar to switch statements in many programming languages, or nested IF functions in Excel.

In the above example, the Case object is configured so that:

• When Input Variable matches Option 1, Result 1 will be output. (This is indeed the path taken in this case.)
• When Input Variable matches Option 2, Result 2 will be output.
• When Input Variable does not match any of the “When” options, the Default, Result if no Match, will be returned.

Compare

Compares two inputs (comparators) and returns one of two values depending on whether the inputs match. Comparisons available in the Compare decision include: Equals (=), Not equals (<>), Greater than (>), Less than (<), Greater Than or Equal (>=), Less Than or Equal (<=).

Matrix

Evaluates a number of inputs and returns the looked-up value. You can add more inputs with the Add Column Input and Add Row Input buttons. If you have several column inputs or several row inputs, they must all be matched for that cell to be picked. That effectively means that this is an n dimensional matrix. The 2-dimensional case (with one column input and one row input) is the simplest and most common, but if your situation demands more dimensions, add inputs to suit.

When no cells are matched, the Default Value will be used. You should ensure that the result type of the Default Value is the same as the result type of the Matrix.

Range

The Range element is similar to the Case element, except that you specify a range of input values for each case, rather than a single specific value. Range evaluates a numeric input against a series of numeric ranges and returns the found value. For each range, you specify the Lower (>=) and Upper (<=) as numeric values, and then choose a Result from the available inputs. A Range element needs at least three inputs: one to supply the Case value that will be used to decide which range is matched (if any); one for the Default Value which will be used if no range is matched, and one to define a result for the first range. If you want more than one range, add more than three inputs. If you want to re-use one input several times, drag that input onto the Range element several times. If multiple ranges match the input, the first matched range will be used, so if your ranges are 1 to 5 and 2 to 6, only inputs of greater than 5 will match the second range.

Lookup

Returns a summarised value from various sources of data within the NEXUS IC database.

So if you wanted to (say) fetch an Asset Information field from an Asset, you could choose that Asset Information field as the Result Field, and connect the Asset Input to a Function Parameter which will be fed from Asset. Almost any field from almost any table can be used as the Result Field.

You can also aggregate data from the Result Field by selecting an Aggregate: Max, Min, Average, Sum, Standard Deviation or Count. If you select an aggregate, NEXUS IC will make a list of all the results and aggregate as appropriate. For example, if you chose a field from an event form as your Result Field and Min as your Aggregate, then NEXUS IC will look through all the events on that asset, and return the minimum value from that field in that list of events.

If Aggregate is left at None, you should ensure that your filters allow only one value to be returned. If multiple values exist, the Lookup will return the first value it finds.

If the Result Field you select has a Display Type different from its Field Type, then you can set the Return Type to be either the Functional Value or the Display Value. The Display Value is usually human-friendly text, whereas the Functional Value is the underlying numeric key value, which may be useful for feeding into subsequent function elements for comparisons, etc.

You can set an Asset Input, if the result table you have selected has Asset or Component_ID as a key field (for example, if your Result Field is an Asset Information field). Only use this for Asset or Component_ID — for any other table’s key field, add a Filter, as shown below. An Asset Input must have a type of Whole number (not Numeric).

You can set an Asset Filter:

• The default, “No Children”, returns results from just the single asset specified by the Asset Input.
• “This Asset and dependent Assets” returns results from the asset specified, and also from that asset’s children, grandchildren, great-grandchildren, etc.
• “Dependant Assets but not this Asset” does almost the same thing, but leaves out results for the asset specified.
• “Immediate Children” returns results from the specified asset’s immediate descendants, but not from the asset itself, nor from any grandchildren, great-grandchildren, etc.
• “Parent Assets” looks up the tree instead of down, returning results from the specified asset’s parent, grandparent, great-grandparent, etc., all the way to the root of the asset tree.
• “Direct Parents” returns results from the specified asset’s immediate parent.

If you are using an Asset Filter option other than “No Children” or “Direct Parents”, you will typically also want to specify an Aggregate.

If an asset appears in multiple Asset Views, it may have different parents and different descendants in different views. These asset filters will match parents and descendants in all asset views.

You can also specify a Workpack Filter, whose options (Most Recent, All, Specific Workpack) are reasonably self-explanatory.

Filters can be used to filter the list of results that would otherwise be returned to a shorter list (possibly containing exactly one item, thus avoiding the requirement to use an Aggregate). You can drag extra inputs onto the Lookup element for use as Filter inputs.

The first six comparisons (=, <>, >, >=, <, <=) are straightforward.

The various “closest” filters (“closest (either)”, “closest (lower or equal)”, “closest (higher or equal)”, “closest (lower)” and “closest (higher)”) are special. Suppose you want to find the event whose KP is closest to a particular value: for this you would use “closest (either)”. Or suppose you wanted to find the event just before this one; i.e. the event with KP closest to a particular value, but lower: for this you would use “closest (lower)”. And similarly, “closest (higher)” would be used to find the next event after a particular KP.

For “highest” and “lowest” you need specify no input; these simply return the single result that has the highest or lowest value in whatever Field you specified in the filter. (Be aware that using an Aggregate of Max or Min is usually faster than using a filter for highest or lowest.)

“contains” lets you search for a substring within an alphanumeric input. You can use “_” and “%” as wildcard characters, with “_” matching any single character and “%” matching several characters, so “abcde” contains “a_c”, and also contains “a%d”.

All filters must be matched for results to be returned; in other words, filters are implicitly connected by ANDs.

Lookup Optimisation

Lookups may be executed a large number of times, so it may be worth configuring them so that NEXUS can best optimise their execution. Aggregates such as “Max” are more efficient than Filters such as “highest”. In Filters comparisons, “=” is better able to be optimised than <, >, <=, >=.

Results may be cached, so subsequent lookups in a particular circumstance may be faster than the first lookup.

When the return value of a function is deterministic, NEXUS IC may cache the result for a given set of inputs. For example if you have a function to add two numbers, 1 plus 2 always equals 3, so NEXUS IC may enter that result into its cache, so that if it has to calculate that same result again in future, it can simply read the value from the cache rather than actually recalculating. If a function contains a Lookup, NEXUS IC will cache the result only if it is confident that the result is deterministic — i.e. a future run of the function with those same inputs will necessarily produce the same outputs. This might not be the case if, for example, your function contains a Lookup that is returning the closest event to a particular date – if any event is added or deleted, or any event’s date is changed, then the Lookup result could change.

You can help NEXUS IC be confident that a function is deterministic (and therefore potentially make your functions run faster) by tucking each Lookup into its own function. So if you have a function that contains several Lookups, and that function is running slowly, try putting each Lookup into its own function, and then replacing the Lookups in your main function with calls to the new simple functions you’ve just created. NEXUS IC can now consider caching separately for each function.

In general where time is critical, avoid aggregates across tables, aggregates across fields that reference other tables, and aggregates across slow fields.

For small frequently-used tables (a few hundred rows), all the rows in the table will typically quickly get cached and remain cached for the entire run of the application. If the value changes, cache entries are expired as appropriate, then re-cached the next time they are requested by a function. NEXUS IC may also clear parts of its cache if it runs low on memory.

Notes

Notes are used when building functions for reference and documentation purposes. Notes are placed in the Function Builder work space. You should use Notes whenever you think a function is not self-explanatory, where you want to refer to a standard, document changes to a function, etc.

Risk

Returns the aggregate risk value for an asset and all its children in a particular asset view.

Error

In version 6, the function builder includes the concept of errors. You can see errors by, for example, dividing by zero or by feeding an element an input of a type it did not expect.

But you can also deliberately include errors. For example, suppose you have a function whose input must not be 0. You can add a comparison which compares that input to 0, and if true, returns the value of an Error element. If you set the Error value inside the Error element to “Oh no! An 0!”, then when the function has its input set to 0, the user will see that error message output.

The advantage of using an Error element is that it can give a textual description to the user explaining what is wrong without changing the output type of the function — the output of the function might still be of type Numeric. This means that if this function’s output is in turn consumed by other functions, those functions will get a Numeric value as they expected. In this way, functions can chain to other functions, while also giving descriptive messages to the user.

Is Anomalous

You can use this element to check, within a function, if a particular event field causes any Anomaly Triggers to fire. Its input should be an event Header_ID.

Solver

The solver element is used within charts to solve for a particular input parameter of a function — see Chart Template Axis Type for details.

Electronic Corrosion Engineer (ECE)

If you drop an ECE element into a function, it will call Wood’s proprietary ECE library. Set the ECE Result Type to determine which value it will return an estimate for. ECE is a separately licensed feature — contact support@nexusic.com for details.

The Section Start Fe Concentration parameter is optional and can be null. When it is null, supersaturated = true. This relates to the dissolved iron concentration in the water at the inlet, which may be low in Fe, or may be supersaturated with iron carbonate. There are two options. The default setting is supersaturated, assuming that the water has been flowing through carbon steel equipment for some distance before entering the flowline: this would be appropriate if the fluids come from a well completed with carbon steel production tubing for example. When most of the water comes from condensation from water vapour in gas, this setting should be changed to none, which can lead to increased corrosion rates for a short distance at the inlet region. This would be appropriate for a gas overhead line from a separator vessel for example.

Required input parameter units:

• Start Pressure - bar
• End Pressure - bar
• Start Temperature - °C
• End Temperature - °C
• Liquid Holdup - %
• Inlet Pressure - bar
• Inlet Temperature - °C
• Oil Density - °API (API gravity)
• Section Length - m (metres)
• Inside Diameter - m (metres)
• H2S Concentration - Mole %
• CO2 Concentration - Mole %
• Percentage Carbon - Mole %
• Chloride - g/l (Grams per litre)
• Acetic Acid - ppmw (Parts per million by weight)
• Bicarbonate - ppmw (Parts per million by weight)
• Gas Production Rate – MMSm³/d (million metric standard cubic metres per day)
• Oil Production Rate - m³/d (Cubic metres per day)
• Water Production Rate - m³/d (Cubic metres per day)
• Fe Concentration - moles/litre

Function

You can embed an entire other function into this function via the Function element. This is the same as dragging in a System Function or User Function — see below.

System Functions

System function elements in the NEXUS IC database can be broken up into Character functions, mathematical functions and other functions. These system functions are pre- defined and explained below:

Character/String Functions

Function	Description	Example of use
ASCII	Returns the ASCII code value of the leftmost character of a character expression.	ASCII(‘Alphabet’) = 65
Chr	Converts an ASCII code to a character.	CHR(65) = ‘A’
InStr	Returns the starting position of the specified expression in a character string.	INSTR(‘CORPORATE FLOOR’,’OR’, 3) = 14 INSTR(‘CORPORATE FLOOR’,’OR’, 1) = 2
Len	Returns the number of characters of the given string expression.	LEN(‘Alphabet’) = 8
Length	Same as LEN.	LENGTH(‘Alphabet’) = 8
Lower	Returns a character expression after converting uppercase character data to lowercase.	LOWER(‘Alphabet’) = ‘alphabet’
LTrim	Returns a character expression after removing leading blanks.	LTRIM(‘ Alphabet’) = ‘Alphabet’
Replace	Replaces all occurrences of the 2nd given string in the 1st string with a 3rd string.	REPLACE(‘Alphabet’,’ph’,’f’) = ‘Alfabet’
RTrim	Returns a character string after truncating all trailing blanks.	RTRIM(‘Alphabet ‘) = ‘Alphabet’
SubStr	Returns a part of a character expression.	SUBSTRING (‘Alphabet’,0,6) = ‘Alpha’
Upper	Returns a character expression with lowercase character data converted to uppercase.	UPPER(‘Alphabet’) = ‘ALPHABET’

Mathematical Functions

Function	Description	Example of use
Abs	Returns the absolute, positive value of the given numeric expression.	ABS(-15) = 15
ACos	Returns the angle, in radians, whose cosine is the given value.	ACOS(.3) = 1.26610367
ASin	Returns the angle, in radians, whose sine is the given value.	ASIN(.3) = .304692654
ATan	Returns the angle in radians whose tangent is the given value.	ATAN(.3) = .291456794
Ceiling	Returns the smallest integer greater than, or equal to, the given numeric expression.	CEILING(15.7) = 16
Cos	Returns the trigonometric cosine of the given angle (in radians).	COS(180 * 3.14159265359/180) = -1
Erf	Gaussian Error function. See https://en.wikipedia.org/wiki/Error_function	ERF(0) = 0
Exp (10^x)	Returns the exponential value of the given numeric expression.	EXP(4) = 54.59815
Exp (e^x)	Returns the exponential value of the given numeric expression.	EXP(4) = 54.59815
Floor	Returns the largest integer less than or equal to the given numeric expression.	FLOOR(15.7) = 15
InvErf	Inverse Gaussian Error Function.
IsNumber	Returns true if the Alphanumeric input can be converted to a Whole Number.	ISNUMBER(“three”) = false
IsNumeric	Returns true if the Alphanumeric input can be converted to a Numeric.	ISNUMERIC(“three point one four”) = false
Ln(x)	Returns the natural logarithm of the given numeric expression.	LN(95) = 4.55387689
Log(x)	Returns the base-10 logarithm of the given numeric expression.	LOG(100) = 2
Log_b(x)	Returns the base-b logarithm of the given numeric expression.	LOG_B(2, 256) = 8
Round	Returns a numeric expression, rounded to the nearest whole number.	ROUND(15.193) = 15
RoundTo	Returns a numeric expression, rounded to the specified length or precision.	ROUNDTO(15.193,1) = 15.2 ROUNDTO(15.193,-1) = 20
Sign	Returns the positive (+1), zero (0), or negative (-1) sign of the given expression.	SIGN(- 15) = - 1
Sin	Returns the trigonometric sine of the given angle (in radians).	SIN(30 * 3.14159265359/180) = .5
SqRt	Returns the square of the given expression.	SQRT(26) = 5.09901951
Tan	Returns the tangent of the input expression.	TAN(135 * 3.14159265359/180) = -1
ToNumeric	Converts the input to a numeric data type. (Use Concatenate to go the other way.)	TONUMERIC(‘123’) = 123 TONUMERIC(TODATE(‘22 April 2005’)) = 38462
Trunc	Returns n truncated to a whole number.	TRUNC(15.79) = 15.7
TruncTo	Returns n truncated to m decimal places. m can be negative.	TRUNCTO(15.79,1) = 15.7 TRUNCTO(15.79,-1) = 10
UnitExample	Used under the hood to provide examples in Configuration ‣ General ‣ Unit Types

Compare Functions

There are a variety of Compare functions (“Compare A = B”, “Compare A < B”, “Compare (A = B and C = D) or (E in (F, G, H) and I = J)”, etc.) They all compare the various inputs in the way described in the function name.

Date/Time Functions

Function	Description	Example of use
CurrentDate	Returns the current system date.	CURRENTDATE( ) = <Today’s current date>
CurrentDateTime	Returns the current system date and time.	CURRENTDATE( ) = <Today’s current date and time>
DateDiff (Day Of Month)	Returns the difference between the day-of-month of two dates. Returns a whole number from -30 to +30.	DATEDIFF (DAY OF MONTH)(2005-04-22, 2006-06-12) = 10
DateDiff (Days)	Returns the number of days between two dates.	DATEDIFF (DAYS)(2005-04-22, 2006-06-12) = -416
DateDiff (Month of Year)	Returns the difference between the month-of-year of two dates. Returns a whole number from -11 to +11.	DATEDIFF (MONTH OF YEAR)(2005-04-22, 2006-06-12) = -2
DateDiff (Months)	Returns the number of months between two dates.	DATEDIFF (MONTHS)(2005-04-22, 2006-06-12) = -13.667
DateDiff (Years)	Returns the number of years between two dates.	DATEDIFF (YEARS)(2005-04-22, 2006-06-12) = -1.139
Day	Returns the Day part of a date.	DAY(2005-04-22) = 22
LastInspectionDate	Returns the last inspection date for a component.	N/A
Month	Returns the Month part of a date.	MONTH(2005-04-22) = 4
NextInspectionDate	Returns the next inspection date for a component.	N/A
ToDate	Converts the input value to date data type.	TODATE(38462) = 2005-04-22 TODATE(‘22 April 2005’) = 2005-04-22
Year	Returns the Year part of a date.	YEAR(2005-04-22) = 2005

Other Functions

Function	Description	Example of use
IsNull	ISNULL(A, B) returns A if A is not null; or B if A is null. See below for details.	ISNULL(<null>, 10) = 10 ISNULL(30,10) = 30
Linear Interpolation	Specify Ymin, Ymax, Xmin and Xmax, and for a given Xset, this function will return Yset.	LINEAR INTERPOLATION(0,0, 2,4, 1) = 2
Length	Calculates length from two parameters, i.e. ABS(Param2 - Param1)	LENGTH(5.418 – 6.254) = 0.836
PassThru	Returns parameter value without modifying its display type.	PASSTHRU(‘Alphabet’) = ‘Alphabet’ PASSTHRU(123) = 123

IsNull: The syntax for this function is ISNULL(check_expression, replacement_value), where check_expression is the expression to be checked, and replacement_value is the expression to be returned if check_expression is NULL. check_expression can be of any type. replacement_value must have the same type as check_expression. Note that an alphanumeric field that contains an empty string is not null — to set the field value back to null, click the “X” button at the right of the field.

User Functions

User functions are functions that have been defined by the Users. They can be further categorised by type.