Custom functions basics

To fully benefit from ILNumerics, it is essential to learn about the dos and don'ts. ILNumerics distinguishes itself by a high execution speed, partly due to a particular memory management. Only by following a few rules you can make use of the ILNumerics memory management speed advantage.

So let's take a look at one of the basic components of a program: functions. A function consists of a head and a body. The head may include a return value, input and output parameters. The body comprises calculations that are based on the input parameters and may result in a return value and output parameters.

As shown in the image above ILNumerics provides different array types that vary in terms of lifetime and where the array is used:

• Array<T> is a local array declared and used inside the function body.
• RetArray<T> is a return parameter used to return a value of a function.
• InArray<T> is a readonly input parameter of a function.
• OutArray<T> is an optional output parameter of a function.

The following example displays a very simple function that rounds down every single entry of the input parameter inArray.

Here, two different types of ILNumerics arrays are applied. While the function body contains a local array Array<float>, the head includes an input array: InArray<float>.

To support immediate, deterministic disposal of array's storages we must implement an artifical scope. In this scope all local arrays created throughout the scope body are retained. Once the scope is left, the arrays are released.

Since we can't access the results in this way, it makes sense to add a return value as displayed in the following:

Here, the ILNumerics array type RetArray<float> is introduced, thus, an arbitrary local array of the type float can be returned. Note, you can only use return arrays once. Afterwards they will be disposed. Thus, the first and only use of the return array must either be an assignment to a local array within the function body or the use of the return value as parameter in other function calls. All array variables / all local arrays may be of the type Array<T>, Logical, or Cell.

If you want to return more than one array, use the output array type OutArray<T>.

The output array above is optional with a default value of null. Inside the function body, it is checked, whether the output array is null or not. If it is not, the function will compute and assign a result value to it. Note, that assignments to an output arrays O is done via assigning to its 'O.a' property in C#. 

The arrays mentioned before are not just available for numeric arrays, but also for cell and logical arrays. Here, you can get more details.

Dos

The following list sums up the recommendations that were mentioned above:

• only use Array<T> to declare local variables
• only use the array parameter types RetArray<T>, InArray<T>, OutArray<T> inside the head of a function
• use artificial scopes inside the function body to make sure that arrays are available within the scope and released once the scope is left

Don'ts

Next to applying the right type of array depending on the situation, it is also important to know which features of the C# language are not supported by ILNumerics:

• ILNumerics arrays always must be defined explicitely. As a result the C# var keyword can not be used, since it is not compatible with ILNumerics memory management.
• Compound arrays such as +=, -=, *= and /= can not be used when referencing a subarray

To learn more about best practices in ILNumerics, check out the following pages:

• general usage
• writing algorithms