maxframe 2.4.0rc1__cp312-cp312-win32.whl

maxframe/tensor/random/multivariate_normal.py

@@ -0,0 +1,190 @@
+# Copyright 1999-2025 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 Float64Field, NDArrayField, StringField
+from ..utils import gen_random_seeds
+from .core import TensorDistribution, TensorRandomOperatorMixin
+
+
+class TensorMultivariateNormal(TensorDistribution, TensorRandomOperatorMixin):
+    _op_type_ = opcodes.RAND_MULTIVARIATE_NORMAL
+
+    _fields_ = "mean", "cov", "size", "check_valid", "tol"
+    mean = NDArrayField("mean")
+    cov = NDArrayField("cov")
+    check_valid = StringField("check_valid")
+    tol = Float64Field("tol")
+    _func_name = "multivariate_normal"
+
+    def __call__(self, chunk_size=None):
+        N = self.mean.size
+        if self.size is None:
+            shape = (N,)
+        else:
+            try:
+                shape = tuple(self.size) + (N,)
+            except TypeError:
+                shape = (self.size, N)
+
+        return self.new_tensor(None, shape, raw_chunk_size=chunk_size)
+
+
+def multivariate_normal(
+    random_state,
+    mean,
+    cov,
+    size=None,
+    check_valid=None,
+    tol=None,
+    chunk_size=None,
+    gpu=None,
+    dtype=None,
+):
+    """
+    Draw random samples from a multivariate normal distribution.
+
+    The multivariate normal, multinormal or Gaussian distribution is a
+    generalization of the one-dimensional normal distribution to higher
+    dimensions.  Such a distribution is specified by its mean and
+    covariance matrix.  These parameters are analogous to the mean
+    (average or "center") and variance (standard deviation, or "width,"
+    squared) of the one-dimensional normal distribution.
+
+    Parameters
+    ----------
+    mean : 1-D array_like, of length N
+        Mean of the N-dimensional distribution.
+    cov : 2-D array_like, of shape (N, N)
+        Covariance matrix of the distribution. It must be symmetric and
+        positive-semidefinite for proper sampling.
+    size : int or tuple of ints, optional
+        Given a shape of, for example, ``(m,n,k)``, ``m*n*k`` samples are
+        generated, and packed in an `m`-by-`n`-by-`k` arrangement.  Because
+        each sample is `N`-dimensional, the output shape is ``(m,n,k,N)``.
+        If no shape is specified, a single (`N`-D) sample is returned.
+    check_valid : { 'warn', 'raise', 'ignore' }, optional
+        Behavior when the covariance matrix is not positive semidefinite.
+    tol : float, optional
+        Tolerance when checking the singular values in covariance matrix.
+    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.
+
+    Notes
+    -----
+    The mean is a coordinate in N-dimensional space, which represents the
+    location where samples are most likely to be generated.  This is
+    analogous to the peak of the bell curve for the one-dimensional or
+    univariate normal distribution.
+
+    Covariance indicates the level to which two variables vary together.
+    From the multivariate normal distribution, we draw N-dimensional
+    samples, :math:`X = [x_1, x_2, ... x_N]`.  The covariance matrix
+    element :math:`C_{ij}` is the covariance of :math:`x_i` and :math:`x_j`.
+    The element :math:`C_{ii}` is the variance of :math:`x_i` (i.e. its
+    "spread").
+
+    Instead of specifying the full covariance matrix, popular
+    approximations include:
+
+      - Spherical covariance (`cov` is a multiple of the identity matrix)
+      - Diagonal covariance (`cov` has non-negative elements, and only on
+        the diagonal)
+
+    This geometrical property can be seen in two dimensions by plotting
+    generated data-points:
+
+    >>> mean = [0, 0]
+    >>> cov = [[1, 0], [0, 100]]  # diagonal covariance
+
+    Diagonal covariance means that points are oriented along x or y-axis:
+
+    >>> import matplotlib.pyplot as plt
+    >>> import maxframe.tensor as mt
+    >>> x, y = mt.random.multivariate_normal(mean, cov, 5000).T
+    >>> plt.plot(x.execute(), y.execute(), 'x')
+    >>> plt.axis('equal')
+    >>> plt.show()
+
+    Note that the covariance matrix must be positive semidefinite (a.k.a.
+    nonnegative-definite). Otherwise, the behavior of this method is
+    undefined and backwards compatibility is not guaranteed.
+
+    References
+    ----------
+    .. [1] Papoulis, A., "Probability, Random Variables, and Stochastic
+           Processes," 3rd ed., New York: McGraw-Hill, 1991.
+    .. [2] Duda, R. O., Hart, P. E., and Stork, D. G., "Pattern
+           Classification," 2nd ed., New York: Wiley, 2001.
+
+    Examples
+    --------
+    >>> mean = (1, 2)
+    >>> cov = [[1, 0], [0, 1]]
+    >>> x = mt.random.multivariate_normal(mean, cov, (3, 3))
+    >>> x.shape
+    (3, 3, 2)
+
+    The following is probably true, given that 0.6 is roughly twice the
+    standard deviation:
+
+    >>> list(((x[0,0,:] - mean) < 0.6).execute())
+    [True, True]
+    """
+    mean = np.asarray(mean)
+    cov = np.asarray(cov)
+
+    if mean.ndim != 1:
+        raise ValueError("mean must be 1 dimensional")
+    if cov.ndim != 2:
+        raise ValueError("cov must be 1 dimensional")
+    if len(set(mean.shape + cov.shape)) != 1:
+        raise ValueError("mean and cov must have same length")
+
+    if dtype is None:
+        small_kw = {}
+        if check_valid:
+            small_kw["check_valid"] = check_valid
+        if tol:
+            small_kw["tol"] = tol
+        dtype = np.random.multivariate_normal(mean, cov, size=(0,), **small_kw).dtype
+
+    size = random_state._handle_size(size)
+    seed = gen_random_seeds(1, random_state.to_numpy())[0]
+    op = TensorMultivariateNormal(
+        mean=mean,
+        cov=cov,
+        size=size,
+        check_valid=check_valid,
+        tol=tol,
+        seed=seed,
+        gpu=gpu,
+        dtype=dtype,
+    )
+    return op(chunk_size=chunk_size)

