Source code for queens.distributions.multinomial

#
# SPDX-License-Identifier: LGPL-3.0-or-later
# Copyright (c) 2024-2025, QUEENS contributors.
#
# This file is part of QUEENS.
#
# QUEENS is free software: you can redistribute it and/or modify it under the terms of the GNU
# Lesser General Public License as published by the Free Software Foundation, either version 3 of
# the License, or (at your option) any later version. QUEENS is distributed in the hope that it will
# be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You
# should have received a copy of the GNU Lesser General Public License along with QUEENS. If not,
# see <https://www.gnu.org/licenses/>.
#
"""Multinomial distribution."""

from typing import override

import numpy as np
from numpy.typing import ArrayLike
from scipy.stats import multinomial

from queens.distributions._distribution import Discrete
from queens.utils.logger_settings import log_init_args


[docs] class Multinomial(Discrete): """Multinomial distribution."""
[docs] @log_init_args def __init__(self, n_trials: int, probabilities: ArrayLike) -> None: """Initialize discrete uniform distribution. Args: n_trials: Number of trials, i.e., the value to which every multivariate sample adds up to. probabilities: Probabilities associated with all the events in the sample space. """ if not isinstance(n_trials, int) or n_trials <= 0: raise ValueError(f"n_trials was set to {n_trials} needs to be a positive integer.") self.n_trials = n_trials probabilities_array = np.array(probabilities) # we misuse the sample_space attribute of the base class to store the number of trials sample_space = np.ones((len(probabilities_array), 1)) * self.n_trials super().__init__(probabilities_array, sample_space, dimension=len(probabilities_array)) self.scipy_multinomial = multinomial(self.n_trials, self.probabilities)
@override def _compute_mean_and_covariance(self) -> tuple[np.ndarray, np.ndarray]: n_trials = self.sample_space[0] mean = n_trials * self.probabilities covariance = n_trials * ( np.diag(self.probabilities) - np.outer(self.probabilities, self.probabilities) ) return mean, covariance
[docs] @override def draw(self, num_draws: int = 1) -> np.ndarray: return np.random.multinomial(self.n_trials, self.probabilities, size=num_draws)
[docs] @override def logpdf(self, x: np.ndarray) -> np.ndarray: return self.scipy_multinomial.logpmf(x)
[docs] @override def pdf(self, x: np.ndarray) -> np.ndarray: return self.scipy_multinomial.pmf(x)
[docs] @override def cdf(self, x: np.ndarray) -> None: super().check_1d()
[docs] @override def ppf(self, quantiles: np.ndarray) -> None: super().check_1d()