@petamoriken/float16

What is @petamoriken/float16?

@petamoriken/float16 is an npm package that provides utilities for handling 16-bit floating-point numbers (half-precision). It allows for conversion between 16-bit floats and other numeric types, as well as arithmetic operations on 16-bit floats.

What are @petamoriken/float16's main functionalities?

Conversion from 32-bit float to 16-bit float

This feature allows you to convert a 32-bit floating-point number to a 16-bit floating-point number. The code sample demonstrates converting the 32-bit float value 1.5 to its 16-bit float representation.

const { float32ToFloat16 } = require('@petamoriken/float16');
const float32 = 1.5;
const float16 = float32ToFloat16(float32);
console.log(float16); // Output: 15360

Conversion from 16-bit float to 32-bit float

This feature allows you to convert a 16-bit floating-point number back to a 32-bit floating-point number. The code sample demonstrates converting the 16-bit float value 15360 back to its 32-bit float representation.

const { float16ToFloat32 } = require('@petamoriken/float16');
const float16 = 15360;
const float32 = float16ToFloat32(float16);
console.log(float32); // Output: 1.5

Arithmetic operations on 16-bit floats

This feature provides basic arithmetic operations (addition, subtraction, multiplication, and division) on 16-bit floating-point numbers. The code sample demonstrates these operations using two 16-bit float values representing 1.5.

const { addFloat16, subFloat16, mulFloat16, divFloat16 } = require('@petamoriken/float16');
const a = 15360; // 1.5 in 16-bit float
const b = 15360; // 1.5 in 16-bit float
console.log(addFloat16(a, b)); // Output: 16384 (3.0 in 16-bit float)
console.log(subFloat16(a, b)); // Output: 0 (0.0 in 16-bit float)
console.log(mulFloat16(a, b)); // Output: 15872 (2.25 in 16-bit float)
console.log(divFloat16(a, b)); // Output: 15360 (1.0 in 16-bit float)

Other packages similar to @petamoriken/float16

float16

The 'float16' package provides similar functionality for handling 16-bit floating-point numbers. It includes methods for converting between 16-bit and 32-bit floats, as well as arithmetic operations. However, it may have a different API and performance characteristics compared to @petamoriken/float16.

README

@petamoriken/float16

half precision floating point for JavaScript
See ES Discuss Float16Array topic

Install

yarn add @petamoriken/float16

npm install @petamoriken/float16

Import

Node.js or Bundler (webpack, rollup.js, esbuild, etc)

// ES Modules
import { Float16Array, isFloat16Array, getFloat16, setFloat16, hfround } from "@petamoriken/float16";

// CommonJS
const { Float16Array, isFloat16Array, getFloat16, setFloat16, hfround } = require("@petamoriken/float16");

Browser

Deliver a browser/float16.mjs or browser/float16.js file from your Web server with the JavaScript Content-Type HTTP header.

<!-- Module Scripts -->
<script type="module">
    import { Float16Array, isFloat16Array, getFloat16, setFloat16, hfround } from "DEST/TO/float16.mjs";
</script>

<!-- Classic Scripts -->
<script src="DEST/TO/float16.js"></script>
<script>
    const { Float16Array, isFloat16Array, getFloat16, setFloat16, hfround } = float16;
</script>

Or use jsDelivr CDN.

<!-- Module Scripts -->
<script type="module">
    import { Float16Array, isFloat16Array, getFloat16, setFloat16, hfround } from "https://cdn.jsdelivr.net/npm/@petamoriken/float16/+esm";
</script>

<!-- Classic Scripts -->
<script src="https://cdn.jsdelivr.net/npm/@petamoriken/float16/browser/float16.min.js"></script>
<script>
    const { Float16Array, isFloat16Array, getFloat16, setFloat16, hfround } = float16;
</script>

ES modules are also available on the Skypack CDN.

<!-- Module Scripts -->
<script type="module">
    import { Float16Array, isFloat16Array, getFloat16, setFloat16, hfround } from "https://cdn.skypack.dev/@petamoriken/float16?min";
</script>

Deno

You can get modules from deno.land/x hosting service.

import { Float16Array, isFloat16Array, getFloat16, setFloat16, hfround } from "https://deno.land/x/float16/index.mjs";

Support

This package's Float16Array uses Proxy object, so IE11 is never supported.

lib/ and browser/ directories in the npm package have JavaScript files already built, whose target are

• Firefox: last 2 versions and ESR
• Chrome: last 2 versions
• Edge: last 2 versions
• Safari: last 2 versions

However, this package only uses up to the ES2015 features, so you should be able to use it without any problems.

If you build it yourself using bundler to support older browsers, transpile the JavaScript files in the src/ directory.

API

Float16Array

Float16Array is similar to TypedArray such as Float32Array (MDN).

const array = new Float16Array([1.0, 1.1, 1.2]);
for (const val of array) {
    console.log(val); // => 1, 1.099609375, 1.19921875
}

