gaussian-splatting-my/envs/gaussian_splatting/Library/share/man/man3/hwlocality_distances_get.3

.TH "hwlocality_distances_get" 3 "Thu Sep 7 2023" "Version 2.9.3" "Hardware Locality (hwloc)" \" -*- nroff -*-
.ad l
.nh
.SH NAME
hwlocality_distances_get \- Retrieve distances between objects
.SH SYNOPSIS
.br
.PP
.SS "Data Structures"

.in +1c
.ti -1c
.RI "struct \fBhwloc_distances_s\fP"
.br
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBhwloc_distances_kind_e\fP { \fBHWLOC_DISTANCES_KIND_FROM_OS\fP, \fBHWLOC_DISTANCES_KIND_FROM_USER\fP, \fBHWLOC_DISTANCES_KIND_MEANS_LATENCY\fP, \fBHWLOC_DISTANCES_KIND_MEANS_BANDWIDTH\fP, \fBHWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES\fP }"
.br
.ti -1c
.RI "enum \fBhwloc_distances_transform_e\fP { \fBHWLOC_DISTANCES_TRANSFORM_REMOVE_NULL\fP, \fBHWLOC_DISTANCES_TRANSFORM_LINKS\fP, \fBHWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS\fP, \fBHWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE\fP }"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "int \fBhwloc_distances_get\fP (\fBhwloc_topology_t\fP topology, unsigned *nr, struct \fBhwloc_distances_s\fP **distances, unsigned long kind, unsigned long flags)"
.br
.ti -1c
.RI "int \fBhwloc_distances_get_by_depth\fP (\fBhwloc_topology_t\fP topology, int depth, unsigned *nr, struct \fBhwloc_distances_s\fP **distances, unsigned long kind, unsigned long flags)"
.br
.ti -1c
.RI "int \fBhwloc_distances_get_by_type\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_obj_type_t\fP type, unsigned *nr, struct \fBhwloc_distances_s\fP **distances, unsigned long kind, unsigned long flags)"
.br
.ti -1c
.RI "int \fBhwloc_distances_get_by_name\fP (\fBhwloc_topology_t\fP topology, const char *name, unsigned *nr, struct \fBhwloc_distances_s\fP **distances, unsigned long flags)"
.br
.ti -1c
.RI "const char * \fBhwloc_distances_get_name\fP (\fBhwloc_topology_t\fP topology, struct \fBhwloc_distances_s\fP *distances)"
.br
.ti -1c
.RI "void \fBhwloc_distances_release\fP (\fBhwloc_topology_t\fP topology, struct \fBhwloc_distances_s\fP *distances)"
.br
.ti -1c
.RI "int \fBhwloc_distances_transform\fP (\fBhwloc_topology_t\fP topology, struct \fBhwloc_distances_s\fP *distances, enum \fBhwloc_distances_transform_e\fP transform, void *transform_attr, unsigned long flags)"
.br
.in -1c
.SH "Detailed Description"
.PP 

.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBhwloc_distances_kind_e\fP"

.PP
Kinds of distance matrices\&. The \fCkind\fP attribute of struct \fBhwloc_distances_s\fP is a OR'ed set of kinds\&.
.PP
A kind of format HWLOC_DISTANCES_KIND_FROM_* specifies where the distance information comes from, if known\&.
.PP
A kind of format HWLOC_DISTANCES_KIND_MEANS_* specifies whether values are latencies or bandwidths, if applicable\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIHWLOC_DISTANCES_KIND_FROM_OS \fP\fP
These distances were obtained from the operating system or hardware\&. 
.TP
\fB\fIHWLOC_DISTANCES_KIND_FROM_USER \fP\fP
These distances were provided by the user\&. 
.TP
\fB\fIHWLOC_DISTANCES_KIND_MEANS_LATENCY \fP\fP
Distance values are similar to latencies between objects\&. Values are smaller for closer objects, hence minimal on the diagonal of the matrix (distance between an object and itself)\&. It could also be the number of network hops between objects, etc\&. 
.TP
\fB\fIHWLOC_DISTANCES_KIND_MEANS_BANDWIDTH \fP\fP
Distance values are similar to bandwidths between objects\&. Values are higher for closer objects, hence maximal on the diagonal of the matrix (distance between an object and itself)\&. Such values are currently ignored for distance-based grouping\&. 
.TP
\fB\fIHWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES \fP\fP
This distances structure covers objects of different types\&. This may apply to the 'NVLinkBandwidth' structure in presence of a NVSwitch or POWER processor NVLink port\&. 
.SS "enum \fBhwloc_distances_transform_e\fP"

