Cluster Gmm | NVIDIA cuVS

Source header: cuvs/cluster/gmm.hpp

Gaussian mixture hyperparameters

cluster::gmm::covariance_type

Covariance parameterization of the mixture components.

1 enum class covariance_type {
2   FULL = 0,
3   TIED = 1,
4   DIAG = 2,
5   SPHERICAL = 3
6 };

Values

Name	Value
`FULL`	`0`
`TIED`	`1`
`DIAG`	`2`
`SPHERICAL`	`3`

cluster::gmm::init_method

Strategy used to initialize the responsibilities before EM.

1 enum class init_method {
2   KMeans = 0,
3   KMeansPlusPlus = 1,
4   Random = 2,
5   RandomFromData = 3
6 };

Values

Name	Value
`KMeans`	`0`
`KMeansPlusPlus`	`1`
`Random`	`2`
`RandomFromData`	`3`

cluster::gmm::params

Hyper-parameters for the Gaussian mixture EM solver.

1 struct params {
2   int n_components;
3   covariance_type cov_type;
4   double tol;
5   double reg_covar;
6   int max_iter;
7   int n_init;
8   init_method init;
9   uint64_t seed;
10 };

Fields

Name	Type	Description
`n_components`	`int`	The number of mixture components (at most 65535). Default: 1.
`cov_type`	`covariance_type`	Covariance parameterization of the mixture components. Default: FULL.
`tol`	`double`	Convergence threshold on the change of the per-sample average log-likelihood (lower bound). Default: 1e-3.
`reg_covar`	`double`	Non-negative regularization added to the diagonal of covariance. Default: 1e-6.
`max_iter`	`int`	Maximum number of EM iterations for a single run. Default: 100.
`n_init`	`int`	Number of initializations to perform; the best result is kept. Default: 1.
`init`	`init_method`	Strategy used to initialize the responsibilities before EM. Default: KMeans.
`seed`	`uint64_t`	Seed to the random number generator. Default: 0.

Gaussian mixture model APIs

cluster::gmm::fit

Fit a Gaussian mixture with the EM algorithm.

1 void fit(raft::resources const& handle,
2 const params& params,
3 raft::device_matrix_view<const float, int64_t> X,
4 raft::device_vector_view<float, int64_t> weights,
5 raft::device_matrix_view<float, int64_t> means,
6 raft::device_vector_view<float, int64_t> covariances,
7 raft::device_vector_view<float, int64_t> precisions_chol,
8 raft::device_vector_view<float, int64_t> precisions,
9 raft::device_vector_view<int, int64_t> labels,
10 raft::host_scalar_view<float> lower_bound,
11 raft::host_scalar_view<int> n_iter,
12 raft::host_scalar_view<bool> converged,
13 bool warm_start = false);

Runs params.n_init random restarts (unless warm_start is true) and keeps the parameters with the largest lower bound. Writes the fitted weights, means, covariances, precisions_chol and precisions, the per-sample hard labels (argmax of the final responsibilities), and the scalar lower_bound / n_iter / converged diagnostics.

When warm_start is true the incoming weights / means / covariances are used as the single initialization and params.n_init is ignored.

Parameters

Name	Direction	Type	Description
`handle`	in	`raft::resources const&`	The raft resources handle.
`params`	in	`const params&`	Hyper-parameters of the EM solver.
`X`	in	`raft::device_matrix_view<const float, int64_t>`	Training data, row-major. [dim = n_samples x n_features]
`weights`	inout	`raft::device_vector_view<float, int64_t>`	Mixture weights. [len = n_components]
`means`	inout	`raft::device_matrix_view<float, int64_t>`	Component means, row-major. [dim = n_components x n_features]
`covariances`	inout	`raft::device_vector_view<float, int64_t>`	Component covariances, flat. Length depends on cov_type (K=n_components, d=n_features): FULL Kdd, TIED dd, DIAG Kd, SPHERICAL K.
`precisions_chol`	out	`raft::device_vector_view<float, int64_t>`	Precision Cholesky factors, same flat layout as covariances. FULL/TIED hold the upper-triangular factor U (precision = U @ Uᵀ); DIAG/SPHERICAL hold reciprocal standard deviations.
`precisions`	out	`raft::device_vector_view<float, int64_t>`	Precision matrices, same flat layout as covariances.
`labels`	out	`raft::device_vector_view<int, int64_t>`	Hard component assignment per sample. [len = n_samples]
`lower_bound`	out	`raft::host_scalar_view<float>`	Per-sample average log-likelihood of the best fit.
`n_iter`	out	`raft::host_scalar_view<int>`	Number of EM iterations of the best fit.
`converged`	out	`raft::host_scalar_view<bool>`	Whether the best fit converged within `params.tol`.
`warm_start`	in	`bool`	Use the incoming weights/means/covariances as the single initialization. Default: `false`.

