Clusterer¶

template<std::size_t Ndim, std::floating_point TData = float>
class Clusterer¶

The Clusterer class is the interface for running the clustering algorithm. It provides methods to set up the clustering parameters, initializes the internal buffers and runs the clustering algorithm on host or device points.

Template Parameters:¶

std::size_t Ndim¶

The number of dimensions of the points to cluster

Public Types¶

using value_type = std::remove_cv_t<std::remove_reference_t<TData>>¶

Public Functions¶

Clusterer(value_type dc, value_type rhoc, std::optional<value_type> dm = std::nullopt, std::optional<value_type> seed_dc = std::nullopt, int pPBin = 128)¶

Constuct a Clusterer object.

Parameters:¶

value_type dc¶

Distance threshold for clustering.

value_type rhoc¶

Density threshold for clustering

std::optional<value_type> dm = std::nullopt¶

Minimum distance between clusters. This parameter is optional and by default dc is used.

std::optional<value_type> seed_dc = std::nullopt¶

Distance threshold for seed points. This parameter is optional and by default dc is used.

int pPBin = 128¶

Number of points per bin, used to determine the tile size

Clusterer(Queue &queue, value_type dc, value_type rhoc, std::optional<value_type> dm = std::nullopt, std::optional<value_type> seed_dc = std::nullopt, int pPBin = 128)¶

Constuct a Clusterer object.

Parameters:¶

Queue &queue¶

The queue to use for the device operations

value_type dc¶

Distance threshold for clustering.

value_type rhoc¶

Density threshold for clustering

std::optional<value_type> dm = std::nullopt¶

Minimum distance between clusters. This parameter is optional and by default dc is used.

std::optional<value_type> seed_dc = std::nullopt¶

Distance threshold for seed points. This parameter is optional and by default dc is used.

int pPBin = 128¶

Number of points per bin, used to determine the tile size

void setParameters(value_type dc, value_type rhoc, std::optional<value_type> dm = std::nullopt, std::optional<value_type> seed_dc = std::nullopt, int pPBin = 128)¶

Set the parameters for the clustering algorithm.

Parameters:¶

value_type dc¶

Distance threshold for clustering

value_type rhoc¶

Density threshold for clustering

std::optional<value_type> dm = std::nullopt¶

Minimum distance between clusters. This parameter is optional and by default dc is used.

std::optional<value_type> seed_dc = std::nullopt¶

Distance threshold for seed points. This parameter is optional and by default dc is used.

int pPBin = 128¶

Number of points per bin, used to determine the tile size

template<concepts::convolutional_kernel Kernel = FlatKernel<>, concepts::distance_metric<Ndim> DistanceMetric = clue::EuclideanMetric<Ndim, TData>>
void make_clusters(Queue &queue, PointsHost &h_points, const DistanceMetric &metric = clue::EuclideanMetric<Ndim, TData>{}, const Kernel &kernel = FlatKernel<>{.5f}, std::size_t block_size = 256)¶

Construct the clusters from host points.

Template Parameters:¶

concepts::convolutional_kernel Kernel = FlatKernel<>¶

The type of convolutional kernel to use

concepts::distance_metric<Ndim> DistanceMetric = clue::EuclideanMetric<Ndim, TData>¶

The type of distance metric to use

Parameters:¶

Queue &queue¶

The queue to use for the device operations

PointsHost &h_points¶

Host points to cluster

const DistanceMetric &metric = clue::EuclideanMetric<Ndim, TData>{}¶

The distance metric to use for clustering, default is EuclideanMetric

const Kernel &kernel = FlatKernel<>{.5f}¶

The convolutional kernel to use for computing the local densities, default is FlatKernel with height 0.5

std::size_t block_size = 256¶

The size of the blocks to use for clustering, default is 256

template<concepts::convolutional_kernel Kernel = FlatKernel<>, concepts::distance_metric<Ndim> DistanceMetric = clue::EuclideanMetric<Ndim, TData>>
void make_clusters(PointsHost &h_points, const DistanceMetric &metric = clue::EuclideanMetric<Ndim, TData>{}, const Kernel &kernel = FlatKernel<>{.5f}, std::size_t block_size = 256)¶

