Array Styles

ILNumerics arrays are compatible with both: numpy and Matlab & Co. Both frameworks share a set of common semantics: n-dimensional, rectilinear arrays of common element types, subarray read / write and array operators. However, both bring their specifics too: storage format, broadcasting rules, and advanced indexing show individual behavior. Users wanting to access those features must explicitly decide for an array style.

Configuring the Array Style ...

... locally

The style for handling arrays is set for each thread individually:

This setting affects the current thread only! When running multiple computational threads it must be configured on each thread individually.

... Globally

The default array style is ILNumerics.ArrayStyles.ILNumericsV4, which is also configurable: the initial value for new threads is determined from ILNumerics.Settings.DefaultArrayStyle. A safe way to configure the array style globally, is to configure the default style also. Make sure to do this early enough in the program:

Most users configure the required array style once and stick to it throughout the program. In this case you may only read the corresponding parts in this documentation and ignore the respective other features.

... temporarily

Alternatively, you can take the best of both worlds: ILNumerics.Array<T> can be used in mixed styles. You may temporarily switch the array style anywhere within your code. This method is recommended for library developers having to ensure that their code works regardless of the current global configuration. It is also useful when sharing code with fellow developers.

Within the marked region / code block the correct array style is configured to make the code execute correctly. And after the marked region was left the former setting is restored automatically and robustly. No global setting is changed. No unwanted side effects are introduced.

Two similar approaches exist:

Approach 1: Using the scope

The most simple way is to configure the required array style directly when entering the artificial ILNumerics scope:

Approach 2: Settings.Ensure(()=>...)

This approach is useful for feature picking within a single function. Arbitrary small regions of code can be configured for a certain style this way:

Both methods are equally robust against unexpected exceptions. It is recommended to specify the array style explicitly for each public function you create which is exposed to / callable by unknown code.

What is controlled by Settings.ArrayStyle?

The setting of ILNumerics.Settings.ArrayStyle controls multiple aspects:

Default storage order: numpy prefers row major order while Matlab arrays are strictly column major arrays. ILNumerics tries to stick to the corresponding behavior according to the array style.
Broadcasting in binary operations aligns the dimensions of both arrays, starting at the last dimension (numpy) or at the first dimension (Matlab). Obviously, this matters most, when both arrays have different number of dimensions.
The binary operators +,-,*,/,% defined on ILNumerics arrays with integer elements perform 'saturation' in Matlab array style: computations are performed as double precision floating point numbers and rounded to the nearest integer afterwards. In numpy array style these operators work with the corresponding system integer datatypes directly.
Indexing and subarray creation & modification involve certain subtleties, which are listed here.
The minimum number of dimensions of arrays is 0 for numpy. 0-dimensional scalars can be created only in numpy array style (once created they can be used in both styles, though). Matlab, on the other hand, considers any array as a matrix or higher dimensional array and gives them at least 2 dimensions.

Requirements

In order to configure ILNumerics for ArrayStyles.numpy and to utilize any numpy specific extension method on ILNumerics arrays the module ILNumerics.numpy must be referenced by your project.