Matlab arguments validation

Matlab arguments validation syntax is generally recommended over the legacy validateattributes. The arguments specification coerces the data to fix the class declaration given if possible, and errors otherwise.

  • Default values are easily specified, which required such verbose syntax before.
  • only a single class can be specified
  • recall the .empty method of most Matlab classes e.g. datetime.empty() that allows initializing an empty array.

Caveats

A downside of the Matlab argument validation syntax is that they are enacted at runtime, so repeated specification may entail increased CPU burden. It seems that Matlab JIT could optimize these away.

It appears that Octave 7.x might be adding the ability to ignore the arguments syntax until the functionality is added to Octave. Older versions of Octave simply error if arguments syntax is used.

Python distutils deprecation

The deprecation of Python distutils has been a decade in the making, and is finally being formalized in PEP632. Setuptools 49.1.2 vendored distutils, but has experienced some friction in setuptools 50.x since so many packages monkeypatch distutils due to the little maintained status of distutils for several years.

With distutils proposed deprecation in Python 3.10, migration to setuptools is a topic being worked on by major packages such as Numpy. Aside from major packages in the Scipy/Numpy stack, I don’t recall many current packages setup.py relying on distutils. However, there is code in some packages using import distutils that could break.

I applaud the decision to remove distutils from Python stdlib despite the fallout. The fallout is a symptom of the legacy baggage of Python’s packaging. Non-stdlib packages like setuptools are so much more nimble that sorely needed improvements can be made more rapidly.

Notes

What value does modern Fortran add?

For scientists, engineers and other performance-sensitive coders modern Fortran offers immediate advantages in developer time savings. The clarity, conciseness and power of modern Fortran are widely available in contemporary compilers. This brief post was motivated by viewpoints encountered including:

  • those whose boss insisted on Fortran 77–they didn’t know anything newer than Fortran 90 existed.
  • those who thought essentially no compilers supported newer than Fortran 95 standard (in calendar year 2018).

To be effective with programmer time, one generally shouldn’t needlessly upgrade all Fortran 77 code to modern Fortran, since Fortran has always maintained good backward compatibility. However, new and upgraded Fortran code should almost never be written in Fortran 77 unless specific job conditions dictate. Of course, Fortran 66 / Fortran IV is little supported and will need to be upgraded to Fortran 77 syntax, which is very similar except for file I/O.

New Fortran code should at least use Fortran 2003, which is universally supported by current compilers. In our work, including in HPC environments, Gfortran and Intel oneAPI are widely supported, so we use Fortran 2008 features in virtually every program.

Modern Fortran support

The compilers easily available supporting modern Fortran include:

  • Gfortran: Most of Fortran 2008 and much of Fortran 2018
  • Intel oneAPI: “full” Fortran 2018 support
  • NAG: Fortran 2008
  • LLVM Flang: built from the ground up with Fortran 2018 standard as the target
  • Nvidia HPC: Fortran 2003

Every year or so, Polyhedral updates their list of compilers supporting modern Fortran features.

What did the major Fortran versions add

  • Fortran 95 brought strong N-dimensional array operations. It is a key step toward modern Fortran, enabling arbitrary size (elemental) intrinsic and non-intrinsic procedures. With Fortran 95, one no longer had to to explicitly loop over almost every array operation.
  • Fortran 2003 brought polymorphism and true object-oriented procedures, critical parts of modern generic programming.
  • Fortran 2008 strengthened polymorphism, and baked coarray (distributed parallelism) directly into Fortran, transparently using underlying libraries such as OpenMPI. Improved Fortran software architecture comes through submodule enabled by Fortran 2008.
  • Fortran 2018 strengthened coarray support, and did further important language cleanup such as enabling error stop within pure procedures

Gfortran feature set vs. OS and version

How does Fortran stderr stop return code work?

Summary:

  • stop (1956 Fortran I): return integer on stderr (recommendation)
  • stop (Fortran 77): return integer or constant character – no integer return with character
  • error stop (Fortran 2008): constant character with error code
  • error stop (Fortran 2018): variable character with error code, also allowed inside pure procedure.

Fortran 2018 finally brought the needed behavior for convenient error messages and continuous integration.

Compiler support

CMake and Meson handle automatic detection of compiler support features like error stop.

Fortran 2008 error stop with constant code:

Fortran 2018 error stop with variable code

Language support

Since Fortran I in 1956, the stop statement has generally displayed a return code to indicate an error if an integer value was provided. Over time, stop statement behavior has changed to allow more refined signaling on program stop.

