Skip to content

PR: Add finfo and iinfo in the spec #129

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Feb 21, 2021
Merged

PR: Add finfo and iinfo in the spec #129

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8c414d6
add finfo and iinfo in the spec
steff456 Feb 17, 2021
39a9cb2
move result_type function to new file and minor fixes
steff456 Feb 17, 2021
79dc82c
add review changes and remove tiny from the finfo object
steff456 Feb 18, 2021
2cc6683
Make finfo/info argument positional-only
rgommers Feb 21, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 63 additions & 0 deletions spec/API_specification/data_type_functions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# Data type functions

> Array API specification for data type functions.

A conforming implementation of the array API standard must provide and support the following data type functions.

<!-- NOTE: please keep the constants in alphabetical order -->

## Objects in API

(finfo)=
### finfo(type)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

type should be a positional argument here, so this should be finfo(type, /).

And same for iinfo.


Defines the machine limits for floating point types.

#### Parameters

- **type**: _Union\[ float, &lt;dtype&gt, instance ]_

- the kind of floating point data-type about which to get information

#### Returns

- **out**: _&lt;class&gt;_

- a class with that encapsules the following attributes:

- **bits**: _int_
- The number of bits occupied by the type
- **eps**: _float_
- The difference between 1.0 and the next smallest representable float larger than 1.0 following the IEEE 754 standard.
- **max**: _float_
- The largest representable number.
- **min**: _float_
- The smallest representable number.
- **tiny**: _float_
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kgryte do you happen to know if this is guaranteed to be the same across implementations? I.e. it's part of IEEE 754 somehow?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is what the NumPy docs have in their notes:

Note that tiny is not actually the smallest positive representable value in a NumPy floating point type. As in the IEEE-754 standard [1], NumPy floating point types make use of subnormal numbers to fill the gap between 0 and tiny. However, subnormal numbers may have significantly reduced precision [2].

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No. While part of IEEE 754, support for subnormal numbers is less common, especially among older generation GPUs. Often subnormal numbers trigger slow paths, and, if not implemented in hardware, software emulation. More recent NVIDIA GPUs do support subnormal numbers. And among ARM processors, one can flush subnormal numbers to zero.

Based on NumPy docs (via @steff456 ), tiny refers to the smallest normal number. We should probably be explicit by what we mean by "representable number".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interesting. So the description is a bit off here. I'm not sure it should be part of the standard. I can imagine it may be useful in a few corner cases, but I've never seen it used in the wild.

Let's see if anyone else has an opinion.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, so there are use cases at the compiled code level at least.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose having this info is useful for meta inspection concerning platform capabilities. For example, if I want to know whether a platform supports subnormals. Apart from meta data, a user would need to compute a quantity which should resolve to a subnormal number and manually check whether the value is zero.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct. It can also come up in user code, e.g., in the computation of transcendentals, where, if you know that a platform does not support subnormals, then you can avoid various, often slower, branching logic.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think if we wanted to be complete, instead of "tiny", we'd have smallest_normal and smallest_subnormal. If the latter is 0, then a platform does not support subnormal numbers.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Those do seem like better names indeed. TF and CuPy just alias numpy.finfo, which may be wrong. And JAX implements it but docs say "The smallest positive usable number", which is quite uninformative.

I think we can add the new names, but then we should make a PR to NumPy to see if that's accepted. And otherwise we should probably drop it completely.

- The smallest positive representable number.
- **resolution**: _float_
- The approximate decimal resolution of this type.

(iinfo)=
### iinfo(type)

Defines the machine limits for integer types.

#### Parameters

- **type**: _Union\[ integer, &lt;dtype&gt, instance ]_

- the kind of integer data-type about which to get information

#### Returns

- **out**: _&lt;class&gt;_

- a class with that encapsules the following attributes:

- **bits**: _int_
- The number of bits occupied by the type
- **max**: _int_
- The largest representable number.
- **min**: _int_
- The smallest representable number.
1 change: 1 addition & 0 deletions spec/API_specification/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ API specification
array_object
indexing
data_types
data_type_functions
type_promotion
broadcasting
creation_functions
Expand Down