maxframe/tensor/random/negative_binomial.py

@@ -0,0 +1,123 @@
+# Copyright 1999-2025 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 TensorNegativeBinomial(TensorDistribution, TensorRandomOperatorMixin):
+    _input_fields_ = ["n", "p"]
+    _op_type_ = opcodes.RAND_NEGATIVE_BINOMIAL
+
+    _fields_ = "n", "p", "size"
+    n = AnyField("n")
+    p = AnyField("p")
+    _func_name = "negative_binomial"
+
+    def __call__(self, n, p, chunk_size=None):
+        return self.new_tensor([n, p], None, raw_chunk_size=chunk_size)
+
+
+def negative_binomial(
+    random_state, n, p, size=None, chunk_size=None, gpu=None, dtype=None
+):
+    r"""
+    Draw samples from a negative binomial distribution.
+
+    Samples are drawn from a negative binomial distribution with specified
+    parameters, `n` trials and `p` probability of success where `n` is an
+    integer > 0 and `p` is in the interval [0, 1].
+
+    Parameters
+    ----------
+    n : int or array_like of ints
+        Parameter of the distribution, > 0. Floats are also accepted,
+        but they will be truncated to integers.
+    p : float or array_like of floats
+        Parameter of the distribution, >= 0 and <=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 ``n`` and ``p`` are both scalars.
+        Otherwise, ``np.broadcast(n, 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 negative binomial distribution,
+        where each sample is equal to N, the number of trials it took to
+        achieve n - 1 successes, N - (n - 1) failures, and a success on the,
+        (N + n)th trial.
+
+    Notes
+    -----
+    The probability density for the negative binomial distribution is
+
+    .. math:: P(N;n,p) = \binom{N+n-1}{n-1}p^{n}(1-p)^{N},
+
+    where :math:`n-1` is the number of successes, :math:`p` is the
+    probability of success, and :math:`N+n-1` is the number of trials.
+    The negative binomial distribution gives the probability of n-1
+    successes and N failures in N+n-1 trials, and success on the (N+n)th
+    trial.
+
+    If one throws a die repeatedly until the third time a "1" appears,
+    then the probability distribution of the number of non-"1"s that
+    appear before the third "1" is a negative binomial distribution.
+
+    References
+    ----------
+    .. [1] Weisstein, Eric W. "Negative Binomial Distribution." From
+           MathWorld--A Wolfram Web Resource.
+           http://mathworld.wolfram.com/NegativeBinomialDistribution.html
+    .. [2] Wikipedia, "Negative binomial distribution",
+           http://en.wikipedia.org/wiki/Negative_binomial_distribution
+
+    Examples
+    --------
+    Draw samples from the distribution:
+
+    A real world example. A company drills wild-cat oil
+    exploration wells, each with an estimated probability of
+    success of 0.1.  What is the probability of having one success
+    for each successive well, that is what is the probability of a
+    single success after drilling 5 wells, after 6 wells, etc.?
+
+    >>> import maxframe.tensor as mt
+
+    >>> s = mt.random.negative_binomial(1, 0.1, 100000)
+    >>> for i in range(1, 11):
+    ...    probability = (mt.sum(s<i) / 100000.).execute()
+    ...    print i, "wells drilled, probability of one success =", probability
+    """
+    if dtype is None:
+        dtype = (
+            np.random.RandomState()
+            .negative_binomial(handle_array(n), handle_array(p), size=(0,))
+            .dtype
+        )
+    size = random_state._handle_size(size)
+    seed = gen_random_seeds(1, random_state.to_numpy())[0]
+    op = TensorNegativeBinomial(size=size, seed=seed, gpu=gpu, dtype=dtype)
+    return op(n, p, chunk_size=chunk_size)