Construct the clusters from host points.

Note

This method creates a temporary queue for the operations on the device

Template Parameters:¶

concepts::convolutional_kernel Kernel = FlatKernel<>¶

The type of convolutional kernel to use

concepts::distance_metric<Ndim> DistanceMetric = clue::EuclideanMetric<Ndim, TData>¶

The type of distance metric to use

Parameters:¶

PointsHost &h_points¶

Host points to cluster

const DistanceMetric &metric = clue::EuclideanMetric<Ndim, TData>{}¶

The distance metric to use for clustering, default is EuclideanMetric

const Kernel &kernel = FlatKernel<>{.5f}¶

The convolutional kernel to use for computing the local densities, default is FlatKernel with height 0.5

std::size_t block_size = 256¶

The size of the blocks to use for clustering, default is 256

template<concepts::convolutional_kernel Kernel = FlatKernel<>, concepts::distance_metric<Ndim> DistanceMetric = clue::EuclideanMetric<Ndim, TData>>
void make_clusters(Queue &queue, PointsHost &h_points, PointsDevice &dev_points, const DistanceMetric &metric = clue::EuclideanMetric<Ndim, TData>{}, const Kernel &kernel = FlatKernel<>{.5f}, std::size_t block_size = 256)¶

Construct the clusters from host and device points.

Template Parameters:¶

concepts::convolutional_kernel Kernel = FlatKernel<>¶

The type of convolutional kernel to use

concepts::distance_metric<Ndim> DistanceMetric = clue::EuclideanMetric<Ndim, TData>¶

The type of distance metric to use

Parameters:¶

Queue &queue¶

The queue to use for the device operations

PointsHost &h_points¶

Host points to cluster

PointsDevice &dev_points¶

Device points to cluster

const DistanceMetric &metric = clue::EuclideanMetric<Ndim, TData>{}¶

The distance metric to use for clustering, default is EuclideanMetric

const Kernel &kernel = FlatKernel<>{.5f}¶

The convolutional kernel to use for computing the local densities, default is FlatKernel with height 0.5

std::size_t block_size = 256¶

The size of the blocks to use for clustering, default is 256

template<concepts::convolutional_kernel Kernel = FlatKernel<>, concepts::distance_metric<Ndim> DistanceMetric = clue::EuclideanMetric<Ndim, TData>>
void make_clusters(Queue &queue, PointsDevice &dev_points, const DistanceMetric &metric = clue::EuclideanMetric<Ndim, TData>{}, const Kernel &kernel = FlatKernel<>{.5f}, std::size_t block_size = 256)¶

Construct the clusters from device points.

Template Parameters:¶

concepts::convolutional_kernel Kernel = FlatKernel<>¶

The type of convolutional kernel to use

concepts::distance_metric<Ndim> DistanceMetric = clue::EuclideanMetric<Ndim, TData>¶

The type of distance metric to use

Parameters:¶

Queue &queue¶

The queue to use for the device operations

PointsDevice &dev_points¶

Device points to cluster

const DistanceMetric &metric = clue::EuclideanMetric<Ndim, TData>{}¶

The distance metric to use for clustering, default is EuclideanMetric

const Kernel &kernel = FlatKernel<>{.5f}¶

The convolutional kernel to use for computing the local densities, default is FlatKernel with height 0.5

std::size_t block_size = 256¶

The size of the blocks to use for clustering, default is 256

template<concepts::convolutional_kernel Kernel = FlatKernel<>, concepts::distance_metric<Ndim> DistanceMetric = clue::EuclideanMetric<Ndim, TData>>
void make_clusters(Queue &queue, PointsHost &h_points, PointsDevice &dev_points, std::span<const uint32_t> batch_item_sizes, const DistanceMetric &metric = clue::EuclideanMetric<Ndim, TData>{}, const Kernel &kernel = FlatKernel<>{.5f}, std::size_t block_size = 256)¶

Construct the clusters from batched host and device points.

Note

The total size of h_points and dev_points must be equal to the sum of batch_item_sizes