Returns

void

Additional overload: cluster::gmm::fit

1 void fit(raft::resources const& handle,
2 const params& params,
3 raft::device_matrix_view<const double, int64_t> X,
4 raft::device_vector_view<double, int64_t> weights,
5 raft::device_matrix_view<double, int64_t> means,
6 raft::device_vector_view<double, int64_t> covariances,
7 raft::device_vector_view<double, int64_t> precisions_chol,
8 raft::device_vector_view<double, int64_t> precisions,
9 raft::device_vector_view<int, int64_t> labels,
10 raft::host_scalar_view<double> lower_bound,
11 raft::host_scalar_view<int> n_iter,
12 raft::host_scalar_view<bool> converged,
13 bool warm_start = false);

Parameters

Name	Type	Description
`handle`	`raft::resources const&`
`params`	`const params&`
`X`	`raft::device_matrix_view<const double, int64_t>`
`weights`	`raft::device_vector_view<double, int64_t>`
`means`	`raft::device_matrix_view<double, int64_t>`
`covariances`	`raft::device_vector_view<double, int64_t>`
`precisions_chol`	`raft::device_vector_view<double, int64_t>`
`precisions`	`raft::device_vector_view<double, int64_t>`
`labels`	`raft::device_vector_view<int, int64_t>`
`lower_bound`	`raft::host_scalar_view<double>`
`n_iter`	`raft::host_scalar_view<int>`
`converged`	`raft::host_scalar_view<bool>`
`warm_start`	`bool`	Default: `false`.

Returns

void

cluster::gmm::predict

Hard component labels (argmax responsibility) for new data.

1 void predict(raft::resources const& handle,
2 const params& params,
3 raft::device_matrix_view<const float, int64_t> X,
4 raft::device_vector_view<const float, int64_t> weights,
5 raft::device_matrix_view<const float, int64_t> means,
6 raft::device_vector_view<const float, int64_t> precisions_chol,
7 raft::device_vector_view<int, int64_t> labels);

Parameters

Name	Direction	Type	Description
`handle`	in	`raft::resources const&`	The raft resources handle.
`params`	in	`const params&`	Fit hyper-parameters; only n_components and cov_type are consulted at inference time.
`X`	in	`raft::device_matrix_view<const float, int64_t>`	Data to assign, row-major. [dim = n_samples x n_features]
`weights`	in	`raft::device_vector_view<const float, int64_t>`	Fitted mixture weights. [len = n_components]
`means`	in	`raft::device_matrix_view<const float, int64_t>`	Fitted component means. [dim = n_components x n_features]
`precisions_chol`	in	`raft::device_vector_view<const float, int64_t>`	Fitted precision Cholesky factors, flat. Length by cov_type (K=n_components, d=n_features): FULL Kdd, TIED dd, DIAG Kd, SPHERICAL K.
`labels`	out	`raft::device_vector_view<int, int64_t>`	Hard component assignment per sample. [len = n_samples]

Returns

void

Additional overload: cluster::gmm::predict

1 void predict(raft::resources const& handle,
2 const params& params,
3 raft::device_matrix_view<const double, int64_t> X,
4 raft::device_vector_view<const double, int64_t> weights,
5 raft::device_matrix_view<const double, int64_t> means,
6 raft::device_vector_view<const double, int64_t> precisions_chol,
7 raft::device_vector_view<int, int64_t> labels);

Parameters

Name	Direction	Type	Description
`handle`		`raft::resources const&`
`params`		`const params&`
`X`		`raft::device_matrix_view<const double, int64_t>`
`weights`		`raft::device_vector_view<const double, int64_t>`
`means`		`raft::device_matrix_view<const double, int64_t>`
`precisions_chol`		`raft::device_vector_view<const double, int64_t>`
`labels`		`raft::device_vector_view<int, int64_t>`

Returns

void

cluster::gmm::predict_proba

Posterior responsibilities for new data.

1 void predict_proba(raft::resources const& handle,
2 const params& params,
3 raft::device_matrix_view<const float, int64_t> X,
4 raft::device_vector_view<const float, int64_t> weights,
5 raft::device_matrix_view<const float, int64_t> means,
6 raft::device_vector_view<const float, int64_t> precisions_chol,
7 raft::device_matrix_view<float, int64_t> resp);

