Awkward Array: Identities Class Reference

Loading...
Searching...
No Matches
Public Types | Public Member Functions | Static Public Member Functions | Protected Attributes | List of all members
Identities Class Referenceabstract

A contiguous, two-dimensional array of integers and a list of strings used to represent a path from the root of an array structure to each item in an array. More...

`#include <Identities.h>`

Inheritance diagram for Identities:

## Public Types
using | Ref = int64_t
| Identities reference type (64-bit integer).
using | FieldLoc = std::vector< std::pair< int64_t, std::string > >
| Identities field location type (integer-string pairs).

## Public Member Functions
| Identities (const Ref ref, const FieldLoc &fieldloc, int64_t offset, int64_t width, int64_t length)
| Called by all subclass constructors; assigns ref, fieldloc, offset, width, and length upon construction.
virtual | ~Identities ()
| Virtual destructor acts as a first non-inline virtual function that determines a specific translation unit in which vtable shall be emitted.
const Ref | ref () const
| A globally unique reference to this set of identities.
const FieldLoc | fieldloc () const
| A list of integer-string pairs indicating the positions of all tuple/record field indicators within the identity tuple.
const int64_t | offset () const
| Location of item zero in the buffer, relative to `ptr`, measured in the number of elements. We keep this information in two parameters (`ptr` and `offset`) rather than moving `ptr` so that `ptr` can be reference counted among all arrays that use the same buffer.
const int64_t | width () const
| The number of integers in each identity tuple.
const int64_t | length () const
| The number of identities in the array.
virtual kernel::lib | ptr_lib () const =0
| The Kernel Library that ptr uses.
virtual const std::string | classname () const =0
| User-friendly name of this class: `"Identities32"` or `"Identities64"`.
virtual const std::string | identity_at (int64_t where) const =0
| Return a string representing an identity tuple at `where`.
virtual const IdentitiesPtr | to64 () const =0
| Converts this Identities to an `Identities64`.
virtual const std::string | tostring_part (const std::string &indent, const std::string &pre, const std::string &post) const =0
| Internal function to build an output string for tostring.
virtual const IdentitiesPtr | getitem_range_nowrap (int64_t start, int64_t stop) const =0
| Subinterval of this array, without handling negative indexing or bounds-checking.
virtual void | nbytes_part (std::map< size_t, int64_t > &largest) const =0
| Internal function used to calculate Content::nbytes.
virtual const IdentitiesPtr | shallow_copy () const =0
| Copies this Identities node without copying its buffer.
virtual const IdentitiesPtr | deep_copy () const =0
| Copies this Identities node and all the data in its buffer.
virtual const IdentitiesPtr | getitem_carry_64 (const Index64 &carry) const =0
| Returns an Identities array with elements filtered, rearranged, and possibly duplicated by the `carry` array of integers.
virtual const IdentitiesPtr | withfieldloc (const FieldLoc &fieldloc) const =0
| Returns this Identities node with a different fieldloc.
virtual int64_t | value (int64_t row, int64_t col) const =0
| Returns the integer value of the two-dimensional array at `row` and `col`.
virtual const IdentitiesPtr | copy_to (kernel::lib ptr_lib) const =0
| Moves the identity ptr buffer of the array between devices.
const std::string | tostring () const
| Returns a string representation of this array (multi-line XML).
virtual bool | referentially_equal (const IdentitiesPtr &other) const =0
| Returns `true` if this Identities has all the same buffers and parameters as `other`; `false` otherwise.

## Static Public Member Functions
static Ref | newref ()
| Returns a new Identities reference that is globally unique in the current process.
static IdentitiesPtr | none ()
| A constant, empty Identities pointer (`nullptr`).

## Protected Attributes
const Ref | ref_
| See ref.
const FieldLoc | fieldloc_
| See fieldloc.
int64_t | offset_
| See offset.
int64_t | width_
| See width.
int64_t | length_
| See length.

## Detailed Description

A contiguous, two-dimensional array of integers and a list of strings used to represent a path from the root of an array structure to each item in an array.

A single value's identity is equivalent to a tuple of integers and strings:

(999, "muons", 1, "pt")