array.reduce((prev, current) => prev + current); // 3.298828125

isFloat16Array

isFloat16Array is a utility function to check whether the value given as an argument is an instance of Float16Array or not.

declare function isFloat16Array(value: unknown): value is Float16Array;

isFloat16Array(new Float16Array(10)); // true
isFloat16Array(new Float32Array(10)); // false
isFloat16Array(new Uint16Array(10)); // false

DataView

getFloat16 and setFloat16 are similar to DataView methods such as DataView#getFloat32 (MDN) and DataView#setFloat32 (MDN).

declare function getFloat16(view: DataView, byteOffset: number, littleEndian?: boolean): number;
declare function setFloat16(view: DataView, byteOffset: number, value: number, littleEndian?: boolean): void;

const buffer = new ArrayBuffer(10);
const view = new DataView(buffer);

view.setUint16(0, 0x1234);
getFloat16(view, 0); // 0.0007572174072265625

// You can append methods to DataView instance
view.getFloat16 = (...args) => getFloat16(view, ...args);
view.setFloat16 = (...args) => setFloat16(view, ...args);

view.getFloat16(0); // 0.0007572174072265625

view.setFloat16(0, Math.PI, true);
view.getFloat16(0, true); // 3.140625

hfround

hfround is similar to Math.fround (MDN). This function returns nearest half precision float representation of a number.

declare function hfround(x: number): number;

Math.fround(1.337); // 1.3370000123977661
hfround(1.337); // 1.3369140625

Float16Array limitations (edge cases)

The instanceof Operator

Since Float16Array is made by inheriting from Uint16Array, so you can't use the instanceof operator to check if it is a Uint16Array or not.

new Uint16Array(10) instanceof Uint16Array; // true
new Float16Array(10) instanceof Uint16Array; // true

Actually, I could use Proxy's getPrototypeOf handler to trap it, but that would be too complex and have some limitations.

In addition, it is a bad idea to use instanceof to detect the type of TypedArray, because it can't be used to detect the type of objects from other Realms, such as iframe and vm. It is recommended to use Object#toString or @@toStringTag for this purpose.

function isUint16Array(target) {
    if (target === null || typeof target !== "object") {
        return false;
    }
    return Object.prototype.toString.call(target) === "[object Uint16Array]";
}

For Node.js, you can use util.types (document) instead. Want to do a more solid TypedArray check for other environments? Then you can use this code 😉

Built-in Functions

Built-in TypedArray objects use "internal slots" for built-in methods. Some limitations exist because the Proxy object can't trap internal slots (explanation).

This package isn't polyfill, in other words, it doesn't change native global functions and static/prototype methods.

E.g. ArrayBuffer.isView is the butlt-in method that checks if it has the [[ViewedArrayBuffer]] internal slot. It returns false for Proxy object such as Float16Array instance.

ArrayBuffer.isView(new Float32Array(10)); // true
ArrayBuffer.isView(new Float16Array(10)); // false

The structured clone algorithm (Web Workers, IndexedDB, etc)

The structured clone algorithm copies complex JavaScript objects. It is used internally when invoking structuredClone(), to transfer data between Web Workers via postMessage(), storing objects with IndexedDB, or copying objects for other APIs (MDN).

It can't clone Proxy object such as Float16Array instance, you need to convert it to Uint16Array or deal with ArrayBuffer directly.

const array = new Float16Array([1.0, 1.1, 1.2]);
const cloned = structuredClone({ buffer: array.buffer });

WebGL

WebGL requires Uint16Array for buffer or texture data whose types are gl.HALF_FLOAT (WebGL 2) or ext.HALF_FLOAT_OES (WebGL 1 extension). Do not apply the Float16Array object directly to gl.bufferData or gl.texImage2D etc.

// WebGL 2 example
const vertices = new Float16Array([
    -0.5, -0.5,  0,
     0.5, -0.5,  0,
     0.5,  0.5,  0,
]);

const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);

// wrap in Uint16Array
gl.bufferData(gl.ARRAY_BUFFER, new Uint16Array(vertices.buffer), gl.STATIC_DRAW);
gl.vertexAttribPointer(location, 3, gl.HALF_FLOAT, false, 0, 0);

gl.bindBuffer(gl.ARRAY_BUFFER, null);
gl.enableVertexAttribArray(location);

Others

See JSDoc comments in src/Float16Array.mjs for details. If you don't write hacky code, you shouldn't have any problems.

Build

First, download devDependencies.

yarn

Build lib/, browser/ files.

yarn run build

Build docs/ files (for browser test).

yarn run docs

Test

First, download devDependencies.

yarn

Node.js Test

yarn build:lib
yarn test

Browser Test

yarn build:browser
yarn docs

Access docs/test/index.html with browsers.

You can access current test page (power-assert version) in master branch.