maxframe 0.1.0b5__cp310-cp310-macosx_11_0_arm64.whl

maxframe/tensor/random/laplace.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# Copyright 1999-2024 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import numpy as np
+
+from ... import opcodes
+from ...serialization.serializables import AnyField
+from ..utils import gen_random_seeds
+from .core import TensorDistribution, TensorRandomOperatorMixin, handle_array
+
+
+class TensorLaplace(TensorDistribution, TensorRandomOperatorMixin):
+    _input_fields_ = ["loc", "scale"]
+    _op_type_ = opcodes.RAND_LAPLACE
+
+    _fields_ = "loc", "scale", "size"
+    loc = AnyField("loc")
+    scale = AnyField("scale")
+    _func_name = "laplace"
+
+    def __call__(self, loc, scale, chunk_size=None):
+        return self.new_tensor([loc, scale], None, raw_chunk_size=chunk_size)
+
+
+def laplace(
+    random_state, loc=0.0, scale=1.0, size=None, chunk_size=None, gpu=None, dtype=None
+):
+    r"""
+    Draw samples from the Laplace or double exponential distribution with
+    specified location (or mean) and scale (decay).
+
+    The Laplace distribution is similar to the Gaussian/normal distribution,
+    but is sharper at the peak and has fatter tails. It represents the
+    difference between two independent, identically distributed exponential
+    random variables.
+
+    Parameters
+    ----------
+    loc : float or array_like of floats, optional
+        The position, :math:`\mu`, of the distribution peak. Default is 0.
+    scale : float or array_like of floats, optional
+        :math:`\lambda`, the exponential decay. Default is 1.
+    size : int or tuple of ints, optional
+        Output shape.  If the given shape is, e.g., ``(m, n, k)``, then
+        ``m * n * k`` samples are drawn.  If size is ``None`` (default),
+        a single value is returned if ``loc`` and ``scale`` are both scalars.
+        Otherwise, ``np.broadcast(loc, scale).size`` samples are drawn.
+    chunks : int or tuple of int or tuple of ints, optional
+        Desired chunk size on each dimension
+    gpu : bool, optional
+        Allocate the tensor on GPU if True, False as default
+    dtype : data-type, optional
+      Data-type of the returned tensor.
+
+    Returns
+    -------
+    out : Tensor or scalar
+        Drawn samples from the parameterized Laplace distribution.
+
+    Notes
+    -----
+    It has the probability density function
+
+    .. math:: f(x; \mu, \lambda) = \frac{1}{2\lambda}
+                                   \exp\left(-\frac{|x - \mu|}{\lambda}\right).
+
+    The first law of Laplace, from 1774, states that the frequency
+    of an error can be expressed as an exponential function of the
+    absolute magnitude of the error, which leads to the Laplace
+    distribution. For many problems in economics and health
+    sciences, this distribution seems to model the data better
+    than the standard Gaussian distribution.
+
+    References
+    ----------
+    .. [1] Abramowitz, M. and Stegun, I. A. (Eds.). "Handbook of
+           Mathematical Functions with Formulas, Graphs, and Mathematical
+           Tables, 9th printing," New York: Dover, 1972.
+    .. [2] Kotz, Samuel, et. al. "The Laplace Distribution and
+           Generalizations, " Birkhauser, 2001.
+    .. [3] Weisstein, Eric W. "Laplace Distribution."
+           From MathWorld--A Wolfram Web Resource.
+           http://mathworld.wolfram.com/LaplaceDistribution.html
+    .. [4] Wikipedia, "Laplace distribution",
+           http://en.wikipedia.org/wiki/Laplace_distribution
+
+    Examples
+    --------
+    Draw samples from the distribution
+
+    >>> import maxframe.tensor as mt
+
+    >>> loc, scale = 0., 1.
+    >>> s = mt.random.laplace(loc, scale, 1000)
+
+    Display the histogram of the samples, along with
+    the probability density function:
+
+    >>> import matplotlib.pyplot as plt
+    >>> count, bins, ignored = plt.hist(s.execute(), 30, normed=True)
+    >>> x = mt.arange(-8., 8., .01)
+    >>> pdf = mt.exp(-abs(x-loc)/scale)/(2.*scale)
+    >>> plt.plot(x.execute(), pdf.execute())
+
+    Plot Gaussian for comparison:
+
+    >>> g = (1/(scale * mt.sqrt(2 * np.pi)) *
+    ...      mt.exp(-(x - loc)**2 / (2 * scale**2)))
+    >>> plt.plot(x.execute(),g.execute())
+    """
+    if dtype is None:
+        dtype = (
+            np.random.RandomState()
+            .laplace(handle_array(loc), handle_array(scale), size=(0,))
+            .dtype
+        )
+    size = random_state._handle_size(size)
+    seed = gen_random_seeds(1, random_state.to_numpy())[0]
+    op = TensorLaplace(seed=seed, size=size, gpu=gpu, dtype=dtype)
+    return op(loc, scale, chunk_size=chunk_size)

