Enji Blog: Mathematical Notation and Clean Formulas

Our previous blog briefly mentioned that Enjicalc is an Interactive Programming Language based on Mathematical Notation. We also stated how our tool allows flexible variable name definition and how this, in return, helps to improve readability. In this article, we will dive deeper into the topic to explain what Mathematical Notation means and why it is a must for someone working with calculations and design codes. We will also touch on how to make every calculation look better.

As per our favourite wiki, Mathematical Notation consists of using symbols to represent operations, unspecified numbers, relations, and any other mathematical objects and assembling them into expressions and formulas. Mathematical Notation is widely used in mathematics, science, and engineering to represent complex concepts and properties concisely, unambiguously, and accurately.

What sets Mathematical Notation apart is its unique two-dimensional representational approach. On the contrary, the text you're reading and the code used to define a formula are one-dimensional. When you use programming languages to recreate a mathematical formula, you're essentially transforming two-dimensional data into one-dimensional data. This conversion creates a certain barrier to the review process. To illustrate, we present a comparison of a Microsoft Excel formula definition, a Python definition, and the Mathematical definition by Enjicalc, which is identical to the formula (7.9) from Eurocode 2, EN 1992-1-1.

Microsoft Excel:

=(C308 - B3 * (C309/B20) * (1+T250/TH213*B20))/T250

Python:

meanStrainDifference = ( sigma_s - k_t * (f_cteff/rho_peff) * (1 + E_s/E_cm * rho_peff) )/E_s

Enjicalc:

Let's admit — Microsoft Excel for engineering calculations is not just bad; it is a catastrophe. To understand how the result was calculated, first, we need to find the location of the variable used (scroll scroll). Then, we need to verify the engineering logic behind this variable and potentially the variables inside it if the initial function is nested (more scroll). And then, we need to do this process for every single variable in this formula.

Yes, if you are an Excel Super User, you might help yourself with the Evaluate feature, as well as the Trace Precedents feature. But let's agree that endlessly pushing the Evaluate and Remove/Show Precedents buttons is also quite mentally taxing when you review hundreds of formulas.

With Python, reviewing speed is better compared to Excel, thanks to the text-based variable name. If the coder is competent and experienced (which is sometimes an issue), large calculations can be split into different functions and files, further improving the review speed. Combined with smart editors like VSCODE, the process of reviewing can be smooth.

But let's compare Python code to Enjicalc.

First, we allow users to produce two-dimensional formulas in the exact same way as defined in the design standard and physics. That means zero barriers to checking the formula itself. Second, we automatically create a formula duplicate with substituted values. That means zero barriers to checking the formula's output. This "zero barriers" to review is precisely what we mean when we say we have reached the pinnacle of readability.

There is one catch — while we automatically allow the creation of a two-dimensional formula using Mathematical Notation, you still need to make sure you define variable names the right way. Let's explore this topic.

Variable definition in scientific calculations

Some typical variable names are widely known and often introduced in the early stage of STEM education. Most are standardised within The International System of Quantities (ISQ) and formally described in a multi-part ISO standard ISO/IEC 80000. From ISO/IEC 80000-1, there is a set of seven Base Quantities, a subset of those quantities, where no base quantity can be expressed in terms of the others but where every quantity in the system can be expressed in terms of the base quantities. You can find these seven quantities below. 

A similar style of symbols is used throughout ISO/IEC 80000, where quantities are described by one letter in a baseline, sometimes including one letter in subscript, superscript, and diacritic. However, this approach to variable definition has a very big problem. To understand this, we need to refer to some written and unwritten rules created by software developers.

In the software development world, different programming languages have different rules around the variable definition. There are many books written about how to write good variable names, and the most famous one is Clean Code by Robert C. Martin, who offers extensive guidance on good coding practices. Here are a couple of points he mentions that must be borrowed by engineers in construction:

• Make Meaningful Distinctions: Differentiate names in a way that explains their usage or purpose. Simply adding numerical increments (e.g., data1, data2) or noise words (e.g., theData, myData) doesn't provide additional clarity and should be avoided.
• Use Intention-Revealing Names: The name of a variable should tell you why it exists, what it does, and how it is used. If a variable requires a comment to explain its purpose, the name does not reveal its intent adequately.
• Avoid Disinformation: Names should not be misleading or imply something that isn't true.
• Use Pronounceable Names: Names should be easy to pronounce and discuss in conversations. This makes verbal communication among developers/engineers about the code/formulas more straightforward.
• Use Searchable Names: Choose names that will be easy to find across the codebase. Longer names will be unique and easier to locate via search tools, which is better than using short, cryptic names, especially for variables that may have broad scope or are used frequently.

And here is the question - with everything you learnt above, does ISO/IEC 80000 have the right approach? It is good to know that "H" represents angular impulse in the mechanics domain, but it also represents height in the space domain. When you mention these different topics in one document, they practically become the same thing and become unsearchable. To understand how serious this problem can become, try to count how many domains beta represents in the design code of your choice.

You can also try to count how many times it was mentioned in your document.

Practical examples

To summarise the above section, your variable needs to be distinctive and needs and have a meaning. Period. If you do not follow these rules, you risk losing control of the intellectual property, which is very often the key to making the contract you procured profitable.

We might make a comprehensive guide in the future on how to define variables in scientific and engineering calculations, but here are a few tips:

TIP 1: If the description is short, include it in the subscript

Let's revisit the example we discussed in the previous section. When you're dealing with two domains in a single document, it's essential to clearly specify which domain each variable belongs to.

When you abbreviate, use your engineering judgement to identify how straightforward your abbreviation is. Remember, every individual has a different mindset and what is obvious to you might not be obvious to others.

TIP 2: Words are better than letters

You must ensure another engineer understands your variable from the first go. You shouldn't rely on the fact that you defined your variable somewhere in the document. Do not force engineers to waste time scrolling back and forth, trying to understand your variable's meaning.

Even if your variable goes against standards, like with "H" (Height) above, always consider whether your decision will make reviewing more or less mentally taxing.

TIP 3: Follow camelCasing when defining a custom variable

There will be situations when a variable you are creating does not represent a term from physics or is not mentioned in standards. In this case, use camelCasing to define a variable and ensure it adheres to the guide we've detailed in the previous section.

• isCoverCompliant
• isPositive
• concreteClass
• exposureClass
• sectionType

TIP 4: Be familiar with the Greek alphabet

You will not learn the Greek alphabet immediately, but our advice is to have a link bookmarked in your browser for quick access.

Summary

This was a quick introduction to Mathematical Notation. We encourage you to read more about this topic and dive deep into ISO/IEC 80000. If you want to add more to this topic or express disagreements, feel free to email info@enji.io.