API¶
Implementation of FiniteDPP
object which has 6 main methods:
sample_exact()
, see also sampling DPPs exactlysample_exact_k_dpp()
, see also sampling k-DPPs exactlysample_mcmc()
, see also sampling DPPs with MCMCsample_mcmc_k_dpp()
, see also sampling k-DPPs with MCMCcompute_K()
, to compute the correlation \(K\) kernel from initial parametrizationcompute_L()
, to compute the likelihood \(L\) kernel from initial parametrization
-
class
dppy.finite_dpps.
FiniteDPP
(kernel_type, projection=False, **params)[source]¶ Bases:
object
Finite DPP object parametrized by
- Parameters
kernel_type (string) –
'correlation'
\(\mathbf{K}\) kernel'likelihood'
\(\mathbf{L}\) kernel
projection (bool, default
False
) – Indicate whether the provided kernel is of projection type. This may be useful when theFiniteDPP
object is defined through its correlation kernel \(\mathbf{K}\).params (dict) –
Dictionary containing the parametrization of the underlying
correlation kernel
{'K': K}
, with \(0 \preceq \mathbf{K} \preceq I\){'K_eig_dec': (eig_vals, eig_vecs)}
, with \(0 \leq eigvals \leq 1\){'A_zono': A}
, with \(A (d \times N)\) and \(\operatorname{rank}(A)=d\)
likelihood kernel
{'L': L}
, with \(\mathbf{L}\succeq 0\){'L_eig_dec': (eig_vals, eig_vecs)}
, with \(eigvals \geq 0\){'L_gram_factor': Phi}
, with \(\mathbf{L} = \Phi^{ \top} \Phi\){'L_eval_X_data': (eval_L, X_data)}
, with \(\mathbf{X}_{data}(N \times d)\) and \(eval \_ L\) a likelihood function such that \(\mathbf{L} = eval \_ L(\mathbf{X}_{data}, \{X}_{data})\). For a full description of the requirements imposed on eval_L’s interface, see the documentationdppy.vfx_sampling.vfx_sampling_precompute_constants()
. For an example, see the implementation of any of the kernels provided by scikit-learn (e.g. sklearn.gaussian_process.kernels.PairwiseKernel).
Caution
For now we only consider real valued matrices \(\mathbf{K}, \mathbf{L}, A, \Phi, \mathbf{X}_{data}\).
See also
Todo
add
.kernel_rank
attribute-
compute_K
(msg=False)[source]¶ Compute the correlation kernel \(\mathbf{K}\) from the original parametrization of the
FiniteDPP
object.The kernel is stored in the
K
attribute.
-
compute_L
(msg=False)[source]¶ Compute the likelihood kernel \(\mathbf{L}\) from the original parametrization of the
FiniteDPP
object.The kernel is stored in the
L
attribute.
-
plot_kernel
(kernel_type='correlation', save_path='')[source]¶ Display a heatmap of the kernel used to define the
FiniteDPP
object (correlation kernel \(\mathbf{K}\) or likelihood kernel \(\mathbf{L}\))- Parameters
kernel_type (str) – Type of kernel (
'correlation'
or'likelihood'
), default'correlation'
save_path (str) – Path to save plot, if empty (default) the plot is not saved.
-
sample_exact
(mode='GS', **params)[source]¶ Sample exactly from the corresponding
FiniteDPP
object.- Parameters
mode (string, default
'GS'
) –projection=True
:'GS'
(default): Gram-Schmidt on the rows of \(\mathbf{K}\).'Chol'
[Pou19] Algorithm 3'Schur'
: when DPP defined from correlation kernelK
, use Schur complement to compute conditionals
projection=False
:'GS'
(default): Gram-Schmidt on the rows of the eigenvectors of \(\mathbf{K}\) selected in Phase 1.'GS_bis'
: Slight modification of'GS'
'Chol'
[Pou19] Algorithm 1'KuTa12'
: Algorithm 1 in [KT12]'vfx'
: the dpp-vfx rejection sampler in [DerezinskiCV19]'alpha'
: the alpha-dpp rejection sampler in [CDerezinskiV20]
params (dict) –
Dictionary containing the parameters for exact samplers with keys
'random_state'
(default None)If
mode='vfx'
See
dpp_vfx_sampler()
for a full list of all parameters accepted by ‘vfx’ sampling. We report here the most impactful'rls_oversample_dppvfx'
(default 4.0) Oversampling parameter used to construct dppvfx’s internal Nystrom approximation. This makes each rejection round slower and more memory intensive, but reduces variance and the number of rounds of rejections.'rls_oversample_bless'
(default 4.0) Oversampling parameter used during bless’s internal Nystrom approximation. This makes the one-time pre-processing slower and more memory intensive, but reduces variance and the number of rounds of rejections
Empirically, a small factor [2,10] seems to work for both parameters. It is suggested to start with a small number and increase if the algorithm fails to terminate.
If
mode='alpha'
See
alpha_k_dpp_sampler()
for a full list of all parameters accepted by ‘alpha’ sampling. We report here the most impactful'rls_oversample_alphadpp'
(default 4.0) Oversampling parameter used to construct alpha-dpp’s internal Nystrom approximation. This makes each rejection round slower and more memory intensive, but reduces variance and the number of rounds of rejections.'rls_oversample_bless'
(default 4.0) Oversampling parameter used during bless’s internal Nystrom approximation. This makes the one-time pre-processing slower and more memory intensive, but reduces variance and the number of rounds of rejections
Empirically, a small factor [2,10] seems to work for both parameters. It is suggested to start with a small number and increase if the algorithm fails to terminate.
- Returns
Returns a sample from the corresponding
FiniteDPP
object. In any case, the sample is appended to thelist_of_samples
attribute as a list.- Return type
list
Note
Each time you call this method, the sample is appended to the
list_of_samples
attribute as a list.The
list_of_samples
attribute can be emptied usingflush_samples()
Caution
The underlying kernel \(\mathbf{K}\), resp. \(\mathbf{L}\) must be real valued for now.
See also
-
sample_exact_k_dpp
(size, mode='GS', **params)[source]¶ Sample exactly from \(\operatorname{k-DPP}\). A priori the
FiniteDPP
object was instanciated by its likelihood \(\mathbf{L}\) kernel so that\[\mathbb{P}_{\operatorname{k-DPP}}(\mathcal{X} = S) \propto \det \mathbf{L}_S ~ 1_{|S|=k}\]- Parameters
size (int) – size \(k\) of the \(\operatorname{k-DPP}\)
mode (string, default
'GS'
) –projection=True
:'GS'
(default): Gram-Schmidt on the rows of \(\mathbf{K}\).'Schur'
: Use Schur complement to compute conditionals.
projection=False
:'GS'
(default): Gram-Schmidt on the rows of the eigenvectors of \(\mathbf{K}\) selected in Phase 1.'GS_bis'
: Slight modification of'GS'
'KuTa12'
: Algorithm 1 in [KT12]'vfx'
: the dpp-vfx rejection sampler in [DerezinskiCV19]'alpha'
: the alpha-dpp rejection sampler in [CDerezinskiV20]
params (dict) –
Dictionary containing the parameters for exact samplers with keys
'random_state'
(default None)If
mode='vfx'
See
k_dpp_vfx_sampler()
for a full list of all parameters accepted by ‘vfx’ sampling. We report here the most impactful'rls_oversample_dppvfx'
(default 4.0) Oversampling parameter used to construct dppvfx’s internal Nystrom approximation. This makes each rejection round slower and more memory intensive, but reduces variance and the number of rounds of rejections.'rls_oversample_bless'
(default 4.0) Oversampling parameter used during bless’s internal Nystrom approximation. This makes the one-time pre-processing slower and more memory intensive, but reduces variance and the number of rounds of rejections
Empirically, a small factor [2,10] seems to work for both parameters. It is suggested to start with a small number and increase if the algorithm fails to terminate.
- If
mode='alpha'
See
alpha_k_dpp_sampler()
for a full list of all parameters accepted by ‘alpha’ sampling. We report here the most impactful'rls_oversample_alphadpp'
(default 4.0) Oversampling parameter used to construct alpha-dpp’s internal Nystrom approximation. This makes each rejection round slower and more memory intensive, but reduces variance and the number of rounds of rejections.'rls_oversample_bless'
(default 4.0) Oversampling parameter used during bless’s internal Nystrom approximation. This makes the one-time pre-processing slower and more memory intensive, but reduces variance and the number of rounds of rejections'early_stop'
(default False) Wheter to return as soon as a k-DPP sample is drawn, or to continue with alpha-dpp internal binary search to make subsequent sampling faster.
Empirically, a small factor [2,10] seems to work for both parameters. It is suggested to start with a small number and increase if the algorithm fails to terminate.
- If
- Returns
A sample from the corresponding \(\operatorname{k-DPP}\).
In any case, the sample is appended to the
list_of_samples
attribute as a list.- Return type
list
Note
Each time you call this method, the sample is appended to the
list_of_samples
attribute as a list.The
list_of_samples
attribute can be emptied usingflush_samples()
Caution
The underlying kernel \(\mathbf{K}\), resp. \(\mathbf{L}\) must be real valued for now.
See also
-
sample_mcmc
(mode, **params)[source]¶ Run a MCMC with stationary distribution the corresponding
FiniteDPP
object.- Parameters
mode (string) –
'AED'
Add-Exchange-Delete'AD'
Add-Delete'E'
Exchange'zonotope'
Zonotope sampling
params (dict) –
Dictionary containing the parameters for MCMC samplers with keys
'random_state'
(default None)If
mode='AED','AD','E'
's_init'
(default None) Starting state of the Markov chain'nb_iter'
(default 10) Number of iterations of the chain'T_max'
(default None) Time horizon'size'
(default None) Size of the initial sample formode='AD'/'E'
\(\operatorname{rank}(\mathbf{K})=\operatorname{trace}(\mathbf{K})\) for projection \(\mathbf{K}\) (correlation) kernel and
mode='E'
If
mode='zonotope'
:'lin_obj'
linear objective in main optimization problem (default np.random.randn(N))'x_0'
initial point in zonotope (default A*u, u~U[0,1]^n)'nb_iter'
(default 10) Number of iterations of the chain'T_max'
(default None) Time horizon
- Returns
The last sample of the trajectory of Markov chain.
In any case, the full trajectory of the Markov chain, made of
params['nb_iter']
samples, is appended to thelist_of_samples
attribute as a list of lists.- Return type
list
Note
Each time you call this method, the full trajectory of the Markov chain, made of
params['nb_iter']
samples, is appended to thelist_of_samples
attribute as a list of lists.The
list_of_samples
attribute can be emptied usingflush_samples()
See also
-
sample_mcmc_k_dpp
(size, mode='E', **params)[source]¶ Calls
sample_mcmc()
withmode='E'
andparams['size'] = size