.PP
Transformations of distances structures\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIHWLOC_DISTANCES_TRANSFORM_REMOVE_NULL \fP\fP
Remove \fCNULL\fP objects from the distances structure\&. Every object that was replaced with \fCNULL\fP in the \fCobjs\fP array is removed and the \fCvalues\fP array is updated accordingly\&.
.PP
At least \fC2\fP objects must remain, otherwise \fBhwloc_distances_transform()\fP will return \fC-1\fP with \fCerrno\fP set to \fCEINVAL\fP\&.
.PP
\fCkind\fP will be updated with or without \fBHWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES\fP according to the remaining objects\&. 
.TP
\fB\fIHWLOC_DISTANCES_TRANSFORM_LINKS \fP\fP
Replace bandwidth values with a number of links\&. Usually all values will be either \fC0\fP (no link) or \fC1\fP (one link)\&. However some matrices could get larger values if some pairs of peers are connected by different numbers of links\&.
.PP
Values on the diagonal are set to \fC0\fP\&.
.PP
This transformation only applies to bandwidth matrices\&. 
.TP
\fB\fIHWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS \fP\fP
Merge switches with multiple ports into a single object\&. This currently only applies to NVSwitches where GPUs seem connected to different separate switch ports in the NVLinkBandwidth matrix\&. This transformation will replace all of them with the same port connected to all GPUs\&. Other ports are removed by applying \fBHWLOC_DISTANCES_TRANSFORM_REMOVE_NULL\fP internally\&. 
.TP
\fB\fIHWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE \fP\fP
Apply a transitive closure to the matrix to connect objects across switches\&. This currently only applies to GPUs and NVSwitches in the NVLinkBandwidth matrix\&. All pairs of GPUs will be reported as directly connected\&. 
.SH "Function Documentation"
.PP 
.SS "int hwloc_distances_get (\fBhwloc_topology_t\fP topology, unsigned * nr, struct \fBhwloc_distances_s\fP ** distances, unsigned long kind, unsigned long flags)"

.PP
Retrieve distance matrices\&. Retrieve distance matrices from the topology into the \fCdistances\fP array\&.
.PP
\fCflags\fP is currently unused, should be \fC0\fP\&.
.PP
\fCkind\fP serves as a filter\&. If \fC0\fP, all distance matrices are returned\&. If it contains some HWLOC_DISTANCES_KIND_FROM_*, only distance matrices whose kind matches one of these are returned\&. If it contains some HWLOC_DISTANCES_KIND_MEANS_*, only distance matrices whose kind matches one of these are returned\&.
.PP
On input, \fCnr\fP points to the number of distance matrices that may be stored in \fCdistances\fP\&. On output, \fCnr\fP points to the number of distance matrices that were actually found, even if some of them couldn't be stored in \fCdistances\fP\&. Distance matrices that couldn't be stored are ignored, but the function still returns success (\fC0\fP)\&. The caller may find out by comparing the value pointed by \fCnr\fP before and after the function call\&.
.PP
Each distance matrix returned in the \fCdistances\fP array should be released by the caller using \fBhwloc_distances_release()\fP\&.
.PP
\fBReturns\fP
.RS 4
0 on success, -1 on error\&. 
.RE
.PP

.SS "int hwloc_distances_get_by_depth (\fBhwloc_topology_t\fP topology, int depth, unsigned * nr, struct \fBhwloc_distances_s\fP ** distances, unsigned long kind, unsigned long flags)"