which corresponds to the "getitem" path from the root of the array to that value:

array[999, "muons", 1, "pt"]

The fieldloc is a set of integer-string pairs, such as

[(1, "muons"), (3, "pt")]

in the above example. The identities array is two-dimensional so that a single value can be an array, such as

[999, 1]

in the above example.

The Identities superclass abstracts over templated specializations:

- `Identities32`, which is `IdentitiesOf<int32_t>`
- `Identities64`, which is `IdentitiesOf<int64_t>`

## Member Typedef Documentation

## ◆ FieldLoc

using FieldLoc = std::vector<std::pair<int64_t, std::string> >

Identities field location type (integer-string pairs).

## ◆ Ref

using Ref = int64_t

Identities reference type (64-bit integer).

## Constructor & Destructor Documentation

## ◆ Identities()

Identities | ( | const Ref | ref,
|  | const FieldLoc & | fieldloc,
|  | int64_t | offset,
|  | int64_t | width,
|  | int64_t | length
| ) |  |

Called by all subclass constructors; assigns ref, fieldloc, offset, width, and length upon construction.

Parameters

  ref | A globally unique reference to this set of identities.
  fieldloc | A list of integer-string pairs indicating the positions of all tuple/record field indicators within the identity tuple.
  offset | Location of item zero in the buffer, relative to `ptr`, measured in the number of elements. We keep this information in two parameters (`ptr` and `offset`) rather than moving `ptr` so that `ptr` can be reference counted among all arrays that use the same buffer.
  width | The number of integers in each identity tuple.
  length | The number of identities in the array.

## ◆ ~Identities()

virtual ~Identities | ( |  | ) |
| virtual

Virtual destructor acts as a first non-inline virtual function that determines a specific translation unit in which vtable shall be emitted.

## Member Function Documentation

## ◆ classname()

virtual const std::string classname | ( |  | ) | const
| pure virtual

User-friendly name of this class: `"Identities32"` or `"Identities64"`.

Implemented in IdentitiesOf< T >.

## ◆ copy_to()

virtual const IdentitiesPtr copy_to | ( | kernel::lib | ptr_lib | ) | const
| pure virtual

Moves the identity ptr buffer of the array between devices.

Returns a std::shared_ptr<IdentitiesOf> which is, by default, allocated on the first device(device [0])

Note
  This function has not been implemented to handle Multi-GPU setups

Implemented in IdentitiesOf< T >.

## ◆ deep_copy()

virtual const IdentitiesPtr deep_copy | ( |  | ) | const
| pure virtual

Copies this Identities node and all the data in its buffer.

See also shallow_copy.

Implemented in IdentitiesOf< T >.

## ◆ fieldloc()

const FieldLoc fieldloc | ( |  | ) | const

A list of integer-string pairs indicating the positions of all tuple/record field indicators within the identity tuple.

## ◆ getitem_carry_64()

virtual const IdentitiesPtr getitem_carry_64 | ( | const Index64 & | carry | ) | const
| pure virtual

Returns an Identities array with elements filtered, rearranged, and possibly duplicated by the `carry` array of integers.

The output has the same length as the `carry` index, not the `array` that is being manipulated. For each item `i` in `carry`, the output is `array[index[i]]`.

This operation is called take in NumPy and Arrow, although this carry is a low-level function that does not handle negative indexes and is not exposed to the Python layer. It is used by many operations to pass filters/rearrangements/duplications from one typed array node to another without knowing the latter's type.

Taking `getitem_at_nowrap` as a function from integers to the array's item type, `A: [0, len(a)) → T`, and the `carry` array's `Index64::getitem_at_nowrap` as a function `C: [0, len(c)) → [0, len(a))`, this method represents function composition, `A ∘ C: [0, len(c)) → T`.

Implemented in IdentitiesOf< T >.

## ◆ getitem_range_nowrap()

virtual const IdentitiesPtr getitem_range_nowrap | ( | int64_t | start,
|  | int64_t | stop
| ) |  | const
| pure virtual

Subinterval of this array, without handling negative indexing or bounds-checking.

This operation only affects the node metadata; its calculation time does not scale with the size of the array.

