Function Elements

You can access function elements when you create or edit a function under Configuration ‣ General ‣ Functions and you expand ELEMENTS on the Elements tab.

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.

Case

This is a decision function element. It 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.

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.

Compare Two Inputs

This is a decision function element. It 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 (<=).

Concatenate

This is similar to the Operation element, but is 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 %%.

For example, the format string “There are %d apples, which fill %f%% of the basket” would result in the output “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 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 an output like ” 1” and “%.3f” might result in an output like “12.340”.

You can use types other than “d” for whole numbers and “f” for numerics. Find below the possible types:

Type	Output
d	Decimal. Input must be a whole number.
u	Unsigned decimal. If the input is negative, it will be shown as positive. Input must be a whole number.
e	Scientific. You will get an output like “1.234E1”
f	Fixed. You will get an output like “12.34”.
g	General. You will get a 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 the 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 and any remainder will be truncated.
x	Hexadecimal. Input must be a whole number.

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.

Electronic Corrosion Engineer (ECE)

If you drop an ECE element into a function, it will call Wood’s proprietary ECE library. Specify 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 following ECE result types are available:

• Bottom of Line Corrosion Rate

• Top of Line Corrosion Rate

• Fe concentration

• pH

• Pitting Corrosion Rate

The input parameters can be linked to Asset Information Fields to allow the calculation to work automatically for all assessed assets.

The required input parameter units are:

• 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

The Section Start Fe Concentration field 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.

Error

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

However, you can also deliberately include errors. For example, suppose you have a function whose input must not be 0. You can add a comparison that compares that input to 0, and if true, it 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.

Function

You can embed an entire other function into this function using the Function element. This is the same as dragging in a system function or a user function from under FUNCTIONS on the Elements tab.

When editing the parameters of the function element, you can select the required function from the Function field. You can select either a system function or a user function as described below:

• System Functions

  System functions are predelivered functions and are listed with the Function Category System. For information about the available system functions, see System Functions.

• User Functions

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

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.

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.

Lookup

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

For instance, if you need to fetch an asset information field from an asset, you can select that asset information field as the Result Field, and connect the asset input to a function parameter that will be fed from the asset.

For information about setting up the fields for a lookup function, see Edit Lookup Dialog.

Lookup Optimisation

Lookups may be executed a large number of times, so we recommend that you configure them so that NEXUS can best optimise their execution. Consider the following lookup optimisation tips:

• Aggregates and Filters: Aggregates (for example, “Max”) perform better than Filters (for example, “highest”). Additionally, “=” is more optimisable than “<,” “>”, “<=,” or “>=” in Filters.

• Caching Results: 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 caches the result for a given set of inputs. For instance, consider a function that adds two numbers: 1 plus 2 always equals 3. In this case, NEXUS IC stores this result in its cache. When the same calculation is needed again, the system retrieves the value directly from the cache, avoiding redundant recalculation. However, when a function involves a Lookup, caching behaviour changes. NEXUS IC will cache the Lookup result only if it is confident that the outcome remains deterministic. In other words, if you rerun the function with the same inputs, it will consistently produce identical outputs. Lookups tied to dynamic data (such as finding the closest event to a specific date) may not exhibit this determinism. If events are added, deleted, or their dates change, the Lookup result could vary. To ensure deterministic results and thus enhance performance, consider organising each lookup into separate functions (see Function). If your main function contains several Lookups and runs slowly, create individual functions for each Lookup. Then replace the Lookups in your main function with calls to these new simple functions. By doing so, NEXUS IC can optimise caching separately for each function.

• Avoid Slow Aggregates: In time-critical scenarios, avoid aggregates across tables, aggregates across fields referencing other tables, and aggregates across slow fields.

• Small Tables: In case of small tables (typically containing a few hundred rows) that are frequently accessed, NEXUS IC efficiently caches all rows. These cached entries remain available throughout the entire application run. If any value within the table changes, the cache entries are appropriately expired and then re-cached when requested by a function. Additionally, NEXUS IC may clear parts of its cache if it runs low on memory.

Matrix

This is a decision function element. It evaluates a number of inputs and returns the looked-up value. You can add more inputs with the +Column Input and +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 you require more dimensions, add inputs that are needed.

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

Notes

Notes are used when building functions for reference and documentation purposes. Notes are placed in the Function Builder workspace. You can use Notes whenever you think a function is not self-explanatory, or when you want to refer to a standard, document changes to a function, and so on.

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. You can use the following operation types:

• 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.

In case you use more than two inputs, the behaviour may not be obvious. We recommend that you experiment with it and confirm that it works as expected.

Range

This is a decision function element. 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 that will be used if no range is matched

• 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 reuse 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.

Risk (Deprecated)

Returns the aggregate risk value for an asset and all its children in a particular asset view. The Risk function element takes the risk assessment ID (RMC_ID) as the input and returns the risk result as an alphanumeric value. This function element has been deprecated and will be removed in later versions. We recommend that you use the Lookup element instead.

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.

See also

• System Functions

• Configure Functions