Computing Engine - Setup & Rules

This is the first section of the in-depth documentation of ILNumerics Computing Engine. For a quick basic introduction go here.

The following description assumes that ILNumerics was installed and activated on your computer. From version 6 the installation step is skipped and all modules are referenced from nuget.org!

Module references (version 4 and 5 only)

On Windows computers and when using the ILNumerics installer version 5, ILNumerics modules are installed into the GAC. Additionally, all modules are also provided in the installation directory (/bin subfolder).

.NET Framework projects reference .NET assemblies from the GAC. When adding references to your project in Visual Studio, chose the Add References Menu, Assemblies -> Extensions Tab and search for "ILNumerics" in the Search box. Make sure to always reference the ILNumerics.Core module, this is always required. For writing mathematical algorithms include the ILNumerics.Computing module and (optionally) the ILNumerics.numpy module too! Toolboxes come as individual modules which are referenced as required.

.NET Core projects are not aware of the GAC. Hence, you can reference the required assemblies from the installation folder. The default location is:

C:\Program Files (x86)\ILNumerics\ILNumerics Ultimate VS\bin

Additionally, add the following nuget package, using "Manage Nuget Packages":

Microsoft.Windows.Compatibility

In order to finish the setup of your project, attempt to build the project! A dialog box will pop-up and the ILNumerics extension will prepare your project for you. Following short video shows all steps for .NET Core projects:

Useful Namespaces and imports

The following directives should be added at the beginning of your code files. They save a bunch of namespace and class specifiers and make your code a lot more readable. Note that our code examples throughout this documentation imply that you have these directives defined (without repeating that boilerplate code). When copying example listings into your app locally you will likely have to add them manually.

Change Code ⇾ Press Play

C#-Code

using ILNumerics;                 // contains the main array classes, useful types, enumerations and extensions. 
using ILNumerics;                 // contains the main array classes, useful types, enumerations and extensions. 
 
using static ILNumerics.Globals;  // gives direct access to important ILNumerics keywords: full (indexing), eps, ellipsis, ...
 
using static ILNumerics.ILMath;   // gives direct access to all static array functions in the Computing Engine 
                                  // (The ILMath class is one of the rare types using the 'IL' prefix, still.)

...and for Visual Basic:

Change Code ⇾ Press Play

Visual Basic-Code

C#-Code

Imports ILNumerics                 ' contains the main array classes, useful types, enumerations and extensions. 
Imports ILNumerics                 ' contains the main array classes, useful types, enumerations and extensions. 
 
Imports ILNumerics.Globals     ' gives direct access to important ILNumerics keywords: full (indexing), eps, ellipsis, ...
 
Imports ILNumerics.ILMath      ' gives direct access to all static array functions in the Computing Engine 
                               ' (The ILMath class is one of the rare types using the 'IL' prefix, still.)

Note, that in order to use numpy array style and / or numpy array extensions, - subarray features a.s.o. you must simply reference the module ILNumerics.numpy in your project. No other actions (imports) are required in code. The reference makes all array extension methods available. If you are mostly working in numpy style, consider adding another using directive (C#):

using static ILNumerics.numpy;

This includes all static computational functions from the ILNumerics.numpy class without having to write numpy.sum etc. explicitly.

Limitations on C# language features

Before learning the details of what can be done with ILNumerics, let's accept some limitations! The following features of the C# language are not compatible with the array types of ILNumerics and their use is not supported:

The C# var keyword in conjunction with any ILNumerics array type, and
Any compound operator, like +=, -=, /=, *= and so on. To be precise, these operators are not allowed in conjunction with the indexer on arrays. So A += 1; is allowed. A[0] += 1; is not! If you find this rule too hard to remember, we suggest not to use compound operators at all.

Limitations on Visual Basic language features

The type for all arrays must be defined explicitely. Just like the var keyword in C#, in Visual Basic it is not allowed to omit array declarations:

Change Code ⇾ Press Play

VB-Code

C#-Code

Dim A = rand(5,4,3)   ' NOT ALLOWED!                 '
Dim A = rand(5,4,3)   ' NOT ALLOWED!                 '
 
Dim A as Array (Of Double) = rand(5,4,3)   ' Correct

Function Rules - Overview

Performance is made out of only three simple rules! They are described in detail in the next section and summarized in the following example function:

Essential function rules of ILNumerics: The first rule declares specific array types for input parameters and return values in function declarations. The second rule creates artificial scopes around the function body and the third rule handles assignments to output parameters.

Computing Engine Function Rules