Template Parameters:¶

concepts::convolutional_kernel Kernel = FlatKernel<>¶

The type of convolutional kernel to use

concepts::distance_metric<Ndim> DistanceMetric = clue::EuclideanMetric<Ndim, TData>¶

The type of distance metric to use

Parameters:¶

Queue &queue¶

The queue to use for the device operations

PointsHost &h_points¶

Host points to cluster

PointsDevice &dev_points¶

Device points to cluster

std::span<const uint32_t> batch_item_sizes¶

Sizes of each batch item

const DistanceMetric &metric = clue::EuclideanMetric<Ndim, TData>{}¶

The distance metric to use for clustering, default is EuclideanMetric

const Kernel &kernel = FlatKernel<>{.5f}¶

The convolutional kernel to use for computing the local densities, default is FlatKernel with height 0.5

std::size_t block_size = 256¶

The size of the blocks to use for clustering, default is 256

template<concepts::convolutional_kernel Kernel = FlatKernel<>, concepts::distance_metric<Ndim> DistanceMetric = clue::EuclideanMetric<Ndim, TData>>
void make_clusters(Queue &queue, PointsDevice &dev_points, std::span<const uint32_t> batch_item_sizes, const DistanceMetric &metric = clue::EuclideanMetric<Ndim, TData>{}, const Kernel &kernel = FlatKernel<>{.5f}, std::size_t block_size = 256)¶

Construct the clusters from batched device points.

Note

The total size of h_points and dev_points must be equal to the sum of batch_item_sizes

Template Parameters:¶

concepts::convolutional_kernel Kernel = FlatKernel<>¶

The type of convolutional kernel to use

concepts::distance_metric<Ndim> DistanceMetric = clue::EuclideanMetric<Ndim, TData>¶

The type of distance metric to use

Parameters:¶

Queue &queue¶

The queue to use for the device operations

PointsDevice &dev_points¶

Device points to cluster

std::span<const uint32_t> batch_item_sizes¶

Sizes of each batch item

const DistanceMetric &metric = clue::EuclideanMetric<Ndim, TData>{}¶

The distance metric to use for clustering, default is EuclideanMetric

const Kernel &kernel = FlatKernel<>{.5f}¶

The convolutional kernel to use for computing the local densities, default is FlatKernel with height 0.5

std::size_t block_size = 256¶

The size of the blocks to use for clustering, default is 256

template<std::ranges::contiguous_range TRange>
void setWrappedCoordinates(const TRange &wrapped_coordinates)¶

Specify which coordinates are periodic.

Parameters:¶

wrappedCoordinates

Array of wrapped coordinates, where 1 means periodic and 0 means non-periodic

template<std::integral... TArgs>
void setWrappedCoordinates(TArgs... wrapped_coordinates)¶

Specify which coordinates are periodic.

Template Parameters:¶

std::integral... TArgs¶

Types of the wrapped coordinates, should be convertible to uint8_t

Parameters:¶

wrappedCoordinates

Wrapped coordinates, where 1 means periodic and 0 means non-periodic

host_associator getClusters(const PointsHost &h_points)¶

Get the clusters from the host points.

Parameters:¶

const PointsHost &h_points¶

Host points

Returns:¶

An associator mapping clusters and points

AssociationMap<Device> getClusters(Queue &queue, const PointsDevice &d_points)¶

Get the clusters from the device points This function returns an associator object mapping the clusters to the points they contain.

Parameters:¶

const PointsDevice &d_points¶

Device points

Returns:¶

An associator mapping clusters and points

host_associator getSampleAssociations(Queue &queue, PointsHost &h_points)¶

Get the sample-to-cluster associations for batched clustering.

Parameters:¶

Queue &queue¶

The queue to use for the device operations

Returns:¶

A device buffer containing the event associations

AssociationMap<Device> getSampleAssociations(Queue &queue, PointsDevice &d_points)¶

Get the sample-to-cluster associations for batched clustering.

Parameters:¶

Queue &queue¶

The queue to use for the device operations

Returns:¶

A device buffer containing the event associations