maxframe/tensor/random/logistic.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# Copyright 1999-2024 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import numpy as np
+
+from ... import opcodes
+from ...serialization.serializables import AnyField
+from ..utils import gen_random_seeds
+from .core import TensorDistribution, TensorRandomOperatorMixin, handle_array
+
+
+class TensorLogistic(TensorDistribution, TensorRandomOperatorMixin):
+    _input_fields_ = ["loc", "scale"]
+    _op_type_ = opcodes.RAND_LOGISTIC
+
+    _fields_ = "loc", "scale", "size"
+    loc = AnyField("loc")
+    scale = AnyField("scale")
+    _func_name = "logistic"
+
+    def __call__(self, loc, scale, chunk_size=None):
+        return self.new_tensor([loc, scale], None, raw_chunk_size=chunk_size)
+
+
+def logistic(
+    random_state, loc=0.0, scale=1.0, size=None, chunk_size=None, gpu=None, dtype=None
+):
+    r"""
+    Draw samples from a logistic distribution.
+
+    Samples are drawn from a logistic distribution with specified
+    parameters, loc (location or mean, also median), and scale (>0).
+
+    Parameters
+    ----------
+    loc : float or array_like of floats, optional
+        Parameter of the distribution. Default is 0.
+    scale : float or array_like of floats, optional
+        Parameter of the distribution. Should be greater than zero.
+        Default is 1.
+    size : int or tuple of ints, optional
+        Output shape.  If the given shape is, e.g., ``(m, n, k)``, then
+        ``m * n * k`` samples are drawn.  If size is ``None`` (default),
+        a single value is returned if ``loc`` and ``scale`` are both scalars.
+        Otherwise, ``np.broadcast(loc, scale).size`` samples are drawn.
+    chunk_size : int or tuple of int or tuple of ints, optional
+        Desired chunk size on each dimension
+    gpu : bool, optional
+        Allocate the tensor on GPU if True, False as default
+    dtype : data-type, optional
+      Data-type of the returned tensor.
+
+    Returns
+    -------
+    out : Tensor or scalar
+        Drawn samples from the parameterized logistic distribution.
+
+    See Also
+    --------
+    scipy.stats.logistic : probability density function, distribution or
+        cumulative density function, etc.
+
+    Notes
+    -----
+    The probability density for the Logistic distribution is
+
+    .. math:: P(x) = P(x) = \frac{e^{-(x-\mu)/s}}{s(1+e^{-(x-\mu)/s})^2},
+
+    where :math:`\mu` = location and :math:`s` = scale.
+
+    The Logistic distribution is used in Extreme Value problems where it
+    can act as a mixture of Gumbel distributions, in Epidemiology, and by
+    the World Chess Federation (FIDE) where it is used in the Elo ranking
+    system, assuming the performance of each player is a logistically
+    distributed random variable.
+
+    References
+    ----------
+    .. [1] Reiss, R.-D. and Thomas M. (2001), "Statistical Analysis of
+           Extreme Values, from Insurance, Finance, Hydrology and Other
+           Fields," Birkhauser Verlag, Basel, pp 132-133.
+    .. [2] Weisstein, Eric W. "Logistic Distribution." From
+           MathWorld--A Wolfram Web Resource.
+           http://mathworld.wolfram.com/LogisticDistribution.html
+    .. [3] Wikipedia, "Logistic-distribution",
+           http://en.wikipedia.org/wiki/Logistic_distribution
+
+    Examples
+    --------
+    Draw samples from the distribution:
+
+    >>> import maxframe.tensor as mt
+    >>> import matplotlib.pyplot as plt
+
+    >>> loc, scale = 10, 1
+    >>> s = mt.random.logistic(loc, scale, 10000)
+    >>> count, bins, ignored = plt.hist(s.execute(), bins=50)
+
+    #   plot against distribution
+
+    >>> def logist(x, loc, scale):
+    ...     return mt.exp((loc-x)/scale)/(scale*(1+mt.exp((loc-x)/scale))**2)
+    >>> plt.plot(bins, logist(bins, loc, scale).execute()*count.max()/\
+    ... logist(bins, loc, scale).max().execute())
+    >>> plt.show()
+    """
+    if dtype is None:
+        dtype = (
+            np.random.RandomState()
+            .logistic(handle_array(loc), handle_array(scale), size=(0,))
+            .dtype
+        )
+    size = random_state._handle_size(size)
+    seed = gen_random_seeds(1, random_state.to_numpy())[0]
+    op = TensorLogistic(seed=seed, size=size, gpu=gpu, dtype=dtype)
+    return op(loc, scale, chunk_size=chunk_size)

