/*!
 *  Copyright (c) 2020 by Contributors
 * \file dgl/sampling/negative.h
 * \brief Negative sampling.
 */
#ifndef DGL_SAMPLING_NEGATIVE_H_
#define DGL_SAMPLING_NEGATIVE_H_

#include <dgl/base_heterograph.h>
#include <dgl/array.h>
#include <utility>

namespace dgl {
namespace sampling {

/*!
 * \brief Given an edge type, uniformly sample source-destination pairs that do not have
 * an edge in between using rejection sampling.
 *
 * \note This function may not return the same number of elements as the given number
 * of samples.
 * \note This function requires sorting the CSR or CSC matrix of the graph in-place.  It
 * prefers CSC over CSR.
 *
 * \param hg The graph.
 * \param etype The edge type.
 * \param num_samples The number of negative examples to sample.
 * \param num_trials The number of rejection sampling trials.
 * \param exclude_self_loops Do not include the examples where the source equals the
 *        destination.
 * \param replace Whether to sample with replacement.
 * \param redundancy How much redundant negative examples to take in case of duplicate examples.
 * \return The pair of source and destination tensors.
 */
std::pair<IdArray, IdArray> GlobalUniformNegativeSampling(
    HeteroGraphPtr hg,
    dgl_type_t etype,
    int64_t num_samples,
    int num_trials,
    bool exclude_self_loops,
    bool replace,
    double redundancy);

};  // namespace sampling
};  // namespace dgl

#endif  // DGL_SAMPLING_NEGATIVE_H_