Fortran I 1956

stop without return code; stop execution normally

stop

stop integer return code

stop 1

The Fortran 2008 and 2018 standards recommend that the error code be returned on iso_fortran_env: error_unit, which was first defined in Fortran 2003 standard. Earlier standards don’t say where the error code should go. Through Fortran 2018, stop with integer code is still normal program termination.

Fortran 77

stop may instead return a constant scalar character like “goodbye”. This generally sets stderr return code to 0, that is, no error is indicated.

For continuous integration, having a reliable way to indicate error behavior is crucial. For HPC, indicating abnormal conditions to the shell is also vital to avoid wasted resources on runs that suffered a computational error.

error stop

Fortran 2008 brought the long overdue error stop statement. stop still indicates normal program termination, and can for example stop individual images in a parallel executing program. Say an individual cell in a 3-D simulation did not find a stable solution. Depending on the simulation, that can be OK, perhaps set that value to NaN and stop with an error code on stderr, while letting the other images continue running.

However, in other types of simulations, an early failure to converge to a solution in a cell may invalidate the entire simulation taking a month of CPU time. Instead of writing cumbersome external checking code, the programmer can instead use error stop to reliably terminate all images when a critical failure is detected.

Fortran 2008

error stop with constant string or integer code (both return non-zero exit status on stderr)

use, intrinsic:: iso_fortran_env, only: stderr=>error_unit

write(stderr,*) 'the failure was in ' // failedmod

error stop

Fortran 2018

error stop with variable scalar string or variable integer code. A vital addition of Fortran 2018 is that error stop can be used within pure procedures, a very commonly needed use case.

Fortran 2018 error stop variable character string allows for cleaner syntax, for example:

error stop 'the failure was in ' // failedmod

Fortran maximum name lengths

Ancient Fortran code readability is impacted by the restrictions on variable length that could lead to inscrutable variable and procedure names. The Fortran 2003 standard raised many of these limits to lengths that might only be a factor for auto-generated code with internally used very long names. If going beyond the usual name lengths, it’s a good idea to test across the compilers of interest (including compiler versions) to ensure that the required compiler vendors and versions can support the proposed name lengths.

CMake Fortran name length checks

CMake is a natural for this type of checking. We provide code examples verifying that compilers can support 63 character syntax elements (names for modules, submodules, variables), which is the maximum set by Fortran 2003 standard.

Install Intel oneAPI C++ and Fortran compiler

Intel oneAPI is a cross-platform toolset that covers several languages including C, C++, Fortran and Python. Intel oneAPI including the Fortran compiler is free-to-use and no login is required to download oneAPI. The no-cost oneAPI access is distinct from Intel Parallel Studio that requires a paid license, except for instructional use or to develop open source projects.

Install

Refer to the oneAPI install guide to download the oneAPI Fortran compiler for Linux, MacOS or Windows.

  1. (Windows only) Install latest Visual Studio
  2. install GDB from oneAPI Base Toolkit
  3. Install the remaining packages below with oneAPI HPC toolkit

The oneAPI package options we installed included:

  • GDB
  • Intel MPI library
  • Intel C++ compiler
  • Intel Fortran compiler
  • Intel Math Kernel Library

Usage

As with Intel Parallel Studio, there are slightly distinct usage patterns to access the Intel oneAPI compilers on Windows NOTE: it is NOT recommended by Intel to use ifx.exe or icx.exe directly. You should be using ifort icl icc icpc with Intel oneAPI as with Intel Parallel Studio.

Windows

On Windows a Start menu shortcut for a oneAPI command prompt is installed. CMake et al should just find the Intel compiler when in the oneAPI command prompt. Otherwise run setvars.bat as per oneAPI documentation.

Linux / MacOS

each time you wish to use Intel oneAPI, do

. /opt/intel/inteloneapi/setvars.sh

Get user home directory in Matlab on Windows

GNU Octave understands that ~ tilde is the user’s home directory on any operating system, even Windows. Matlab does not consistently understand ~ as the user home directory.

Fix

We created expanduser.m that works on Linux, Mac and Windows. It returns the absolute path of the user home directory, for example:

  • Linux: /home/username
  • MacOS: /Users/username
  • Windows: C:\Users\Username

Chrome and Edge browsers force dark mode

The Google Chrome and Microsoft Edge web browsers can be forced into “dark mode”. This works on mobile and desktop. In the browser address bar, type:

chrome://flags/#enable-force-dark

There are several settings–try “Enabled with selective inversion of non-image elements”. Not all webpages will work correctly, but most do.