maxframe/tensor/random/lognormal.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# Copyright 1999-2024 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import numpy as np
+
+from ... import opcodes
+from ...serialization.serializables import AnyField
+from ..utils import gen_random_seeds
+from .core import TensorDistribution, TensorRandomOperatorMixin, handle_array
+
+
+class TensorLognormal(TensorDistribution, TensorRandomOperatorMixin):
+    _input_fields_ = ["mean", "sigma"]
+    _op_type_ = opcodes.RAND_LOGNORMAL
+
+    _fields_ = "mean", "sigma", "size"
+    mean = AnyField("mean")
+    sigma = AnyField("sigma")
+    _func_name = "lognormal"
+
+    def __call__(self, mean, sigma, chunk_size=None):
+        return self.new_tensor([mean, sigma], None, raw_chunk_size=chunk_size)
+
+
+def lognormal(
+    random_state, mean=0.0, sigma=1.0, size=None, chunk_size=None, gpu=None, dtype=None
+):
+    r"""
+    Draw samples from a log-normal distribution.
+
+    Draw samples from a log-normal distribution with specified mean,
+    standard deviation, and array shape.  Note that the mean and standard
+    deviation are not the values for the distribution itself, but of the
+    underlying normal distribution it is derived from.
+
+    Parameters
+    ----------
+    mean : float or array_like of floats, optional
+        Mean value of the underlying normal distribution. Default is 0.
+    sigma : float or array_like of floats, optional
+        Standard deviation of the underlying normal distribution. Should
+        be greater than zero. Default is 1.
+    size : int or tuple of ints, optional
+        Output shape.  If the given shape is, e.g., ``(m, n, k)``, then
+        ``m * n * k`` samples are drawn.  If size is ``None`` (default),
+        a single value is returned if ``mean`` and ``sigma`` are both scalars.
+        Otherwise, ``np.broadcast(mean, sigma).size`` samples are drawn.
+    chunk_size : int or tuple of int or tuple of ints, optional
+        Desired chunk size on each dimension
+    gpu : bool, optional
+        Allocate the tensor on GPU if True, False as default
+    dtype : data-type, optional
+      Data-type of the returned tensor.
+
+    Returns
+    -------
+    out : Tensor or scalar
+        Drawn samples from the parameterized log-normal distribution.
+
+    See Also
+    --------
+    scipy.stats.lognorm : probability density function, distribution,
+        cumulative density function, etc.
+
+    Notes
+    -----
+    A variable `x` has a log-normal distribution if `log(x)` is normally
+    distributed.  The probability density function for the log-normal
+    distribution is:
+
+    .. math:: p(x) = \frac{1}{\sigma x \sqrt{2\pi}}
+                     e^{(-\frac{(ln(x)-\mu)^2}{2\sigma^2})}
+
+    where :math:`\mu` is the mean and :math:`\sigma` is the standard
+    deviation of the normally distributed logarithm of the variable.
+    A log-normal distribution results if a random variable is the *product*
+    of a large number of independent, identically-distributed variables in
+    the same way that a normal distribution results if the variable is the
+    *sum* of a large number of independent, identically-distributed
+    variables.
+
+    References
+    ----------
+    .. [1] Limpert, E., Stahel, W. A., and Abbt, M., "Log-normal
+           Distributions across the Sciences: Keys and Clues,"
+           BioScience, Vol. 51, No. 5, May, 2001.
+           http://stat.ethz.ch/~stahel/lognormal/bioscience.pdf
+    .. [2] Reiss, R.D. and Thomas, M., "Statistical Analysis of Extreme
+           Values," Basel: Birkhauser Verlag, 2001, pp. 31-32.
+
+    Examples
+    --------
+    Draw samples from the distribution:
+
+    >>> import maxframe.tensor as mt
+
+    >>> mu, sigma = 3., 1. # mean and standard deviation
+    >>> s = mt.random.lognormal(mu, sigma, 1000)
+
+    Display the histogram of the samples, along with
+    the probability density function:
+
+    >>> import matplotlib.pyplot as plt
+    >>> count, bins, ignored = plt.hist(s.execute(), 100, normed=True, align='mid')
+
+    >>> x = mt.linspace(min(bins), max(bins), 10000)
+    >>> pdf = (mt.exp(-(mt.log(x) - mu)**2 / (2 * sigma**2))
+    ...        / (x * sigma * mt.sqrt(2 * mt.pi)))
+
+    >>> plt.plot(x.execute(), pdf.execute(), linewidth=2, color='r')
+    >>> plt.axis('tight')
+    >>> plt.show()
+
+    Demonstrate that taking the products of random samples from a uniform
+    distribution can be fit well by a log-normal probability density
+    function.
+
+    >>> # Generate a thousand samples: each is the product of 100 random
+    >>> # values, drawn from a normal distribution.
+    >>> b = []
+    >>> for i in range(1000):
+    ...    a = 10. + mt.random.random(100)
+    ...    b.append(mt.product(a).execute())
+
+    >>> b = mt.array(b) / mt.min(b) # scale values to be positive
+    >>> count, bins, ignored = plt.hist(b.execute(), 100, normed=True, align='mid')
+    >>> sigma = mt.std(mt.log(b))
+    >>> mu = mt.mean(mt.log(b))
+
+    >>> x = mt.linspace(min(bins), max(bins), 10000)
+    >>> pdf = (mt.exp(-(mt.log(x) - mu)**2 / (2 * sigma**2))
+    ...        / (x * sigma * mt.sqrt(2 * mt.pi)))
+
+    >>> plt.plot(x.execute(), pdf.execute(), color='r', linewidth=2)
+    >>> plt.show()
+    """
+    if dtype is None:
+        dtype = (
+            np.random.RandomState()
+            .lognormal(handle_array(mean), handle_array(sigma), size=(0,))
+            .dtype
+        )
+    size = random_state._handle_size(size)
+    seed = gen_random_seeds(1, random_state.to_numpy())[0]
+    op = TensorLognormal(seed=seed, size=size, gpu=gpu, dtype=dtype)
+    return op(mean, sigma, chunk_size=chunk_size)

