API

Implementation of FiniteDPP object which has 6 main methods:

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 the FiniteDPP 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 documentation dppy.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}\).

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.

flush_samples()[source]

Empty the list_of_samples attribute.

info()[source]

Display infos about the FiniteDPP object

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 kernel K, 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 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 using flush_samples()

Caution

The underlying kernel \(\mathbf{K}\), resp. \(\mathbf{L}\) must be real valued for now.

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.

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 using flush_samples()

Caution

The underlying kernel \(\mathbf{K}\), resp. \(\mathbf{L}\) must be real valued for now.

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 for mode='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 the list_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 the list_of_samples attribute as a list of lists.

The list_of_samples attribute can be emptied using flush_samples()

sample_mcmc_k_dpp(size, mode='E', **params)[source]

Calls sample_mcmc() with mode='E' and params['size'] = size