Envision Coding

[Loree Naumann]

This program really helped me solidify my interest in the computer science field. It helped expose me to different tools I'll need to succeed in the future and ideas on how to achieve what I want to achieve. I learned so much here and the program has given me a greater motivation to take initiative and work on my skills on my own as well."

"After I was introduced to coding in unity, I found myself staying up late (probably more than I should have) to code and would sometimes sit on my bed just theory crafting new ways to make certain things work in unity. I never expected to become to so addicted to coding so fast."

"My son found his tribe. He already knew he loved programming. This program allowed him to expand his skills. More importantly, he found people that share his interests. He's been on the computer interacting with them daily through Skype and other platforms."

Envision is the Domain-Specific Language (DSL) engineered by Lokad for the specific purpose of the predictive optimization of supply chains. This document is not intended for complete programming beginners, but rather for an audience already familiar with basic programming patterns like Microsoft Excel formulas.

Unlike many scripting languages, Envision focuses on delivering a high-degree of correctness by design, which means capturing as many issues as possible at compile time (the moment when the script is compiled) rather than runtime (the moment when the script is run). Capturing issues at compile time is preferable because whenever the amount of processed data is sizable, a runtime issue can take a long time (several minutes) to manifest itself causing productivity and production reliability problems. This documentation focuses on the compile-time angles of Envision.

All the statements that start with the keyword show indicate that a tile will be displayed. Tiles are the display mechanism provided by Envision. All the tiles present in a script are consolidated in a dashboard.

Beside scalars, Envision supports another mechanism for short-name variables, i.e. omit table names, through a default implicit table. This mechanism is used with dimensions. We will get back to the concept of dimensions in the following.

Variables in Envision can be documented with with a triple-slash /// comment. In order to obtain the structured documentation behavior, the /// has to be put at the beginning of the line, and just before the documented variable.

The Markdown syntax is used for the structured documentation. In the above example, when hovering the variable greeting, the word bold appears in bold due to the use of the ** .. ** delimiters. An structured documentation block can include multiple lines.

Whitespaces placed at the beginning of the line control the level of indentation. In Envision, adding an extra level of indentation is required whenever entering a block, for example:

Envision is sensitive to line breaks. A script is divided into a number of logical lines. A logical line break typically indicates the end of a statement, but it can also indicate a new block - typically when the keyword with is used.

The recommended practice with Envision is to keep lines under 120 characters. When facing very long lines, the backslash can be used to reorganize the code in physical lines of less than 120 characters.

While Envision is sensitive to line breaks, it also offers implicit line continuation that does not rely on the use of backslashes. When the last token of a line is something that requires another token to be found, Envision expects the next line to be its continuation, i.e. the logical line extending to the next physical line. For example:

Conversely, when found at the beginning of a line, the keywords as, over, if, default, sort, scan, by, into, cross and at imply that the current line is a continuation of the previous line.

Envision features a rich library of built-in functions, which provides many capabilities that can not be replicated directly from the language itself. All functions operate on vectors and return vector results as well. Functions are free of side effects, i.e. the values passed as arguments to the functions are never modified by function calls.

Function calls start with the name of the function followed by an opening parenthesis (, then the arguments and finally the closing parenthesis ). For example, the abs() function returns the absolute value of a number:

More complex functions require several arguments. Most functions use positional arguments where arguments are specified according to their position in the function call. For example, the startsWith() function takes two text arguments and returns true when the text provided through the first argument starts with the text provided through the second argument:

Finally, certain advanced functions may contain a dot (.) in their name. This dot is only used for namespacing purposes, i.e. to clarify that multiple functions are closely related. However, there is no special semantic associated with the name suffix before the dot. For example, the function lastForex() returns the last known date, in Lokad, for a conversion rate between the currencies USD and EUR.

The function lastForex() is obviously semantically related to the function forex(), which provides conversion rates at any point in the past, but otherwise deciding to call this function lastForex() rather than lastForex() is a (somewhat) arbitrary choice from the Lokad teams.

In Envision, a process is a special sort of function that takes vectors as arguments instead of scalar values. The most frequent processes es the aggregators. The processes benefit from call options in addition to their regular function arguments.

These options provide general mechanisms that are similar across many functions. They are introduced by specific keywords such as at, by, sort or scan. For example, the following script illustrates how the lowest priced product can be extracted from a table:

Advanced remark: call options frequently hint about the degree of data parallelism that can be achieved by the underlying implementation of the function call. Some options, like by, tend to indicate that data can be partitioned, offering the possibility to speed-up the computation by processing groups independently. Some options, like scan, tend to indicate that the data has to be processed in sequence, preventing data parallelism.

The keyword with is used to introduce a block that is defined by its higher indentation level (just like in Python). The variable x is restricted to the block introduced by the with keyword. This block ends with the return statement. Attempting to use either x past the return statement would yield a compiler error.

Then, a with scope can be used to return multiple variables in what is known as a tuple, a collection that is ordered and that has its length fixed at compile time. The script can be rewritten as:

The use of parentheses in the return indicates a tuple. The tuple is deconstructed directly upon assignment. However, the deconstruction can also be done separately, as illustrated by:

Here a pair (x, y) is returned, but assigned to a single tuple value x. The name x is used on purpose, twice in two distinct scopes, to illustrate the scoping mechanism. However, tuples cannot be assigned to variables: the only thing that can be done with a tuple is to deconstruct it into multiple variables.

The x tuple returned is distinct from the x text within the with block. Naming-wise, the collision is avoided: an outer variable does not collide with the with block. However, the with block can leverage variables that are assigned above it, as illustrated by:

When calling a function that returns a tuple (or when deconstructing a dimension), some of the elements may not be used. This triggers an unused assignment warning. In order to clarify that the intent is to ignore the element, a discard should be used. One indicates that a variable is a discard by assigning it the underscore (_) as its name.

Every variable is originally constructed based on one or several primitive data types, or types for short. These types reflect the nature of the information (e.g. text or number). In Envision, all types are identified and validated at compile time, i.e. Envision is a strongly typed language. Non-primitive types include, for example, tuples that are a collection of types. In this section, all the primitive data types are reviewed. All the more complicated types processed by Envision are built on top of those primitive types.

The numerical precision chosen in Envision is a tradeoff between compute performance, precision and simplicity. In practice, operations performed with these numbers usually deliver a 1/1,000,000 precision that vastly exceeds the requirements as far as supply chain optimization is concerned. Yet, if the goal is to compute the exact balance sheet of a large corporation down to the last cent, this precision is insufficient.

Advanced remark : The Envision numbers are primarily internally processed using the IEC 60559:1989 (IEEE 754) standard for binary floating-point arithmetic, i.e single precision. We do not expose higher precision numbers to supply chain scientists because our experience indicates that it would put an extra burden on them for little or no benefit. However, Lokad moves internally to double precision whenever relevant, as is the case with accumulators for example. Our goal is to constantly achieve higher-than-necessary precision from a supply chain perspective, without needlessly throwing processing power at unstable numerical recipes that should have been avoided in the first place.

The UTF-8 encoding ensures that virtually all non-latin alphabets (eg. Chinese characters) can be processed by Lokad as well as Emoji and Dingbats. The latter prove themselves very useful for building highly visual yet concise reports with Lokad.The limitation of 256 characters is a tradeoff between compute performance and expressiveness. This limit is vastly sufficient for all supply chain purposes, including product labels and even the longest barcode identifiers. By enforcing a hard limit on the text length, Envision eliminates the entire class of out of memory exceptions that plagues regular programming languages whenever large amounts of data are processed.

3a8082e126