maxframe/tensor/random/logseries.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# Copyright 1999-2024 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import numpy as np
+
+from ... import opcodes
+from ...serialization.serializables import AnyField
+from ..utils import gen_random_seeds
+from .core import TensorDistribution, TensorRandomOperatorMixin, handle_array
+
+
+class TensorLogseries(TensorDistribution, TensorRandomOperatorMixin):
+    _input_fields_ = ["p"]
+    _op_type_ = opcodes.RAND_LOGSERIES
+
+    _fields_ = "p", "size"
+    p = AnyField("p")
+    _func_name = "logseries"
+
+    def __call__(self, p, chunk_size=None):
+        return self.new_tensor([p], None, raw_chunk_size=chunk_size)
+
+
+def logseries(random_state, p, size=None, chunk_size=None, gpu=None, dtype=None):
+    r"""
+    Draw samples from a logarithmic series distribution.
+
+    Samples are drawn from a log series distribution with specified
+    shape parameter, 0 < ``p`` < 1.
+
+    Parameters
+    ----------
+    p : float or array_like of floats
+        Shape parameter for the distribution.  Must be in the range (0, 1).
+    size : int or tuple of ints, optional
+        Output shape.  If the given shape is, e.g., ``(m, n, k)``, then
+        ``m * n * k`` samples are drawn.  If size is ``None`` (default),
+        a single value is returned if ``p`` is a scalar.  Otherwise,
+        ``np.array(p).size`` samples are drawn.
+    chunk_size : int or tuple of int or tuple of ints, optional
+        Desired chunk size on each dimension
+    gpu : bool, optional
+        Allocate the tensor on GPU if True, False as default
+    dtype : data-type, optional
+      Data-type of the returned tensor.
+
+    Returns
+    -------
+    out : Tensor or scalar
+        Drawn samples from the parameterized logarithmic series distribution.
+
+    See Also
+    --------
+    scipy.stats.logser : probability density function, distribution or
+        cumulative density function, etc.
+
+    Notes
+    -----
+    The probability density for the Log Series distribution is
+
+    .. math:: P(k) = \frac{-p^k}{k \ln(1-p)},
+
+    where p = probability.
+
+    The log series distribution is frequently used to represent species
+    richness and occurrence, first proposed by Fisher, Corbet, and
+    Williams in 1943 [2].  It may also be used to model the numbers of
+    occupants seen in cars [3].
+
+    References
+    ----------
+    .. [1] Buzas, Martin A.; Culver, Stephen J.,  Understanding regional
+           species diversity through the log series distribution of
+           occurrences: BIODIVERSITY RESEARCH Diversity & Distributions,
+           Volume 5, Number 5, September 1999 , pp. 187-195(9).
+    .. [2] Fisher, R.A,, A.S. Corbet, and C.B. Williams. 1943. The
+           relation between the number of species and the number of
+           individuals in a random sample of an animal population.
+           Journal of Animal Ecology, 12:42-58.
+    .. [3] D. J. Hand, F. Daly, D. Lunn, E. Ostrowski, A Handbook of Small
+           Data Sets, CRC Press, 1994.
+    .. [4] Wikipedia, "Logarithmic distribution",
+           http://en.wikipedia.org/wiki/Logarithmic_distribution
+
+    Examples
+    --------
+    Draw samples from the distribution:
+
+    >>> import maxframe.tensor as mt
+    >>> import matplotlib.pyplot as plt
+
+    >>> a = .6
+    >>> s = mt.random.logseries(a, 10000)
+    >>> count, bins, ignored = plt.hist(s.execute())
+
+    #   plot against distribution
+
+    >>> def logseries(k, p):
+    ...     return -p**k/(k*mt.log(1-p))
+    >>> plt.plot(bins, (logseries(bins, a)*count.max()/
+    ...          logseries(bins, a).max()).execute(), 'r')
+    >>> plt.show()
+    """
+    if dtype is None:
+        dtype = np.random.RandomState().logseries(handle_array(p), size=(0,)).dtype
+    size = random_state._handle_size(size)
+    seed = gen_random_seeds(1, random_state.to_numpy())[0]
+    op = TensorLogseries(seed=seed, size=size, gpu=gpu, dtype=dtype)
+    return op(p, chunk_size=chunk_size)

