Skip to content

Commit

Permalink
Doc sample change (apache#6094)
Browse files Browse the repository at this point in the history 
* documentation changes for random sampling operators

* added myself to contributor list

* lint fixes

* used italic font for variables according to review comment
  • Loading branch information
@asmushetzel @madjam
asmushetzel authored and madjam committed May 4, 2017
1 parent e9f281a commit 400498d
Show file tree
Hide file tree
Showing 7 changed files with 345 additions and 85 deletions.
1 change: 1 addition & 0 deletions CONTRIBUTORS.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -133,3 +133,4 @@ List of Contributors
* [Jun Wu](https://github.com/reminisce)
* [Dom Divakaruni](https://github.com/domdivakaruni)
* [David Salinas](https://github.com/geoalgo)
* [Asmus Hetzel](https://github.com/asmushetzel)
9 changes: 7 additions & 2 deletions docs/api/python/ndarray.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -369,8 +369,13 @@ In the rest of this document, we first overview the methods provided by the
.. autosummary::
:nosignatures:
uniform
normal
random_uniform
random_normal
random_gamma
random_exponential
random_poisson
random_negative_binomial
random_generalized_negative_binomial
mxnet.random.seed
```

Expand Down
16 changes: 14 additions & 2 deletions docs/api/python/symbol.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -357,8 +357,20 @@ Composite multiple symbols into a new one by an operator.
.. autosummary::
:nosignatures:
uniform
normal
random_uniform
random_normal
random_gamma
random_exponential
random_poisson
random_negative_binomial
random_generalized_negative_binomial
sample_uniform
sample_normal
sample_gamma
sample_exponential
sample_poisson
sample_negative_binomial
sample_generalized_negative_binomial
mxnet.random.seed
```

Expand Down
242 changes: 215 additions & 27 deletions src/operator/tensor/multisample_op.cc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -116,22 +116,14 @@ struct GeneralizedNegativeBinomialSampler {
};
};


DMLC_REGISTER_PARAMETER(MultiSampleParam);

#define MXNET_OPERATOR_REGISTER_SAMPLING(distr, sampler, num_inputs, \
input_name_1, input_name_2, description) \
input_name_1, input_name_2, \
input_desc_1, input_desc_2, \
description) \
NNVM_REGISTER_OP(sample_##distr) \
.MXNET_DESCRIBE("Multi-sampling from " description "." \
" The parameters of the distributions are provided as input tensor(s)." \
" Let \"[s]\" be the shape of the input tensor(s), \"n\" be the dimension of [s], \"[t]\"" \
" be the shape specified as the parameter of the operator, and \"m\" be the dimension" \
" of [t]. Then the output will be a (n+m)-dimensional tensor with shape [s]x[t]. For any" \
" valid n-dimensional index \"i\" with respect to the input tensor(s), output[i] will be" \
" an m-dimensional tensor that holds randomly drawn samples from the distribution which" \
" is parameterized by the input values at index i. If the shape parameter of the operator" \
" is not set, then one sample will be drawn per distribution and the output tensor has" \
" the same dimensions as the input tensor(s).") \
.describe(description()+std::string(ADD_FILELINE)) \
.set_num_inputs(num_inputs) \
.set_num_outputs(1) \
.set_attr_parser(ParamParser<MultiSampleParam>) \
Expand All @@ -147,31 +139,227 @@ DMLC_REGISTER_PARAMETER(MultiSampleParam);
.set_attr<FCompute>("FCompute<cpu>", MultiSampleOpForward<cpu, sampler>) \
.set_attr<nnvm::FGradient>("FGradient", MakeZeroGradNodes) \
.add_arguments(MultiSampleParam::__FIELDS__()) \
.add_argument(input_name_1, "NDArray", "")
.add_argument(input_name_1, "NDArray-or-Symbol", input_desc_1)

#define MXNET_OPERATOR_REGISTER_SAMPLING1(distr, sampler, input_name, input_desc, \
description) \
MXNET_OPERATOR_REGISTER_SAMPLING(distr, sampler, 1, input_name, input_name, \
input_desc, input_desc, description);

#define MXNET_OPERATOR_REGISTER_SAMPLING2(distr, sampler, input_name_1, input_name_2, \
input_desc_1, input_desc_2, description) \
MXNET_OPERATOR_REGISTER_SAMPLING(distr, sampler, 2, input_name_1, input_name_2, \
input_desc_1, input_desc_2, description) \
.add_argument(input_name_2, "NDArray-or-Symbol", input_desc_2);

inline std::string uniform_desc() {
return std::string(R"code(Concurrent sampling from multiple
uniform distributions on the intervals given by *[low,high)*.
The parameters of the distributions are provided as input arrays.
Let *[s]* be the shape of the input arrays, *n* be the dimension of *[s]*, *[t]*
be the shape specified as the parameter of the operator, and *m* be the dimension
of *[t]*. Then the output will be a *(n+m)*-dimensional array with shape *[s]x[t]*. For any
valid *n*-dimensional index *i* with respect to the input arrays, *output[i]* will be
an *m*-dimensional array that holds randomly drawn samples from the distribution which
is parameterized by the input values at index *i*. If the shape parameter of the
operator is not set, then one sample will be drawn per distribution and the output array
has the same shape as the input arrays.
Examples::
low = [ 0.0, 2.5 ]
high = [ 1.0, 3.7 ]
// Draw a single sample for each distribution
sample_uniform(low, high) = [ 0.40451524, 3.18687344]
// Draw a vector containing two samples for each distribution
sample_uniform(low, high, shape=(2)) = [[ 0.40451524, 0.18017688],
[ 3.18687344, 3.68352246]]
)code");
}

inline std::string normal_desc() {
return std::string(R"code(Concurrent sampling from multiple
normal distributions with parameters *mu* (mean) and *sigma* (standard deviation).
The parameters of the distributions are provided as input arrays.
Let *[s]* be the shape of the input arrays, *n* be the dimension of *[s]*, *[t]*
be the shape specified as the parameter of the operator, and *m* be the dimension
of *[t]*. Then the output will be a *(n+m)*-dimensional array with shape *[s]x[t]*. For any
valid *n*-dimensional index *i* with respect to the input arrays, *output[i]* will be
an *m*-dimensional array that holds randomly drawn samples from the distribution which
is parameterized by the input values at index *i*. If the shape parameter of the
operator is not set, then one sample will be drawn per distribution and the output array
has the same shape as the input arrays.
Examples::
mu = [ 0.0, 2.5 ]
sigma = [ 1.0, 3.7 ]
// Draw a single sample for each distribution
sample_normal(mu, sigma) = [-0.56410581, 0.95934606]
// Draw a vector containing two samples for each distribution
sample_normal(mu, sigma, shape=(2)) = [[-0.56410581, 0.2928229 ],
[ 0.95934606, 4.48287058]]
)code");
}

inline std::string gamma_desc() {
return std::string(R"code(Concurrent sampling from multiple
gamma distributions with parameters *alpha* (shape) and *beta* (scale).
The parameters of the distributions are provided as input arrays.
Let *[s]* be the shape of the input arrays, *n* be the dimension of *[s]*, *[t]*
be the shape specified as the parameter of the operator, and *m* be the dimension
of *[t]*. Then the output will be a *(n+m)*-dimensional array with shape *[s]x[t]*. For any
valid *n*-dimensional index *i* with respect to the input arrays, *output[i]* will be
an *m*-dimensional array that holds randomly drawn samples from the distribution which
is parameterized by the input values at index *i*. If the shape parameter of the
operator is not set, then one sample will be drawn per distribution and the output array
has the same shape as the input arrays.
Examples::
alpha = [ 0.0, 2.5 ]
beta = [ 1.0, 0.7 ]
// Draw a single sample for each distribution
sample_gamma(alpha, beta) = [ 0. , 2.25797319]
// Draw a vector containing two samples for each distribution
sample_gamma(alpha, beta, shape=(2)) = [[ 0. , 0. ],
[ 2.25797319, 1.70734084]]
)code");
}

inline std::string exponential_desc() {
return std::string(R"code(Concurrent sampling from multiple
exponential distributions with parameters lambda (rate).
The parameters of the distributions are provided as an input array.
Let *[s]* be the shape of the input array, *n* be the dimension of *[s]*, *[t]*
be the shape specified as the parameter of the operator, and *m* be the dimension
of *[t]*. Then the output will be a *(n+m)*-dimensional array with shape *[s]x[t]*. For any
valid *n*-dimensional index *i* with respect to the input array, *output[i]* will be
an *m*-dimensional array that holds randomly drawn samples from the distribution which
is parameterized by the input value at index *i*. If the shape parameter of the
operator is not set, then one sample will be drawn per distribution and the output array
has the same shape as the input array.
Examples::
lam = [ 1.0, 8.5 ]
// Draw a single sample for each distribution
sample_exponential(lam) = [ 0.51837951, 0.09994757]
// Draw a vector containing two samples for each distribution
sample_exponential(lam, shape=(2)) = [[ 0.51837951, 0.19866663],
[ 0.09994757, 0.50447971]]
)code");
}

inline std::string poisson_desc() {
return std::string(R"code(Concurrent sampling from multiple
Poisson distributions with parameters lambda (rate).
The parameters of the distributions are provided as an input array.
Let *[s]* be the shape of the input array, *n* be the dimension of *[s]*, *[t]*
be the shape specified as the parameter of the operator, and *m* be the dimension
of *[t]*. Then the output will be a *(n+m)*-dimensional array with shape *[s]x[t]*. For any
valid *n*-dimensional index *i* with respect to the input array, *output[i]* will be
an *m*-dimensional array that holds randomly drawn samples from the distribution which
is parameterized by the input value at index *i*. If the shape parameter of the
operator is not set, then one sample will be drawn per distribution and the output array
has the same shape as the input array.
Samples will always be returned as a floating point data type.
Examples::
lam = [ 1.0, 8.5 ]
// Draw a single sample for each distribution
sample_poisson(lam) = [ 0., 13.]
// Draw a vector containing two samples for each distribution
sample_poisson(lam, shape=(2)) = [[ 0., 4.],
[ 13., 8.]]
)code");
}

inline std::string negative_binomial_desc() {
return std::string(R"code(Concurrent sampling from multiple
negative binomial distributions with parameters *k* (failure limit) and *p* (failure probability).
The parameters of the distributions are provided as input arrays.
Let *[s]* be the shape of the input arrays, *n* be the dimension of *[s]*, *[t]*
be the shape specified as the parameter of the operator, and *m* be the dimension
of *[t]*. Then the output will be a *(n+m)*-dimensional array with shape *[s]x[t]*. For any
valid *n*-dimensional index *i* with respect to the input arrays, *output[i]* will be
an *m*-dimensional array that holds randomly drawn samples from the distribution which
is parameterized by the input values at index *i*. If the shape parameter of the
operator is not set, then one sample will be drawn per distribution and the output array
has the same shape as the input arrays.
Samples will always be returned as a floating point data type.
Examples::
k = [ 20, 49 ]
p = [ 0.4 , 0.77 ]
// Draw a single sample for each distribution
sample_negative_binomial(k, p) = [ 15., 16.]
// Draw a vector containing two samples for each distribution
sample_negative_binomial(k, p, shape=(2)) = [[ 15., 50.],
[ 16., 12.]]
)code");
}

inline std::string generalized_negative_binomial_desc() {
return std::string(R"code(Concurrent sampling from multiple
generalized negative binomial distributions with parameters *mu* (mean) and *alpha* (dispersion).
The parameters of the distributions are provided as input arrays.
Let *[s]* be the shape of the input arrays, *n* be the dimension of *[s]*, *[t]*
be the shape specified as the parameter of the operator, and *m* be the dimension
of *[t]*. Then the output will be a *(n+m)*-dimensional array with shape *[s]x[t]*. For any
valid *n*-dimensional index *i* with respect to the input arrays, *output[i]* will be
an *m*-dimensional array that holds randomly drawn samples from the distribution which
is parameterized by the input values at index *i*. If the shape parameter of the
operator is not set, then one sample will be drawn per distribution and the output array
has the same shape as the input arrays.
Samples will always be returned as a floating point data type.
Examples::
mu = [ 2.0, 2.5 ]
alpha = [ 1.0, 0.1 ]
#define MXNET_OPERATOR_REGISTER_SAMPLING1(distr, sampler, input_name, description) \
MXNET_OPERATOR_REGISTER_SAMPLING(distr, sampler, 1, input_name, input_name, description);
// Draw a single sample for each distribution
sample_generalized_negative_binomial(mu, alpha) = [ 0., 3.]
#define MXNET_OPERATOR_REGISTER_SAMPLING2(distr, sampler, input_name_1, input_name_2, description) \
MXNET_OPERATOR_REGISTER_SAMPLING(distr, sampler, 2, input_name_1, input_name_2, description) \
.add_argument(input_name_2, "NDArray", "");
// Draw a vector containing two samples for each distribution
sample_generalized_negative_binomial(mu, alpha, shape=(2)) = [[ 0., 3.],
[ 3., 1.]]
)code");
}

MXNET_OPERATOR_REGISTER_SAMPLING2(uniform, UniformSampler, "low", "high",
"uniform distributions on the interval [low,high)")
"Lower bounds of the distributions.", "Upper bounds of the distributions.", uniform_desc)
MXNET_OPERATOR_REGISTER_SAMPLING2(normal, NormalSampler, "mu", "sigma",
"normal distributions with parameters mu and sigma")
"Means of the distributions.", "Standard deviations of the distributions.", normal_desc)
MXNET_OPERATOR_REGISTER_SAMPLING2(gamma, GammaSampler, "alpha", "beta",
"gamma distributions with parameters alpha and beta")
"Alpha (shape) parameters of the distributions.", "Beta (scale) parameters of the distributions.",
gamma_desc)
MXNET_OPERATOR_REGISTER_SAMPLING1(exponential, ExponentialSampler, "lam",
"exponential distributions with parameters lambda")
"Lambda (rate) parameters of the distributions.", exponential_desc)
MXNET_OPERATOR_REGISTER_SAMPLING1(poisson, PoissonSampler, "lam",
"Poisson distributions with parameters lambda")
"Lambda (rate) parameters of the distributions.", poisson_desc)
MXNET_OPERATOR_REGISTER_SAMPLING2(negative_binomial, NegativeBinomialSampler, "k", "p",
"negative binomial distributions with parameters k (failure limit) and p (failure probability)")
"Limits of unsuccessful experiments.", "Failure probabilities in each experiment.",
negative_binomial_desc)
MXNET_OPERATOR_REGISTER_SAMPLING2(generalized_negative_binomial,
GeneralizedNegativeBinomialSampler, "mu", "alpha",
"generalized negative binomial distributions with parameters mu (mean)"
" and alpha (over dispersion)")
GeneralizedNegativeBinomialSampler, "mu", "alpha",
"Means of the distributions.", "Alpha (dispersion) parameters of the distributions.",
generalized_negative_binomial_desc)

} // namespace op
} // namespace mxnet
6 changes: 3 additions & 3 deletions src/operator/tensor/multisample_op.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,12 +25,12 @@ struct MultiSampleParam : public dmlc::Parameter<MultiSampleParam> {
.describe("Shape to be sampled from each random distribution.");
DMLC_DECLARE_FIELD(dtype)
.add_enum("None", -1)
.add_enum("float16", mshadow::kFloat16)
.add_enum("float32", mshadow::kFloat32)
.add_enum("float64", mshadow::kFloat64)
.add_enum("float16", mshadow::kFloat16)
.set_default(-1)
.describe("DType of the output. If output given, set to type of output."
"If output not given and type not defined (dtype=None), set to float32.");
.describe("DType of the output in case this can't be inferred. "
"Defaults to float32 if not defined (dtype=None).");
}
};

Expand Down
Loading

0 comments on commit 400498d

Please sign in to comment.