% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/generate.R
\name{generate_ndset}
\alias{generate_ndset}
\title{Generate a random set of mutually nondominated points}
\usage{
generate_ndset(n, d, method, seed = NULL, integer = FALSE)
}
\arguments{
\item{n}{\code{integer(1)}\cr Number of rows in the output.}

\item{d}{\code{integer(1)}\cr Number of columns in the output.}

\item{method}{\code{character(1)}\cr Method used to generate the random nondominated set.
See \strong{Details} below for more information.}

\item{seed}{\code{integer(1)}\cr Integer seed for random number generation. If \code{NULL},
a random seed is generated.}

\item{integer}{\code{logical(1)}\cr If \code{TRUE}, return integer-valued points.}
}
\value{
A numeric matrix of size \verb{n × d} containing nondominated points.
}
\description{
Generate a random set of \code{n} mutually nondominated points of dimension \code{d}
with the shape defined by \code{method}.

When \code{integer = FALSE} (the default), the points are generated within the
hypercube \eqn{(0,1)^d} and can be scaled to another range using
\code{\link[=normalise]{normalise()}}.  Otherwise, points are scaled to a non-negative integer range
that keeps the points mutually nondominated.

See the visualisations in the vignette \HTMLVignette{generate}{Sampling Random Nondominated Sets}.
}
\details{
The available methods are:

\describe{
\item{\code{'simplex'}, \code{'linear'}, or \code{'L'}}{

Uniformly samples points on the standard simplex.  This shape of
nondominated set is also called \code{'linear'} in the literature
\citep{LacKlaFon2017box}.

The standard \eqn{(d-1)}-simplex is defined by \eqn{\{x \in \mathbb{R}_+^d :
   \sum_i x_i = 1\}}.  Each point \eqn{\vec{z} \in (0,1)^d \subset
   \mathbb{R}^d} is generated by sampling \eqn{d} independent and
identically distributed values \eqn{(x_1,x_2, \dots, x_d)} from the
exponential distribution, then dividing each value by the L1-norm of the
vector, \eqn{z_i = x_i / \sum_{i=1}^d x_i} \citep{RubMel1998simulation}.
Values sampled from the exponential distribution are guaranteed to be
positive.  Sampling from either the standard normal distribution
\citep{GueFonPaq2021hv} or the uniform distribution
\citep{LacKlaFon2017box} does not produce a uniform distribution when
projected onto the simplex.

}
\item{\code{'concave-sphere'}, \code{'sphere'}, or \code{'C'}}{

Uniformly samples points on the positive orthant of the hyper-sphere,
which is concave when all objectives are minimised.

Each point \eqn{\vec{z} \in (0,1)^d \subset \mathbb{R}^d} is generated by
sampling \eqn{d} independent and identically distributed values
\eqn{\vec{x}=(x_1,x_2, \dots, x_d)} from the standard normal
distribution, then dividing each value by the l2-norm of the vector,
\eqn{z_i = \frac{|x_i|}{\|\vec{x}\|_2}} \citep{Muller1959sphere}. The
absolute value in the numerator ensures that points are sampled on the
positive orthant of the hyper-sphere.  Sampling from the uniform
distribution \citep{LacKlaFon2017box} would not result in a uniform
sampling when projected onto the surface of the hyper-sphere.

}
\item{\code{'convex-sphere'} or \code{'X'}}{

Equivalent to \code{1 - generate_ndset(..., method='concave-sphere')}, which
is convex for minimisation.  This shape has also been called \emph{inverted
convex} \citep{IshHeSha2019regular}. This sampling is uniform.

It corresponds to translating points from the negative orthant of the
hyper-sphere to the positive orthant. Thus, the sampling remains uniform.

}
\item{\code{'convex-simplex'}}{

Equivalent to \code{generate_ndset(..., method='simplex')^2}, which is convex
for minimisation. Such a set cannot be obtained by any affine
transformation of a subset of the hyper-sphere.  This sampling is \emph{not}
uniform.

The corresponding surface is equivalent to a simplex curved towards the
origin. The generated points \eqn{\vec{z} \in (0,1)^d \subset
   \mathbb{R}^d} satisfy \eqn{\sum_{i=1}^d \sqrt{z_i} = 1}.  Although the
sampling on the simplex is uniform, the transformed points are not.

}
\item{\code{'concave-simplex'}}{

Equivalent to \code{1 - generate_ndset(..., method='convex-simplex')}, which
is concave for minimisation.  This shape has also been called \emph{inverted
concave} \citep{IshHeSha2019regular}.  This sampling is \emph{not} uniform
because \code{method='convex-simplex'} is also not uniform.

}
\item{\code{'inverted-simplex'} or \code{'inverted-linear'}}{

Equivalent to \code{1 - generate_ndset(..., method='simplex')}. This sampling
is uniform.

}
}

Methods \code{'inverted-simplex'}, \code{'concave-simplex'} and \code{'convex-sphere'} are
translations of \code{'simplex'}, \code{'convex-simplex'} and \code{'concave'}, respectively.
These translations have been called \emph{inverted} shapes in the literature and
have different properties than their \emph{regular} counterparts
\citep{IshHeSha2019regular}.
}
\examples{
generate_ndset(5, 3, "simplex", seed = 42)
generate_ndset(5, 3, "simplex", seed = 42, integer = TRUE)
generate_ndset(4, 2, "sphere", seed = 123)
generate_ndset(3, 5, "convex-sphere", seed = 123)
generate_ndset(4, 4, "convex-simplex", seed = 123)

}
\references{
\insertAllCited{}
}