Parameters

Name	Direction	Type	Description
`handle`	in	`raft::resources const&`	The raft resources handle.
`params`	in	`const params&`	Fit hyper-parameters; only n_components and cov_type are consulted at inference time.
`X`	in	`raft::device_matrix_view<const float, int64_t>`	Data to evaluate, row-major. [dim = n_samples x n_features]
`weights`	in	`raft::device_vector_view<const float, int64_t>`	Fitted mixture weights. [len = n_components]
`means`	in	`raft::device_matrix_view<const float, int64_t>`	Fitted component means. [dim = n_components x n_features]
`precisions_chol`	in	`raft::device_vector_view<const float, int64_t>`	Fitted precision Cholesky factors, flat. Length by cov_type (K=n_components, d=n_features): FULL Kdd, TIED dd, DIAG Kd, SPHERICAL K.
`resp`	out	`raft::device_matrix_view<float, int64_t>`	Posterior probability of each component for each sample, row-major. [dim = n_samples x n_components]

Returns

void

Additional overload: cluster::gmm::predict_proba

1 void predict_proba(raft::resources const& handle,
2 const params& params,
3 raft::device_matrix_view<const double, int64_t> X,
4 raft::device_vector_view<const double, int64_t> weights,
5 raft::device_matrix_view<const double, int64_t> means,
6 raft::device_vector_view<const double, int64_t> precisions_chol,
7 raft::device_matrix_view<double, int64_t> resp);

Parameters

Name	Direction	Type	Description
`handle`		`raft::resources const&`
`params`		`const params&`
`X`		`raft::device_matrix_view<const double, int64_t>`
`weights`		`raft::device_vector_view<const double, int64_t>`
`means`		`raft::device_matrix_view<const double, int64_t>`
`precisions_chol`		`raft::device_vector_view<const double, int64_t>`
`resp`		`raft::device_matrix_view<double, int64_t>`

Returns

void

cluster::gmm::score_samples

Per-sample log-likelihood log p(x_i) for new data.

1 void score_samples(raft::resources const& handle,
2 const params& params,
3 raft::device_matrix_view<const float, int64_t> X,
4 raft::device_vector_view<const float, int64_t> weights,
5 raft::device_matrix_view<const float, int64_t> means,
6 raft::device_vector_view<const float, int64_t> precisions_chol,
7 raft::device_vector_view<float, int64_t> log_prob_norm);

Parameters

Name	Direction	Type	Description
`handle`	in	`raft::resources const&`	The raft resources handle.
`params`	in	`const params&`	Fit hyper-parameters; only n_components and cov_type are consulted at inference time.
`X`	in	`raft::device_matrix_view<const float, int64_t>`	Data to evaluate, row-major. [dim = n_samples x n_features]
`weights`	in	`raft::device_vector_view<const float, int64_t>`	Fitted mixture weights. [len = n_components]
`means`	in	`raft::device_matrix_view<const float, int64_t>`	Fitted component means. [dim = n_components x n_features]
`precisions_chol`	in	`raft::device_vector_view<const float, int64_t>`	Fitted precision Cholesky factors, flat. Length by cov_type (K=n_components, d=n_features): FULL Kdd, TIED dd, DIAG Kd, SPHERICAL K.
`log_prob_norm`	out	`raft::device_vector_view<float, int64_t>`	Log-likelihood of each sample under the model. [len = n_samples]

Returns

void

Additional overload: cluster::gmm::score_samples

1 void score_samples(raft::resources const& handle,
2 const params& params,
3 raft::device_matrix_view<const double, int64_t> X,
4 raft::device_vector_view<const double, int64_t> weights,
5 raft::device_matrix_view<const double, int64_t> means,
6 raft::device_vector_view<const double, int64_t> precisions_chol,
7 raft::device_vector_view<double, int64_t> log_prob_norm);

Parameters

Name	Direction	Type	Description
`handle`		`raft::resources const&`
`params`		`const params&`
`X`		`raft::device_matrix_view<const double, int64_t>`
`weights`		`raft::device_vector_view<const double, int64_t>`
`means`		`raft::device_matrix_view<const double, int64_t>`
`precisions_chol`		`raft::device_vector_view<const double, int64_t>`
`log_prob_norm`		`raft::device_vector_view<double, int64_t>`

Returns

void