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:
IdentitiesOf< T >

Public Types

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

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. More...
 
virtual ~Identities ()
 Virtual destructor acts as a first non-inline virtual function that determines a specific translation unit in which vtable shall be emitted. More...
 
const Ref ref () const
 A globally unique reference to this set of identities. More...
 
const FieldLoc fieldloc () const
 A list of integer-string pairs indicating the positions of all tuple/record field indicators within the identity tuple. More...
 
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. More...
 
const int64_t width () const
 The number of integers in each identity tuple. More...
 
const int64_t length () const
 The number of identities in the array. More...
 
virtual kernel::lib ptr_lib () const =0
 The Kernel Library that ptr uses. More...
 
virtual const std::string classname () const =0
 User-friendly name of this class: "Identities32" or "Identities64". More...
 
virtual const std::string identity_at (int64_t where) const =0
 Return a string representing an identity tuple at where. More...
 
virtual const IdentitiesPtr to64 () const =0
 Converts this Identities to an Identities64. More...
 
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. More...
 
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. More...
 
virtual void nbytes_part (std::map< size_t, int64_t > &largest) const =0
 Internal function used to calculate Content::nbytes. More...
 
virtual const IdentitiesPtr shallow_copy () const =0
 Copies this Identities node without copying its buffer. More...
 
virtual const IdentitiesPtr deep_copy () const =0
 Copies this Identities node and all the data in its buffer. More...
 
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. More...
 
virtual const IdentitiesPtr withfieldloc (const FieldLoc &fieldloc) const =0
 Returns this Identities node with a different fieldloc. More...
 
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. More...
 
virtual const IdentitiesPtr copy_to (kernel::lib ptr_lib) const =0
 Moves the identity ptr buffer of the array between devices. More...
 
const std::string tostring () const
 Returns a string representation of this array (multi-line XML). More...
 
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. More...
 

Static Public Member Functions

static Ref newref ()
 Returns a new Identities reference that is globally unique in the current process. More...
 
static IdentitiesPtr none ()
 A constant, empty Identities pointer (nullptr). More...
 

Protected Attributes

const Ref ref_
 See ref. More...
 
const FieldLoc fieldloc_
 See fieldloc. More...
 
int64_t offset_
 See offset. More...
 
int64_t width_
 See width. More...
 
int64_t length_
 See length. More...
 

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:

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
refA globally unique reference to this set of identities.
fieldlocA list of integer-string pairs indicating the positions of all tuple/record field indicators within the identity tuple.
offsetLocation 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.
widthThe number of integers in each identity tuple.
lengthThe 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
largestThe 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
otherThe 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
indentIndentation depth as a string of spaces.
prePrefix string, usually an opening XML tag.
postPostfix 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: