Tutorial: Naming Conventions

Every software system has its own rules and conventions which require the developers to remember and comply with. Owl is not an exception, for example our rules on broadcasting operation and conventions on slicing definition. In this tutorial, I will focus on the naming conventions of functions.

Pure vs. Impure

Ndarray module contains a lot of functions to allow us manipulate arrays and perform mathematical operations atop of them. The pure functions refer to those which do not modify the passed in variables but always return a new one as result. In contrast, impure functions refer to those which modifies the passed-in variables in place.

The arguments between pure and impure functions will never end. However, the introduction of impure functions to Owl is under many careful and practical considerations. One primary motivation of using in-place modification is to avoid expensive memory allocation and deallocation, this can significantly improve the performance of a numerical application especially when large ndarrays and matrices involved.

Certainly, using impure functions makes it difficult to reason the correctness of your code. Therefore, be careful when you decide to use these function, and always remember that you can use Lazy functor to achieve the same effect but offload the "dangerous task" to Owl. Please refer to this tutorial on "Laziness and Dataflow" for more details.

Many pure functions in Owl have their corresponding impure version, the difference is that impure version has an extra underscore "_" as their ending. For example, the following functions are the pure functions in Arr module.

Arr.sin;;
Arr.cos;;
Arr.log;;
Arr.abs;;
Arr.add;;
Arr.mul;;

Their corresponding impure functions are as follows.

Arr.sin_;;
Arr.cos_;;
Arr.log_;;
Arr.abs_;;
Arr.add_;;
Arr.mul_;;