.PP
Retrieve distance matrices for object at a specific depth in the topology\&. Identical to \fBhwloc_distances_get()\fP with the additional \fCdepth\fP filter\&.
.PP
\fBReturns\fP
.RS 4
0 on success, -1 on error\&. 
.RE
.PP

.SS "int hwloc_distances_get_by_name (\fBhwloc_topology_t\fP topology, const char * name, unsigned * nr, struct \fBhwloc_distances_s\fP ** distances, unsigned long flags)"

.PP
Retrieve a distance matrix with the given name\&. Usually only one distances structure may match a given name\&.
.PP
The name of the most common structure is 'NUMALatency'\&. Others include 'XGMIBandwidth', 'XGMIHops', 'XeLinkBandwidth', and 'NVLinkBandwidth'\&.
.PP
\fBReturns\fP
.RS 4
0 on success, -1 on error\&. 
.RE
.PP

.SS "int hwloc_distances_get_by_type (\fBhwloc_topology_t\fP topology, \fBhwloc_obj_type_t\fP type, unsigned * nr, struct \fBhwloc_distances_s\fP ** distances, unsigned long kind, unsigned long flags)"

.PP
Retrieve distance matrices for object of a specific type\&. Identical to \fBhwloc_distances_get()\fP with the additional \fCtype\fP filter\&.
.PP
\fBReturns\fP
.RS 4
0 on success, -1 on error\&. 
.RE
.PP

.SS "const char * hwloc_distances_get_name (\fBhwloc_topology_t\fP topology, struct \fBhwloc_distances_s\fP * distances)"

.PP
Get a description of what a distances structure contains\&. For instance 'NUMALatency' for hardware-provided NUMA distances (ACPI SLIT), or \fCNULL\fP if unknown\&.
.PP
\fBReturns\fP
.RS 4
the constant string with the name of the distance structure\&.
.RE
.PP
\fBNote\fP
.RS 4
The returned name should not be freed by the caller, it belongs to the hwloc library\&. 
.RE
.PP

.SS "void hwloc_distances_release (\fBhwloc_topology_t\fP topology, struct \fBhwloc_distances_s\fP * distances)"

.PP
Release a distance matrix structure previously returned by \fBhwloc_distances_get()\fP\&. 
.PP
\fBNote\fP
.RS 4
This function is not required if the structure is removed with \fBhwloc_distances_release_remove()\fP\&. 
.RE
.PP

.SS "int hwloc_distances_transform (\fBhwloc_topology_t\fP topology, struct \fBhwloc_distances_s\fP * distances, enum \fBhwloc_distances_transform_e\fP transform, void * transform_attr, unsigned long flags)"

.PP
Apply a transformation to a distances structure\&. Modify a distances structure that was previously obtained with \fBhwloc_distances_get()\fP or one of its variants\&.
.PP
This modifies the local copy of the distances structures but does not modify the distances information stored inside the topology (retrieved by another call to \fBhwloc_distances_get()\fP or exported to XML)\&. To do so, one should add a new distances structure with same name, kind, objects and values (see \fBAdd distances between objects\fP) and then remove this old one with \fBhwloc_distances_release_remove()\fP\&.
.PP
\fCtransform\fP must be one of the transformations listed in \fBhwloc_distances_transform_e\fP\&.
.PP
These transformations may modify the contents of the \fCobjs\fP or \fCvalues\fP arrays\&.
.PP
\fCtransform_attr\fP must be \fCNULL\fP for now\&.
.PP
\fCflags\fP must be \fC0\fP for now\&.
.PP
\fBReturns\fP
.RS 4
0 on success, -1 on error for instance if flags are invalid\&.
.RE
.PP
\fBNote\fP
.RS 4
Objects in distances array \fCobjs\fP may be directly modified in place without using \fBhwloc_distances_transform()\fP\&. One may use \fBhwloc_get_obj_with_same_locality()\fP to easily convert between similar objects of different types\&. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&.