maxframe/tensor/random/noncentral_chisquare.py

@@ -0,0 +1,130 @@
+# Copyright 1999-2025 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 TensorNoncentralChisquare(TensorDistribution, TensorRandomOperatorMixin):
+    _input_fields_ = ["df", "nonc"]
+    _op_type_ = opcodes.RAND_NONCENTRAL_CHISQURE
+
+    _fields_ = "df", "nonc", "size"
+    df = AnyField("df")
+    nonc = AnyField("nonc")
+    _func_name = "noncentral_chisquare"
+
+    def __call__(self, df, nonc, chunk_size=None):
+        return self.new_tensor([df, nonc], None, raw_chunk_size=chunk_size)
+
+
+def noncentral_chisquare(
+    random_state, df, nonc, size=None, chunk_size=None, gpu=None, dtype=None
+):
+    r"""
+    Draw samples from a noncentral chi-square distribution.
+
+    The noncentral :math:`\chi^2` distribution is a generalisation of
+    the :math:`\chi^2` distribution.
+
+    Parameters
+    ----------
+    df : float or array_like of floats
+        Degrees of freedom, should be > 0.
+    nonc : float or array_like of floats
+        Non-centrality, should be non-negative.
+    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 ``df`` and ``nonc`` are both scalars.
+        Otherwise, ``mt.broadcast(df, nonc).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 noncentral chi-square distribution.
+
+    Notes
+    -----
+    The probability density function for the noncentral Chi-square
+    distribution is
+
+    .. math:: P(x;df,nonc) = \sum^{\infty}_{i=0}
+                           \frac{e^{-nonc/2}(nonc/2)^{i}}{i!}
+                           \P_{Y_{df+2i}}(x),
+
+    where :math:`Y_{q}` is the Chi-square with q degrees of freedom.
+
+    In Delhi (2007), it is noted that the noncentral chi-square is
+    useful in bombing and coverage problems, the probability of
+    killing the point target given by the noncentral chi-squared
+    distribution.
+
+    References
+    ----------
+    .. [1] Delhi, M.S. Holla, "On a noncentral chi-square distribution in
+           the analysis of weapon systems effectiveness", Metrika,
+           Volume 15, Number 1 / December, 1970.
+    .. [2] Wikipedia, "Noncentral chi-square distribution"
+           http://en.wikipedia.org/wiki/Noncentral_chi-square_distribution
+
+    Examples
+    --------
+    Draw values from the distribution and plot the histogram
+
+    >>> import matplotlib.pyplot as plt
+    >>> import maxframe.tensor as mt
+    >>> values = plt.hist(mt.random.noncentral_chisquare(3, 20, 100000).execute(),
+    ...                   bins=200, normed=True)
+    >>> plt.show()
+
+    Draw values from a noncentral chisquare with very small noncentrality,
+    and compare to a chisquare.
+
+    >>> plt.figure()
+    >>> values = plt.hist(mt.random.noncentral_chisquare(3, .0000001, 100000).execute(),
+    ...                   bins=mt.arange(0., 25, .1).execute(), normed=True)
+    >>> values2 = plt.hist(mt.random.chisquare(3, 100000).execute(),
+    ...                    bins=mt.arange(0., 25, .1).execute(), normed=True)
+    >>> plt.plot(values[1][0:-1], values[0]-values2[0], 'ob')
+    >>> plt.show()
+
+    Demonstrate how large values of non-centrality lead to a more symmetric
+    distribution.
+
+    >>> plt.figure()
+    >>> values = plt.hist(mt.random.noncentral_chisquare(3, 20, 100000).execute(),
+    ...                   bins=200, normed=True)
+    >>> plt.show()
+    """
+    if dtype is None:
+        dtype = (
+            np.random.RandomState()
+            .noncentral_chisquare(handle_array(df), handle_array(nonc), size=(0,))
+            .dtype
+        )
+    size = random_state._handle_size(size)
+    seed = gen_random_seeds(1, random_state.to_numpy())[0]
+    op = TensorNoncentralChisquare(size=size, seed=seed, gpu=gpu, dtype=dtype)
+    return op(df, nonc, chunk_size=chunk_size)