maxframe/tensor/random/multinomial.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# Copyright 1999-2024 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import numpy as np
+
+from ... import opcodes
+from ...serialization.serializables import FieldTypes, Int64Field, TupleField
+from ..utils import gen_random_seeds
+from .core import TensorDistribution, TensorRandomOperatorMixin
+
+
+class TensorMultinomial(TensorDistribution, TensorRandomOperatorMixin):
+    _op_type_ = opcodes.RAND_MULTINOMIAL
+
+    _fields_ = "n", "pvals", "size"
+    n = Int64Field("n")
+    pvals = TupleField("pvals", FieldTypes.float64)
+    _func_name = "multinomial"
+
+    def __call__(self, chunk_size=None):
+        if self.size is None:
+            shape = (len(self.pvals),)
+        else:
+            try:
+                shape = tuple(self.size) + (len(self.pvals),)
+            except TypeError:
+                shape = (self.size, len(self.pvals))
+        return self.new_tensor(None, shape, raw_chunk_size=chunk_size)
+
+
+def multinomial(
+    random_state, n, pvals, size=None, chunk_size=None, gpu=None, dtype=None
+):
+    """
+    Draw samples from a multinomial distribution.
+
+    The multinomial distribution is a multivariate generalisation of the
+    binomial distribution.  Take an experiment with one of ``p``
+    possible outcomes.  An example of such an experiment is throwing a dice,
+    where the outcome can be 1 through 6.  Each sample drawn from the
+    distribution represents `n` such experiments.  Its values,
+    ``X_i = [X_0, X_1, ..., X_p]``, represent the number of times the
+    outcome was ``i``.
+
+    Parameters
+    ----------
+    n : int
+        Number of experiments.
+    pvals : sequence of floats, length p
+        Probabilities of each of the ``p`` different outcomes.  These
+        should sum to 1 (however, the last element is always assumed to
+        account for the remaining probability, as long as
+        ``sum(pvals[:-1]) <= 1)``.
+    size : int or tuple of ints, optional
+        Output shape.  If the given shape is, e.g., ``(m, n, k)``, then
+        ``m * n * k`` samples are drawn.  Default is None, in which case a
+        single value is returned.
+    chunk_size : int or tuple of int or tuple of ints, optional
+        Desired chunk size on each dimension
+    gpu : bool, optional
+        Allocate the tensor on GPU if True, False as default
+    dtype : data-type, optional
+      Data-type of the returned tensor.
+
+    Returns
+    -------
+    out : Tensor
+        The drawn samples, of shape *size*, if that was provided.  If not,
+        the shape is ``(N,)``.
+
+        In other words, each entry ``out[i,j,...,:]`` is an N-dimensional
+        value drawn from the distribution.
+
+    Examples
+    --------
+    Throw a dice 20 times:
+
+    >>> import maxframe.tensor as mt
+
+    >>> mt.random.multinomial(20, [1/6.]*6, size=1).execute()
+    array([[4, 1, 7, 5, 2, 1]])
+
+    It landed 4 times on 1, once on 2, etc.
+
+    Now, throw the dice 20 times, and 20 times again:
+
+    >>> mt.random.multinomial(20, [1/6.]*6, size=2).execute()
+    array([[3, 4, 3, 3, 4, 3],
+           [2, 4, 3, 4, 0, 7]])
+
+    For the first run, we threw 3 times 1, 4 times 2, etc.  For the second,
+    we threw 2 times 1, 4 times 2, etc.
+
+    A loaded die is more likely to land on number 6:
+
+    >>> mt.random.multinomial(100, [1/7.]*5 + [2/7.]).execute()
+    array([11, 16, 14, 17, 16, 26])
+
+    The probability inputs should be normalized. As an implementation
+    detail, the value of the last entry is ignored and assumed to take
+    up any leftover probability mass, but this should not be relied on.
+    A biased coin which has twice as much weight on one side as on the
+    other should be sampled like so:
+
+    >>> mt.random.multinomial(100, [1.0 / 3, 2.0 / 3]).execute()  # RIGHT
+    array([38, 62])
+
+    not like:
+
+    >>> mt.random.multinomial(100, [1.0, 2.0]).execute()  # WRONG
+    array([100,   0])
+    """
+    n = int(n)
+    pvals = tuple(pvals)
+    if dtype is None:
+        dtype = np.random.RandomState().multinomial(n, pvals, size=(0,)).dtype
+    size = random_state._handle_size(size)
+    seed = gen_random_seeds(1, random_state.to_numpy())[0]
+    op = TensorMultinomial(n=n, pvals=pvals, seed=seed, size=size, gpu=gpu, dtype=dtype)
+    return op(chunk_size=chunk_size)