# $Author: saulius $
# $Revision: 9757 $
# $Date: 2022-02-08 07:41:50 +0000 (Tue, 08 Feb 2022) $

Normalise octonions
===================

INTRO
=====

Words MUST, MAY, SHALL, SHOULD, written in all capitals, should be
interpreted as specified in the RFC 2119 [1].

PROGRAM
=======

Write a Perl program that normalises an octonion.

Program name:
onorm

Program invocation:
onorm octonions*.dat

Input files are optional; if they are not provided, the program MUST
read from STDIN (i.e. it's design must follow the Unix filter
pattern).

OCTONION ALGEBRA
================

Octonion algebra is described in Wikipedia [3] and in algebra
textbooks [4].

Since octonion algebra is non-associative, several options of
multiplication table can be defined for octonions. For implementation,
please use the table in Wikipedia [3] (which should be the same as
provided in [4]).

DATA FORMATS
============

Input data
==========

-- A line staring with the "#@ " sequence MUST be treated as column
   names reporting the units used in the data file; the program MUST
   check the order of units and either reorder the input if it is
   different from the expected or report an fatal error if such
   reordering is not implemented.

-- All other lines that start with a has symbol ("#", ASCII HEX 23)
   MUST be treated as comments and ignored;

-- All empty lines MUST be ignored;

-- All non-empty lines MUST contain an octonion in the "vector octonion
   format" as described in [5];

-- All other lines are to be diagnosed as errors.

Output data
===========

Output MUST proceed to STDOUT.

-- The first line of the output MUST contain the program Id, as
   generated by Subversion keywords (or equivalent subsystems
   generated by other version control systems); the line MUST start
   with the has character ("#") and MAY NOT contain the dollar
   characters ("$", ASCII HEX 24);

-- The second line MUST contain the column names preceded by the '#@'
   sequence and a space; the program MUST be able to read its own
   output, i.e. the octonion units MUST be output in the order that
   the program can process.

-- The remaining lines MUST contain the computed normalised octonions
   corresponding the input octonions in the "vector octonion format"
   [5].

The input and output file *format* example:
===========================================

# Id: onorm 8900 2021-04-10 17:30:02Z saulius
# The first line of the data stream (comment)
# The column headers:
#@ 1 i j k l il jl kl
   1 1 1 1 1 1  1  1
# The last line of the data stream

(the data may not correspond to the program output data).

ERROR HANDLING
==============

All error messages MUST be output to STDERR. If an error is detected,
a suitable non-zero status (exit) code MUST be returned.

The program MUST detect abnormal situation and report them. An
informative user-friendly error reporting should be used. IN
particular, the error message MUST contain: the program name, the
input file name where the error was detected (use '-' without the
quotes as a file name if your input is STDIN), input line number where
the error was detected; quoted example of the erroneous input. The
program MAY output error position in the first character where the
error was detected. The error messages should be informative and
permit user to fix the error.

Perl functions 'die' and 'warn', invoked with and without the "\n"
character at the end of the message are examples of acceptable error
reporting. The native Perl diagnostics (switched on by "use warnings")
and file conditions detected by "while(<>) {...}" construct SHOULD be
used for error reporting.

The program SHOULD attempt to recover from errors and SHOULD continue
its operation as long as possible.

The following conditions MUST be detected and reported:

-- missing, unreadable, unreachable files;

-- system read errors;

-- wrong number of octonion components on the line;

-- wrong input number format.

If the program detects wrong format of at least one input number, the
output result MUST be the "NaN" string (IEEE 754 Not-a-Number) [2];

If the program encounters floating point overflow condition while
processing a matrix, its output on that line MUST be "Inf" (IEEE 754
Infinity) with a relevant sign on the corresponding output line.

REFERENCES
==========

1. S. Bradner "Key words for use in RFCs to Indicate Requirement
   Levels" (1997) URL: https://tools.ietf.org/html/rfc2119 .

2. Wikipedia. IEEE 754 (2022) URL: https://en.wikipedia.org/wiki/IEEE_754
   [accessed 2022-02-08T09:01:44 EET].

3. Wikipedia (2020) Octonion. https://en.wikipedia.org/wiki/Octonion
   [accessed 2020-02-15 19:33:49 EET]

4. H.-B. Ebbinghaus et al. (1995) Numbers. Springer, ISBN
   3-540-97497-0

5. Saulius Gražulis (2020) Hiperkompleksinių skaičių vektorinis formatas.
   https://saulius.grazulis.lt/~saulius/paskaitos/VU/bioinformatika-III/užduotys-praktikai/1-užduotis/formatai/hiperkompleksinių-skaičių-vektorinis-formatas.txt
   [accessed 2020-02-16 12:37:46 EET]