Implemented in IdentitiesOf< T >.

## ◆ identity_at()

virtual const std::string identity_at | ( | int64_t | where | ) | const
| pure virtual

Return a string representing an identity tuple at `where`.

Implemented in IdentitiesOf< T >.

## ◆ length()

const int64_t length | ( |  | ) | const

The number of identities in the array.

## ◆ nbytes_part()

virtual void nbytes_part | ( | std::map< size_t, int64_t > & | largest | ) | const
| pure virtual

Internal function used to calculate Content::nbytes.

Parameters

  largest | The largest range of bytes used in each reference-counted pointer (`size_t`).

Note
  This method of accounting for overlapping buffers is insufficient: two nodes could use parts of the same buffer in which one doesn't completely overlap the other. It's not likely, but currently the calculation of Content::nbytes is an underestimate.

Implemented in IdentitiesOf< T >.

## ◆ newref()

static Ref newref | ( |  | ) |
| static

Returns a new Identities reference that is globally unique in the current process.

This is thread-safe: the global counter is an atomic integer.

## ◆ none()

static IdentitiesPtr none | ( |  | ) |
| static

A constant, empty Identities pointer (`nullptr`).

## ◆ offset()

const int64_t offset | ( |  | ) | const

Location of item zero in the buffer, relative to `ptr`, measured in the number of elements. We keep this information in two parameters (`ptr` and `offset`) rather than moving `ptr` so that `ptr` can be reference counted among all arrays that use the same buffer.

## ◆ ptr_lib()

virtual kernel::lib ptr_lib | ( |  | ) | const
| pure virtual

The Kernel Library that ptr uses.

Implemented in IdentitiesOf< T >.

## ◆ ref()

const Ref ref | ( |  | ) | const

A globally unique reference to this set of identities.

## ◆ referentially_equal()

virtual bool referentially_equal | ( | const IdentitiesPtr & | other | ) | const
| pure virtual

Returns `true` if this Identities has all the same buffers and parameters as `other`; `false` otherwise.

Parameters

  other | The Identities to compare this with.

Implemented in IdentitiesOf< T >.

## ◆ shallow_copy()

virtual const IdentitiesPtr shallow_copy | ( |  | ) | const
| pure virtual

Copies this Identities node without copying its buffer.

See also deep_copy.

Implemented in IdentitiesOf< T >.

## ◆ to64()

virtual const IdentitiesPtr to64 | ( |  | ) | const
| pure virtual

Converts this Identities to an `Identities64`.

Implemented in IdentitiesOf< T >.

## ◆ tostring()

const std::string tostring | ( |  | ) | const

Returns a string representation of this array (multi-line XML).

## ◆ tostring_part()

virtual const std::string tostring_part | ( | const std::string & | indent,
|  | const std::string & | pre,
|  | const std::string & | post
| ) |  | const
| pure virtual

Internal function to build an output string for tostring.

Parameters

  indent | Indentation depth as a string of spaces.
  pre | Prefix string, usually an opening XML tag.
  post | Postfix string, usually a closing XML tag and carriage return.

Implemented in IdentitiesOf< T >.

## ◆ value()

virtual int64_t value | ( | int64_t | row,
|  | int64_t | col
| ) |  | const
| pure virtual

Returns the integer value of the two-dimensional array at `row` and `col`.

Implemented in IdentitiesOf< T >.

## ◆ width()

const int64_t width | ( |  | ) | const

The number of integers in each identity tuple.

## ◆ withfieldloc()

virtual const IdentitiesPtr withfieldloc | ( | const FieldLoc & | fieldloc | ) | const
| pure virtual

Returns this Identities node with a different fieldloc.

Implemented in IdentitiesOf< T >.

## Member Data Documentation

## ◆ fieldloc_

const FieldLoc fieldloc_
| protected

See fieldloc.

## ◆ length_

int64_t length_
| protected

See length.

## ◆ offset_

int64_t offset_
| protected

See offset.

## ◆ ref_

const Ref ref_
| protected

See ref.

## ◆ width_

int64_t width_
| protected

See width.

The documentation for this class was generated from the following file:

- include/awkward/Identities.h