Upgrading from ALGLIB 3.x to ALGLIB 4

ALGLIB 3.x held onto numerous legacy API design decisions. However, recent advances in our automatic code and wrapper generation technology allow us to capture more information about program semantics, such as constant and mutable data, in-place changes, reallocations, resizing, etc. Consequently, in ALGLIB 4 we decided to break backward compatibility with the aim of providing more concise API, free from old inconsistencies.

The breaking changes can be divided into two categories:

• high-level changes in the API conventions that affect the entire library in a predictable and uniform way. Such changes are often language-specific, varying across the different editions of ALGLIB (ALGLIB for C++, for C#, etc).
• changes in function signatures that aim to improve API consistency. These primarily are parameters being removed or rearranged. These changes are the same in all ALGLIB editions.

High-level changes in the API conventions

C++ API

ALGLIB for C++ now correctly tracks the const-status of data being passed to ALGLIB. Function parameters that are modified during function execution are now marked as const. This is the only high-level change in the C++ API.

C# API

C# does not track const-status of function parameters, so const-correctness is irrelevant for C# programs. What is important is how we handle different kinds of mutable function parameters, i.e. parameters which have an input value and which are modified after return from the function.

Obviously, the only way to have a mutable parameter of a value type is to pass it by reference. However, there is more flexibility with mutable parameters of reference datatypes. A function can modify it without creating a new reference (modify an array element or an object field). Alternatively, it can create a new reference (perform an array reallocation or construction of a new class instance).

In ALGLIB 3.x all mutable parameters were passed by reference, whether of a primitive datatype or not. Starting from ALGLIB 4.0 we adopt the following conventions:

• mutable parameters of a value datatype are always passed by reference
• mutable parameters of a reference datatype that are modified without creating a new reference are passed by value
• mutable parameters of a reference datatype that can be reallocated are passed by reference

Python API

The question of parameters mutability is also relevant for Python. The language lacks ability to pass parameters by reference, so in ALGLIB 3.x all mutable parameters were included into a return tuple.

Starting from ALGLIB 4.0, Python edition adopts the following convention:

• mutable parameters of a primitive datatype are always included into a return tuple
• mutable parameters of a list/class datatype that are modified in-place (without allocating a new instance) are not included into a return tuple
• mutable parameters of a list/class datatype that can be reallocated are included into a return tuple

Changes in function signatures

The most frequently appearing change is that we stopped using an integer info output parameter to signal success or failure of ALGLIB solvers. It makes the code unnecessarily cluttered because in almost all cases the same solver function has one more output parameter, rep, which can be used to signal success or failure. The fix removes the info output parameter and adds rep.terminationtype field which has exactly the same meaning. More than 95% of changes are covered by this case.

The fix above and several other minor tweaks are fully disclosed in a corresponding issues tracker entry.

Migrating from ALGLIB 3.x to ALGLIB 4

Strongly typed languages: C++, C#, Delphi

When changing the API we adopted the following approach: either it works, or it immediately breaks. It means that in strongly typed languages you can simply recompile your program against the latest ALGLIB release. If it compiles, it definitely means that the migration was successful. If it does not compile, you know where to look.

Python

Due to its dynamic nature, Python does not allow us to check program correctness during compilation stage. Only at runtime it will become apparent that some parameters are missing. Thus, the only way of correctly migrating Python program from ALGLIB 3.x to ALGLIB 4 is check usage of functions that changed in ALGLIB 4.

You can find a list of such functions in the issues tracker entry.

This article is licensed for personal use only.