maxframe/tensor/random/noncentral_f.py

@@ -0,0 +1,124 @@
+# Copyright 1999-2025 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 TensorNoncentralF(TensorDistribution, TensorRandomOperatorMixin):
+    _input_fields_ = ["dfnum", "dfden", "nonc"]
+    _op_type_ = opcodes.RAND_NONCENTRAL_F
+
+    _fields_ = "dfnum", "dfden", "nonc", "size"
+    dfnum = AnyField("dfnum")
+    dfden = AnyField("dfden")
+    nonc = AnyField("nonc")
+    _func_name = "noncentral_f"
+
+    def __call__(self, dfnum, dfden, nonc, chunk_size=None):
+        return self.new_tensor([dfnum, dfden, nonc], None, raw_chunk_size=chunk_size)
+
+
+def noncentral_f(
+    random_state, dfnum, dfden, nonc, size=None, chunk_size=None, gpu=None, dtype=None
+):
+    """
+    Draw samples from the noncentral F distribution.
+
+    Samples are drawn from an F distribution with specified parameters,
+    `dfnum` (degrees of freedom in numerator) and `dfden` (degrees of
+    freedom in denominator), where both parameters > 1.
+    `nonc` is the non-centrality parameter.
+
+    Parameters
+    ----------
+    dfnum : float or array_like of floats
+        Numerator degrees of freedom, should be > 0.
+    dfden : float or array_like of floats
+        Denominator degrees of freedom, should be > 0.
+    nonc : float or array_like of floats
+        Non-centrality parameter, the sum of the squares of the numerator
+        means, should be >= 0.
+    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 ``dfnum``, ``dfden``, and ``nonc``
+        are all scalars.  Otherwise, ``np.broadcast(dfnum, dfden, nonc).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 noncentral Fisher distribution.
+
+    Notes
+    -----
+    When calculating the power of an experiment (power = probability of
+    rejecting the null hypothesis when a specific alternative is true) the
+    non-central F statistic becomes important.  When the null hypothesis is
+    true, the F statistic follows a central F distribution. When the null
+    hypothesis is not true, then it follows a non-central F statistic.
+
+    References
+    ----------
+    .. [1] Weisstein, Eric W. "Noncentral F-Distribution."
+           From MathWorld--A Wolfram Web Resource.
+           http://mathworld.wolfram.com/NoncentralF-Distribution.html
+    .. [2] Wikipedia, "Noncentral F-distribution",
+           http://en.wikipedia.org/wiki/Noncentral_F-distribution
+
+    Examples
+    --------
+    In a study, testing for a specific alternative to the null hypothesis
+    requires use of the Noncentral F distribution. We need to calculate the
+    area in the tail of the distribution that exceeds the value of the F
+    distribution for the null hypothesis.  We'll plot the two probability
+    distributions for comparison.
+
+    >>> import maxframe.tensor as mt
+    >>> import matplotlib.pyplot as plt
+
+    >>> dfnum = 3 # between group deg of freedom
+    >>> dfden = 20 # within groups degrees of freedom
+    >>> nonc = 3.0
+    >>> nc_vals = mt.random.noncentral_f(dfnum, dfden, nonc, 1000000)
+    >>> NF = np.histogram(nc_vals.execute(), bins=50, normed=True)
+    >>> c_vals = mt.random.f(dfnum, dfden, 1000000)
+    >>> F = np.histogram(c_vals.execute(), bins=50, normed=True)
+    >>> plt.plot(F[1][1:], F[0])
+    >>> plt.plot(NF[1][1:], NF[0])
+    >>> plt.show()
+    """
+    if dtype is None:
+        dtype = (
+            np.random.RandomState()
+            .noncentral_f(
+                handle_array(dfnum), handle_array(dfden), handle_array(nonc), size=(0,)
+            )
+            .dtype
+        )
+    size = random_state._handle_size(size)
+    seed = gen_random_seeds(1, random_state.to_numpy())[0]
+    op = TensorNoncentralF(size=size, seed=seed, gpu=gpu, dtype=dtype)
+    return op(dfnum, dfden, nonc, chunk_size=chunk_size)