From 46773f9557aba578449cf4cdb02500df086bb935 Mon Sep 17 00:00:00 2001 From: Xun Deng Date: Fri, 4 Sep 2020 11:11:02 -0400 Subject: [PATCH] add specification of private interface arguments in docs --- .../nn/probability/distribution/bernoulli.py | 40 +++++++++++----- .../probability/distribution/exponential.py | 39 +++++++++++---- .../nn/probability/distribution/geometric.py | 38 +++++++++++---- .../nn/probability/distribution/normal.py | 47 ++++++++++++++----- .../nn/probability/distribution/uniform.py | 45 +++++++++++++----- 5 files changed, 155 insertions(+), 54 deletions(-) diff --git a/mindspore/nn/probability/distribution/bernoulli.py b/mindspore/nn/probability/distribution/bernoulli.py index b3591cd360c..46423b2e6bd 100644 --- a/mindspore/nn/probability/distribution/bernoulli.py +++ b/mindspore/nn/probability/distribution/bernoulli.py @@ -33,7 +33,7 @@ class Bernoulli(Distribution): Note: probs should be proper probabilities (0 < p < 1). - Dist_spec_args is probs. + dist_spec_args is probs. Examples: >>> # To initialize a Bernoulli distribution of prob 0.5 @@ -57,32 +57,50 @@ class Bernoulli(Distribution): >>> # All the following calls in construct are valid >>> def construct(self, value, probs_b, probs_a): >>> + >>> # Private interfaces of probability functions corresponding to public interfaces, including + >>> # 'prob', 'log_prob', 'cdf', 'log_cdf', 'survival_function', 'log_survival', have the form: + >>> # Args: + >>> # value (Tensor): value to be evaluated. + >>> # probs1 (Tensor): probability of success. Default: self.probs. + >>> + >>> # Example of prob. >>> # Similar calls can be made to other probability functions >>> # by replacing 'prob' with the name of the function >>> ans = self.b1.prob(value) >>> # Evaluate with the respect to distribution b >>> ans = self.b1.prob(value, probs_b) - >>> >>> # probs must be passed in during function calls >>> ans = self.b2.prob(value, probs_a) >>> - >>> # Functions 'sd', 'var', 'entropy' have the same usage as 'mean' - >>> # Will return 0.5 - >>> ans = self.b1.mean() - >>> # Will return probs_b - >>> ans = self.b1.mean(probs_b) >>> + >>> # Functions 'sd', 'var', 'entropy' have the same args. + >>> # Args: + >>> # probs1 (Tensor): probability of success. Default: self.probs. + >>> + >>> # Example of mean. sd, var have similar usage. + >>> ans = self.b1.mean() # return 0.5 + >>> ans = self.b1.mean(probs_b) # return probs_b >>> # probs must be passed in during function calls >>> ans = self.b2.mean(probs_a) >>> - >>> # Usage of 'kl_loss' and 'cross_entropy' are similar + >>> + >>> # Interfaces of 'kl_loss' and 'cross_entropy' are similar: + >>> # Args: + >>> # dist (str): name of the distribution. Only 'Bernoulli' is supported. + >>> # probs1_b (Tensor): probability of success of distribution b. + >>> # probs1_a (Tensor): probability of success of distribution a. Default: self.probs. + >>> + >>> # Example of kl_loss (cross_entropy is similar): >>> ans = self.b1.kl_loss('Bernoulli', probs_b) >>> ans = self.b1.kl_loss('Bernoulli', probs_b, probs_a) - >>> - >>> # Additional probs_a must be passed in through + >>> # Additional probs_a must be passed in >>> ans = self.b2.kl_loss('Bernoulli', probs_b, probs_a) >>> - >>> # Sample + >>> + >>> # sample + >>> # Args: + >>> # shape (tuple): shape of the sample. Default: () + >>> # probs1 (Tensor): probability of success. Default: self.probs. >>> ans = self.b1.sample() >>> ans = self.b1.sample((2,3)) >>> ans = self.b1.sample((2,3), probs_b) diff --git a/mindspore/nn/probability/distribution/exponential.py b/mindspore/nn/probability/distribution/exponential.py index 7262e2779c2..005b750d32a 100644 --- a/mindspore/nn/probability/distribution/exponential.py +++ b/mindspore/nn/probability/distribution/exponential.py @@ -34,7 +34,8 @@ class Exponential(Distribution): Note: rate should be strictly greater than 0. - Dist_spec_args is rate. + dist_spec_args is rate. + dtype should be float type because Exponential distributions are continuous. Examples: >>> # To initialize an Exponential distribution of rate 0.5 @@ -58,32 +59,50 @@ class Exponential(Distribution): >>> # All the following calls in construct are valid >>> def construct(self, value, rate_b, rate_a): >>> + >>> # Private interfaces of probability functions corresponding to public interfaces, including + >>> # 'prob', 'log_prob', 'cdf', 'log_cdf', 'survival_function', 'log_survival', have the form: + >>> # Args: + >>> # value (Tensor): value to be evaluated. + >>> # rate (Tensor): rate of the distribution. Default: self.rate. + >>> + >>> # Example of prob. >>> # Similar calls can be made to other probability functions >>> # by replacing 'prob' with the name of the function >>> ans = self.e1.prob(value) >>> # Evaluate with the respect to distribution b >>> ans = self.e1.prob(value, rate_b) - >>> >>> # Rate must be passed in during function calls >>> ans = self.e2.prob(value, rate_a) >>> - >>> # Functions 'sd', 'var', 'entropy' have the same usage as'mean' - >>> # Will return 2 - >>> ans = self.e1.mean() - >>> # Will return 1 / rate_b - >>> ans = self.e1.mean(rate_b) >>> + >>> # Functions 'sd', 'var', 'entropy' have the same args. + >>> # Args: + >>> # rate (Tensor): rate of the distribution. Default: self.rate. + >>> + >>> # Example of mean. sd, var have similar usage. + >>> ans = self.e1.mean() # return 2 + >>> ans = self.e1.mean(rate_b) # return 1 / rate_b >>> # Rate must be passed in during function calls >>> ans = self.e2.mean(rate_a) >>> - >>> # Usage of 'kl_loss' and 'cross_entropy' are similar + >>> + >>> # Interfaces of 'kl_loss' and 'cross_entropy' are similar: + >>> # Args: + >>> # dist (str): name of the distribution. Only 'Exponential' is supported. + >>> # rate_b (Tensor): rate of distribution b. + >>> # rate_a (Tensor): rate of distribution a. Default: self.rate. + >>> + >>> # Example of kl_loss (cross_entropy is similar): >>> ans = self.e1.kl_loss('Exponential', rate_b) >>> ans = self.e1.kl_loss('Exponential', rate_b, rate_a) - >>> >>> # Additional rate must be passed in >>> ans = self.e2.kl_loss('Exponential', rate_b, rate_a) >>> - >>> # Sample + >>> + >>> # sample + >>> # Args: + >>> # shape (tuple): shape of the sample. Default: () + >>> # probs1 (Tensor): rate of distribution. Default: self.rate. >>> ans = self.e1.sample() >>> ans = self.e1.sample((2,3)) >>> ans = self.e1.sample((2,3), rate_b) diff --git a/mindspore/nn/probability/distribution/geometric.py b/mindspore/nn/probability/distribution/geometric.py index 47beff931bd..e5d1c56dfbb 100644 --- a/mindspore/nn/probability/distribution/geometric.py +++ b/mindspore/nn/probability/distribution/geometric.py @@ -36,7 +36,7 @@ class Geometric(Distribution): Note: probs should be proper probabilities (0 < p < 1). - Dist_spec_args is probs. + dist_spec_args is probs. Examples: >>> # To initialize a Geometric distribution of prob 0.5 @@ -60,32 +60,50 @@ class Geometric(Distribution): >>> # Tthe following calls are valid in construct >>> def construct(self, value, probs_b, probs_a): >>> + >>> # Private interfaces of probability functions corresponding to public interfaces, including + >>> # 'prob', 'log_prob', 'cdf', 'log_cdf', 'survival_function', 'log_survival', have the form: + >>> # Args: + >>> # value (Tensor): value to be evaluated. + >>> # probs1 (Tensor): probability of success of a Bernoulli trail. Default: self.probs. + >>> + >>> # Example of prob. >>> # Similar calls can be made to other probability functions >>> # by replacing 'prob' with the name of the function >>> ans = self.g1.prob(value) >>> # Evaluate with the respect to distribution b >>> ans = self.g1.prob(value, probs_b) - >>> >>> # Probs must be passed in during function calls >>> ans = self.g2.prob(value, probs_a) >>> - >>> # Functions 'sd', 'var', 'entropy' have the same usage as 'mean' - >>> # Will return 1.0 - >>> ans = self.g1.mean() - >>> # Another possible usage - >>> ans = self.g1.mean(probs_b) >>> + >>> # Functions 'sd', 'var', 'entropy' have the same args. + >>> # Args: + >>> # probs1 (Tensor): probability of success of a Bernoulli trail. Default: self.probs. + >>> + >>> # Example of mean. sd, var have similar usage. + >>> ans = self.g1.mean() # return 1.0 + >>> ans = self.g1.mean(probs_b) >>> # Probs must be passed in during function calls >>> ans = self.g2.mean(probs_a) >>> - >>> # Usage of 'kl_loss' and 'cross_entropy' are similar + >>> + >>> # Interfaces of 'kl_loss' and 'cross_entropy' are similar: + >>> # Args: + >>> # dist (str): name of the distribution. Only 'Geometric' is supported. + >>> # probs1_b (Tensor): probability of success of a Bernoulli trail of distribution b. + >>> # probs1_a (Tensor): probability of success of a Bernoulli trail of distribution a. Default: self.probs. + >>> + >>> # Example of kl_loss (cross_entropy is similar): >>> ans = self.g1.kl_loss('Geometric', probs_b) >>> ans = self.g1.kl_loss('Geometric', probs_b, probs_a) - >>> >>> # Additional probs must be passed in >>> ans = self.g2.kl_loss('Geometric', probs_b, probs_a) >>> - >>> # Sample + >>> + >>> # sample + >>> # Args: + >>> # shape (tuple): shape of the sample. Default: () + >>> # probs1 (Tensor): probability of success of a Bernoulli trail. Default: self.probs. >>> ans = self.g1.sample() >>> ans = self.g1.sample((2,3)) >>> ans = self.g1.sample((2,3), probs_b) diff --git a/mindspore/nn/probability/distribution/normal.py b/mindspore/nn/probability/distribution/normal.py index 132eb534813..0c4862195c7 100644 --- a/mindspore/nn/probability/distribution/normal.py +++ b/mindspore/nn/probability/distribution/normal.py @@ -35,7 +35,8 @@ class Normal(Distribution): Note: Standard deviation should be greater than zero. - Dist_spec_args are mean and sd. + dist_spec_args are mean and sd. + dtype should be float type because Normal distributions are continuous. Examples: >>> # To initialize a Normal distribution of mean 3.0 and standard deviation 4.0 @@ -59,32 +60,54 @@ class Normal(Distribution): >>> # The following calls are valid in construct >>> def construct(self, value, mean_b, sd_b, mean_a, sd_a): >>> + >>> # Private interfaces of probability functions corresponding to public interfaces, including + >>> # 'prob', 'log_prob', 'cdf', 'log_cdf', 'survival_function', 'log_survival', have the form: + >>> # Args: + >>> # value (Tensor): value to be evaluated. + >>> # mean (Tensor): mean of distribution. Default: self._mean_value. + >>> # sd (Tensor): standard deviation of distribution. Default: self._sd_value. + >>> + >>> # Example of prob. >>> # Similar calls can be made to other probability functions >>> # by replacing 'prob' with the name of the function >>> ans = self.n1.prob(value) >>> # Evaluate with the respect to distribution b >>> ans = self.n1.prob(value, mean_b, sd_b) - >>> >>> # mean and sd must be passed in during function calls >>> ans = self.n2.prob(value, mean_a, sd_a) >>> - >>> # Functions 'sd', 'var', 'entropy' have the same usage as 'mean' - >>> # will return [0.0] - >>> ans = self.n1.mean() - >>> # will return mean_b - >>> ans = self.n1.mean(mean_b, sd_b) >>> - >>> # mean and sd must be passed during function calls + >>> # Functions 'sd', 'var', 'entropy' have the same args. + >>> # Args: + >>> # mean (Tensor): mean of distribution. Default: self._mean_value. + >>> # sd (Tensor): standard deviation of distribution. Default: self._sd_value. + >>> + >>> # Example of mean. sd, var have similar usage. + >>> ans = self.n1.mean() # return 0.0 + >>> ans = self.n1.mean(mean_b, sd_b) # return mean_b + >>> # mean and sd must be passed in during function calls >>> ans = self.n2.mean(mean_a, sd_a) >>> - >>> # Usage of 'kl_loss' and 'cross_entropy' are similar + >>> + >>> # Interfaces of 'kl_loss' and 'cross_entropy' are similar: + >>> # Args: + >>> # dist (str): type of the distributions. Should be "Normal" in this case. + >>> # mean_b (Tensor): mean of distribution b. + >>> # sd_b (Tensor): standard deviation distribution b. + >>> # mean_a (Tensor): mean of distribution a. Default: self._mean_value. + >>> # sd_a (Tensor): standard deviation distribution a. Default: self._sd_value. + >>> + >>> # Example of kl_loss (cross_entropy is similar): >>> ans = self.n1.kl_loss('Normal', mean_b, sd_b) >>> ans = self.n1.kl_loss('Normal', mean_b, sd_b, mean_a, sd_a) - >>> - >>> # Additional mean and sd must be passed + >>> # Additional mean and sd must be passed in >>> ans = self.n2.kl_loss('Normal', mean_b, sd_b, mean_a, sd_a) >>> - >>> # Sample + >>> # sample + >>> # Args: + >>> # shape (tuple): shape of the sample. Default: () + >>> # mean (Tensor): mean of distribution. Default: self._mean_value. + >>> # sd (Tensor): standard deviation of distribution. Default: self._sd_value. >>> ans = self.n1.sample() >>> ans = self.n1.sample((2,3)) >>> ans = self.n1.sample((2,3), mean_b, sd_b) diff --git a/mindspore/nn/probability/distribution/uniform.py b/mindspore/nn/probability/distribution/uniform.py index 7a43f7e1081..9cd86cf9aeb 100644 --- a/mindspore/nn/probability/distribution/uniform.py +++ b/mindspore/nn/probability/distribution/uniform.py @@ -34,7 +34,8 @@ class Uniform(Distribution): Note: low should be stricly less than high. - Dist_spec_args are high and low. + dist_spec_args are high and low. + dtype should be float type because Uniform distributions are continuous. Examples: >>> # To initialize a Uniform distribution of mean 3.0 and standard deviation 4.0 @@ -58,32 +59,54 @@ class Uniform(Distribution): >>> # All the following calls in construct are valid >>> def construct(self, value, low_b, high_b, low_a, high_a): >>> + >>> # Private interfaces of probability functions corresponding to public interfaces, including + >>> # 'prob', 'log_prob', 'cdf', 'log_cdf', 'survival_function', 'log_survival', have the form: + >>> # Args: + >>> # value (Tensor): value to be evaluated. + >>> # low (Tensor): lower bound of distribution. Default: self.low. + >>> # high (Tensor): higher bound of distribution. Default: self.high. + >>> + >>> # Example of prob. >>> # Similar calls can be made to other probability functions >>> # by replacing 'prob' with the name of the function >>> ans = self.u1.prob(value) >>> # Evaluate with the respect to distribution b >>> ans = self.u1.prob(value, low_b, high_b) - >>> >>> # High and low must be passed in during function calls >>> ans = self.u2.prob(value, low_a, high_a) >>> - >>> # Functions 'sd', 'var', 'entropy' have the same usage as 'mean' - >>> # Will return 0.5 - >>> ans = self.u1.mean() - >>> # Will return (low_b + high_b) / 2 - >>> ans = self.u1.mean(low_b, high_b) >>> + >>> # Functions 'sd', 'var', 'entropy' have the same args. + >>> # Args: + >>> # low (Tensor): lower bound of distribution. Default: self.low. + >>> # high (Tensor): higher bound of distribution. Default: self.high. + >>> + >>> # Example of mean. sd, var have similar usage. + >>> ans = self.u1.mean() # return 0.5 + >>> ans = self.u1.mean(low_b, high_b) # return (low_b + high_b) / 2 >>> # High and low must be passed in during function calls >>> ans = self.u2.mean(low_a, high_a) >>> - >>> # Usage of 'kl_loss' and 'cross_entropy' are similar + >>> # Interfaces of 'kl_loss' and 'cross_entropy' are similar: + >>> # Args: + >>> # dist (str): type of the distributions. Should be "Uniform" in this case. + >>> # low_b (Tensor): lower bound of distribution b. + >>> # high_b (Tensor): upper bound of distribution b. + >>> # low_a (Tensor): lower bound of distribution a. Default: self.low. + >>> # high_a (Tensor): upper bound of distribution a. Default: self.high. + >>> + >>> # Example of kl_loss (cross_entropy is similar): >>> ans = self.u1.kl_loss('Uniform', low_b, high_b) >>> ans = self.u1.kl_loss('Uniform', low_b, high_b, low_a, high_a) - >>> - >>> # Additional high and low must be passed + >>> # Additional high and low must be passed in >>> ans = self.u2.kl_loss('Uniform', low_b, high_b, low_a, high_a) >>> - >>> # Sample + >>> + >>> # sample + >>> # Args: + >>> # shape (tuple): shape of the sample. Default: () + >>> # low (Tensor): lower bound of distribution. Default: self.low. + >>> # high (Tensor): higher bound of distribution. Default: self.high. >>> ans = self.u1.sample() >>> ans = self.u1.sample((2,3)) >>> ans = self.u1.sample((2,3), low_b, high_b)