quantum-mind 2.0.0__py3-none-any.whl

quantum_mind/applications/fusion.py

@@ -0,0 +1,259 @@
+r"""Multimodal fusion for robots: from detector scores, speech and gaze to one belief over intents.
+
+A request such as "bring me that cup" is resolved from several sources: an object detector's scores,
+the speech recogniser's n-best list, where the person looks and where they point. This module turns
+each source into a *likelihood over the same hypotheses* and offers three ways to combine them:
+
+* :func:`bayes_fusion`: independent cues multiply (order-free);
+* :func:`dempster_shafer_fusion`: Dempster's rule with discounted sources, which keeps an explicit
+  "don't know" mass when sources conflict;
+* :class:`~quantum_mind.applications.intent.QuantumIntentResolver`: quantum-like fusion in which incompatible
+  cues are applied as rotated Kraus operators, so cue order matters (it reduces to Bayes when every
+  incompatibility angle is zero); :func:`fit_incompatibility` estimates the angles from logged
+  choices, and :func:`compare_fusion` compares the three rules on held-out data.
+
+Adapters: :func:`detector_likelihood`, :func:`asr_likelihood`, :func:`direction_likelihood` (gaze or
+pointing).
+
+Examples
+--------
+>>> import numpy as np
+>>> from quantum_mind.applications.fusion import detector_likelihood, direction_likelihood, bayes_fusion
+>>> objects = ['red cup', 'blue cup', 'bowl']
+>>> vision = detector_likelihood({'red cup': 0.6, 'blue cup': 0.5, 'bowl': 0.2}, objects)
+>>> gaze = direction_likelihood([1, 0, 0], {'red cup': [0.9, 0.1, 0], 'blue cup': [0, 1, 0],
+...                                         'bowl': [-1, 0, 0]}, objects, kappa=4)
+>>> post = bayes_fusion([vision, gaze])
+>>> objects[int(np.argmax(post))]
+'red cup'
+"""
+from __future__ import annotations
+
+import numpy as np
+from scipy.optimize import minimize
+
+__all__ = ['detector_likelihood', 'asr_likelihood', 'direction_likelihood', 'bayes_fusion',
+           'dempster_shafer_fusion', 'fit_incompatibility', 'compare_fusion']
+
+
+def _norm(v, floor):
+    """Floor and normalise a non-negative vector."""
+    v = np.maximum(np.asarray(v, float), 0) + floor
+    return v / v.sum()
+
+
+def detector_likelihood(scores, hypotheses, temperature=1.0, floor=1e-3):
+    """Likelihood over hypotheses from an object detector's scores.
+
+    Parameters
+    ----------
+    scores : dict or array_like
+        ``{hypothesis: score}`` (missing hypotheses score 0) or scores in the order of ``hypotheses``.
+        Scores are confidences in [0, 1] or logits.
+    hypotheses : sequence
+        Hypotheses (object or intent names).
+    temperature : float, optional
+        Softens (> 1) or sharpens (< 1) the scores before normalising.
+    floor : float, optional
+        Added to every entry so that no hypothesis is ruled out by one cue.
+
+    Returns
+    -------
+    numpy.ndarray
+        Normalised likelihood, one entry per hypothesis.
+    """
+    s = np.array([scores.get(h, 0.0) for h in hypotheses], float) if isinstance(scores, dict) else np.asarray(scores, float)
+    if np.all((s >= 0) & (s <= 1)):              # confidences: power-sharpen or soften
+        return _norm(s ** (1.0 / temperature), floor)
+    z = s / temperature                           # logits: softmax
+    return _norm(np.exp(z - z.max()), floor)
+
+
+def asr_likelihood(nbest, keywords, hypotheses, floor=0.02):
+    """Likelihood over hypotheses from a speech recogniser's n-best list.
+
+    Parameters
+    ----------
+    nbest : sequence of tuple
+        ``[(transcript, confidence), ...]``.
+    keywords : dict
+        ``{hypothesis: [words that refer to it]}``.
+    hypotheses : sequence
+    floor : float, optional
+
+    Returns
+    -------
+    numpy.ndarray
+        Each transcript's confidence is shared among the hypotheses it mentions (or spread over all
+        hypotheses when it mentions none).
+    """
+    L = np.zeros(len(hypotheses))
+    for text, conf in nbest:
+        words = set(text.lower().replace(',', ' ').split())
+        hit = np.array([any(k.lower() in words or k.lower() in text.lower() for k in keywords.get(h, [])) for h in hypotheses])
+        L += conf * (hit / hit.sum() if hit.any() else np.full(len(hypotheses), 1 / len(hypotheses)))
+    return _norm(L, floor)
+
+
+def direction_likelihood(direction, targets, hypotheses, kappa=5.0, floor=1e-3):
+    """Likelihood over hypotheses from a gaze or pointing direction (von Mises-Fisher).
+
+    Parameters
+    ----------
+    direction : array_like
+        Direction vector (2D or 3D) from the person's head or hand.
+    targets : dict
+        ``{hypothesis: direction to that object}`` from the same origin.
+    hypotheses : sequence
+    kappa : float, optional
+        Concentration: larger values trust the direction more.
+    floor : float, optional
+
+    Returns
+    -------
+    numpy.ndarray
+        :math:`\\propto \\exp(\\kappa \\cos \\angle(d, t_h))`.
+    """
+    d = np.asarray(direction, float)
+    d = d / np.linalg.norm(d)
+    cos = []
+    for h in hypotheses:
+        t = np.asarray(targets[h], float)
+        cos.append(float(d @ t / np.linalg.norm(t)))
+    return _norm(np.exp(kappa * (np.array(cos) - 1)), floor)
+
+
+def bayes_fusion(likelihoods, prior=None):
+    """Posterior of independent cues: prior times the product of the likelihoods.
+
+    Parameters
+    ----------
+    likelihoods : sequence of array_like
+        One likelihood vector per cue.
+    prior : array_like, optional
+        Prior over hypotheses (uniform by default).
+
+    Returns
+    -------
+    numpy.ndarray
+    """
+    L = np.asarray(likelihoods, float)
+    post = (np.full(L.shape[1], 1 / L.shape[1]) if prior is None else np.asarray(prior, float)) * np.prod(L, axis=0)
+    return post / post.sum()
+
+
+def dempster_shafer_fusion(likelihoods, reliabilities=None):
+    """Dempster's rule for singleton masses with discounting.
+
+    Each cue becomes a mass function on the single hypotheses, discounted by its reliability r: a
+    fraction 1 - r of its mass goes to "any hypothesis" (ignorance). Conflict between cues is
+    renormalised away by Dempster's rule.
+
+    Parameters
+    ----------
+    likelihoods : sequence of array_like
+        One normalised likelihood per cue.
+    reliabilities : sequence of float, optional
+        Reliability of each cue in [0, 1] (default 0.9).
+
+    Returns
+    -------
+    belief : numpy.ndarray
+        Pignistic probability over hypotheses (ignorance shared equally).
+    ignorance : float
+        Remaining mass on "any hypothesis".
+    """
+    L = np.asarray(likelihoods, float)
+    K = L.shape[1]
+    r = np.full(len(L), 0.9) if reliabilities is None else np.asarray(reliabilities, float)
+    m = np.zeros(K)
+    omega = 1.0                                    # mass on the whole frame (start: total ignorance)
+    for li, ri in zip(L, r):
+        mi = ri * li / li.sum()
+        wi = 1 - ri
+        # combine (m, omega) with (mi, wi) on singletons plus the frame
+        new = m * mi + m * wi + omega * mi
+        new_omega = omega * wi
+        z = new.sum() + new_omega                  # 1 - conflict
+        m, omega = new / z, new_omega / z
+    return m + omega / K, float(omega)
+
+
+def fit_incompatibility(resolver_cls, intents, cue_likelihoods, trials, prior=None, bounds=(0.0, np.pi / 2)):
+    """Fit the incompatibility angle of each cue of a quantum-like resolver from logged choices.
+
+    Parameters
+    ----------
+    resolver_cls : type
+        :class:`~quantum_mind.applications.intent.QuantumIntentResolver`.
+    intents : sequence of str
+        Intent names.
+    cue_likelihoods : dict
+        ``{cue name: likelihood over intents}``.
+    trials : sequence of tuple
+        ``[(cue order, chosen intent), ...]``: the order in which cues arrived and what the person
+        actually wanted (or chose).
+    prior : array_like, optional
+        Prior over intents.
+    bounds : tuple, optional
+        Range of the angles.
+
+    Returns
+    -------
+    resolver : QuantumIntentResolver
+        Resolver with the fitted angles.
+    angles : dict
+        ``{cue name: fitted angle}``.
+    """
+    names = list(cue_likelihoods)
+    idx = {h: i for i, h in enumerate(intents)}
+
+    def build(theta):
+        r = resolver_cls(intents, prior)
+        for n, t in zip(names, theta):
+            r.add_cue(n, cue_likelihoods[n], t)
+        return r
+
+    def nll(theta):
+        r = build(theta)
+        return -sum(np.log(max(r.posterior(order)[idx[c]], 1e-12)) for order, c in trials)
+
+    best = min((minimize(nll, np.full(len(names), x0), method='L-BFGS-B', bounds=[bounds] * len(names))
+                for x0 in (0.05, 0.4, 0.9)), key=lambda r: r.fun)
+    return build(best.x), dict(zip(names, (float(v) for v in best.x)))
+
+
+def compare_fusion(intents, cue_likelihoods, train, test, prior=None):
+    """Compare Bayesian, Dempster-Shafer and fitted quantum-like fusion on held-out trials.
+
+    Parameters
+    ----------
+    intents : sequence of str
+    cue_likelihoods : dict
+        ``{cue name: likelihood over intents}``.
+    train, test : sequence of tuple
+        ``[(cue order, chosen intent), ...]``; the quantum-like angles are fitted on ``train``.
+    prior : array_like, optional
+
+    Returns
+    -------
+    dict
+        ``{rule: {'log_loss': ..., 'accuracy': ...}}`` on ``test`` (lower log loss is better), plus
+        ``'angles'``.
+    """
+    from .intent import QuantumIntentResolver
+    idx = {h: i for i, h in enumerate(intents)}
+    q, angles = fit_incompatibility(QuantumIntentResolver, intents, cue_likelihoods, train, prior)
+    rules = {
+        'bayes': lambda order: bayes_fusion([cue_likelihoods[c] for c in order], prior),
+        'dempster_shafer': lambda order: dempster_shafer_fusion([cue_likelihoods[c] for c in order])[0],
+        'quantum_like': q.posterior,
+    }
+    out = {}
+    for name, rule in rules.items():
+        P = [rule(order) for order, _ in test]
+        y = [idx[c] for _, c in test]
+        out[name] = {'log_loss': float(-np.mean([np.log(max(p[i], 1e-12)) for p, i in zip(P, y)])),
+                     'accuracy': float(np.mean([int(np.argmax(p)) == i for p, i in zip(P, y)]))}
+    out['angles'] = angles
+    return out

quantum_mind/applications/handover.py

@@ -0,0 +1,197 @@
+r"""Trust-aware hand-over: a robot policy built on the trust qubit.
+
+The robot hands objects to a person. Whether the person takes the object smoothly depends on how much
+they trust the robot at that moment, and trust changes with every success and failure
+(:class:`~quantum_mind.families.dynamics.OpenSystemBelief`). The robot can also *ask* about trust, which tells it
+where trust stands but, in the quantum-like model, also changes it (the question collapses the belief).
+
+At each step the policy compares the expected cost of four actions:
+
+=================  ==========================================================================
+``handover``       normal speed; fails with probability :math:`1 - p_{\text{trust}}`
+``slow_handover``  slower and more legible; costs ``slow_cost`` but halves the failure risk
+``ask``            costs ``ask_cost``; the answer collapses the belief, then the better of the
+                   two hand-overs is chosen for the next step (one-step look-ahead)
+``wait``           costs ``wait_cost``; the belief keeps dephasing toward its mixed state
+=================  ==========================================================================
+
+The same policy can run on the classical :class:`~quantum_mind.families.dynamics.MarkovBelief`, where asking
+only reads trust; comparing the two shows when the order-aware model changes the robot's behaviour.
+
+Examples
+--------
+>>> from quantum_mind.families.dynamics import OpenSystemBelief
+>>> from quantum_mind.applications.handover import TrustAwareHandover
+>>> policy = TrustAwareHandover(OpenSystemBelief(phi0=0.6, a_pos=0.8, a_neg=1.2, gamma=0.3))
+>>> policy.decide()['action']                      # high trust: hand over normally
+'handover'
+>>> policy.observe(0); policy.observe(0)           # two failures
+>>> policy.decide()['action'] != 'handover'
+True
+"""
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = ['TrustAwareHandover', 'simulate_handover_session']
+
+
+class TrustAwareHandover:
+    """Hand-over policy on a trust belief.
+
+    Parameters
+    ----------
+    model : OpenSystemBelief or MarkovBelief
+        Trust model, with its parameters (fitted to the person or the population).
+    fail_cost : float, optional
+        Cost of a failed hand-over (dropped object, startled person).
+    slow_cost : float, optional
+        Extra cost of a slow hand-over.
+    ask_cost : float, optional
+        Cost of asking "do you trust me to hand this over?".
+    wait_cost : float, optional
+        Cost of waiting one step.
+    slow_factor : float, optional
+        Failure probability of a slow hand-over relative to a normal one.
+
+    Attributes
+    ----------
+    rho : numpy.ndarray
+        Current trust belief as a 2 x 2 density matrix (open-system model), or ``None``.
+    p : float
+        Current P(trust) (Markov model), or ``None``.
+    """
+
+    def __init__(self, model, fail_cost=10.0, slow_cost=1.0, ask_cost=0.5, wait_cost=0.3, slow_factor=0.5):
+        self.model = model
+        self.fail_cost, self.slow_cost, self.ask_cost = fail_cost, slow_cost, ask_cost
+        self.wait_cost, self.slow_factor = wait_cost, slow_factor
+        self.quantum = hasattr(model, 'phi0') and hasattr(model, 'gamma')
+        if self.quantum:
+            v = np.array([np.cos(model.phi0 / 2), np.sin(model.phi0 / 2)])
+            self.rho = np.outer(v, v)
+            self.p = None
+        else:
+            self.rho = None
+            self.p = float(model.p0)
+
+    # ------------------------------------------------------------------ belief
+    @property
+    def p_trust(self):
+        """float: current probability that the person trusts the robot (says "yes")."""
+        return float(np.clip(self.rho[0, 0], 0, 1)) if self.quantum else self.p
+
+    def _rotate(self, rho, event):
+        """Open-system update after one event: rotation, then dephasing."""
+        a = -self.model.a_pos if event else self.model.a_neg
+        c, s = np.cos(a / 2), np.sin(a / 2)
+        U = np.array([[c, -s], [s, c]])
+        r = U @ rho @ U.T
+        f = 1 - self.model.gamma
+        return np.array([[r[0, 0], f * r[0, 1]], [f * r[1, 0], r[1, 1]]])
+
+    def observe(self, event):
+        """Update the belief after a hand-over outcome.
+
+        Parameters
+        ----------
+        event : int
+            1 for a success, 0 for a failure.
+        """
+        if self.quantum:
+            self.rho = self._rotate(self.rho, event)
+        else:
+            self.p = self.model.step(self.p, event)
+
+    def answer(self, yes):
+        """Update the belief after the person answers the trust question.
+
+        In the open-system model the answer collapses the belief onto "trust" or "no trust"; in the
+        Markov model it sets P(trust) to 1 or 0.
+
+        Parameters
+        ----------
+        yes : bool or int
+        """
+        if self.quantum:
+            self.rho = np.diag([1.0, 0.0]) if yes else np.diag([0.0, 1.0])
+        else:
+            self.p = 1.0 if yes else 0.0
+
+    def wait(self):
+        """Let one step pass without a hand-over (dephasing only, open-system model)."""
+        if self.quantum:
+            f = 1 - self.model.gamma
+            self.rho = np.array([[self.rho[0, 0], f * self.rho[0, 1]], [f * self.rho[1, 0], self.rho[1, 1]]])
+
+    # ------------------------------------------------------------------ decision
+    def _handover_costs(self, p):
+        """Expected cost of a normal and a slow hand-over at trust probability p."""
+        return self.fail_cost * (1 - p), self.slow_cost + self.fail_cost * (1 - p) * self.slow_factor
+
+    def decide(self):
+        """Expected cost of each action and the best one.
+
+        Returns
+        -------
+        dict
+            ``action`` (the cheapest), ``costs`` (``{action: expected cost}``) and ``p_trust``.
+        """
+        p = self.p_trust
+        normal, slow = self._handover_costs(p)
+        # asking: pay ask_cost, then hand over optimally given the collapsed answer
+        after_yes, after_no = min(self._handover_costs(1.0)), min(self._handover_costs(0.0))
+        ask = self.ask_cost + p * after_yes + (1 - p) * after_no
+        costs = {'handover': normal, 'slow_handover': slow, 'ask': ask, 'wait': self.wait_cost + min(normal, slow)}
+        return {'action': min(costs, key=costs.get), 'costs': costs, 'p_trust': p}
+
+
+def simulate_handover_session(policy, person, events_rng, n_steps=20):
+    """Run a policy against a simulated person whose trust follows a model.
+
+    The person's real trust (a separate copy of the model) determines whether each hand-over succeeds
+    and how the trust question is answered; the policy only sees outcomes and answers.
+
+    Parameters
+    ----------
+    policy : TrustAwareHandover
+        The robot's policy (its own belief).
+    person : TrustAwareHandover
+        The simulated person's true trust state (only its belief is used).
+    events_rng : numpy.random.Generator
+    n_steps : int, optional
+
+    Returns
+    -------
+    dict
+        ``cost`` (total), ``failures``, ``asks`` and ``actions`` (list).
+    """
+    total = 0.0
+    failures = asks = 0
+    actions = []
+    for _ in range(n_steps):
+        d = policy.decide()
+        a = d['action']
+        actions.append(a)
+        if a == 'ask':
+            total += policy.ask_cost
+            yes = events_rng.random() < person.p_trust
+            person.answer(yes)                      # asking changes the person's trust too
+            policy.answer(yes)
+            asks += 1
+            continue
+        if a == 'wait':
+            total += policy.wait_cost
+            person.wait()
+            policy.wait()
+            continue
+        p_fail = 1 - person.p_trust
+        if a == 'slow_handover':
+            total += policy.slow_cost
+            p_fail *= policy.slow_factor
+        ok = events_rng.random() >= p_fail
+        total += 0 if ok else policy.fail_cost
+        failures += int(not ok)
+        person.observe(int(ok))
+        policy.observe(int(ok))
+    return {'cost': total, 'failures': failures, 'asks': asks, 'actions': actions}

quantum_mind/applications/intent.py

@@ -0,0 +1,196 @@
+r"""Intent resolution from ambiguous commands and context cues (robots, assistants, interfaces).
+
+A user's intent is one of K options ("fetch the red cup", "fetch the blue cup", ...). Each context cue
+(a word, a gesture, a gaze direction, the time of day) carries a likelihood over intents. Classical
+Bayesian updating multiplies the likelihoods, so the order in which cues arrive does not matter.
+
+:class:`QuantumIntentResolver` represents belief as amplitudes :math:`\psi = \sqrt{\text{prior}}` and
+applies each cue c as a Kraus operator
+
+.. math:: K_c = R(\theta_c)\,\mathrm{diag}\bigl(\sqrt{L_c}\bigr)\,R(\theta_c)^T,
+
+where :math:`R(\theta_c)` rotates the intent basis by the cue's incompatibility angle
+:math:`\theta_c`, in the plane of the cue's two most likely intents. With every
+:math:`\theta_c = 0` the posterior is exactly Bayes' rule; :math:`\theta_c \neq 0` makes cues
+incompatible, so their order matters, as in question-order effects. The angles can be fitted to
+observed choices.
+
+Examples
+--------
+>>> from quantum_mind.applications.intent import QuantumIntentResolver
+>>> r = QuantumIntentResolver(['red cup', 'blue cup', 'bowl'])
+>>> _ = r.add_cue('points left', [0.70, 0.20, 0.10], theta=0.5)
+>>> _ = r.add_cue('looks right', [0.25, 0.60, 0.15], theta=0.5)
+>>> r.posterior(['points left', 'looks right']).round(3)
+array([0.482, 0.498, 0.02 ])
+>>> round(r.order_effect('points left', 'looks right'), 3)
+0.079
+"""
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = ['QuantumIntentResolver', 'BayesIntentResolver']
+
+
+class BayesIntentResolver:
+    """Classical baseline: posterior proportional to the prior times the cue likelihoods.
+
+    Parameters
+    ----------
+    intents : sequence of str
+        Names of the K possible intents.
+    prior : array_like, optional
+        Prior over intents (normalised); uniform by default.
+
+    Attributes
+    ----------
+    cues : dict
+        Registered cues, by name.
+    """
+
+    def __init__(self, intents, prior=None):
+        self.intents = list(intents)
+        K = len(self.intents)
+        self.prior = np.full(K, 1 / K) if prior is None else _prob(prior, K)
+        self.cues = {}
+
+    def add_cue(self, name, likelihood, theta=0.0):
+        """Register a cue.
+
+        Parameters
+        ----------
+        name : str
+            Cue name.
+        likelihood : array_like
+            Non-negative likelihood of the cue under each intent.
+        theta : float, optional
+            Ignored here (classical cues commute); used by :class:`QuantumIntentResolver`.
+
+        Returns
+        -------
+        BayesIntentResolver
+            ``self``, so calls can be chained.
+        """
+        self.cues[name] = _prob(likelihood, len(self.intents), normalise=False)
+        return self
+
+    def posterior(self, cues):
+        """Intent probabilities after a sequence of cues.
+
+        Parameters
+        ----------
+        cues : sequence of str
+            Names of registered cues.
+
+        Returns
+        -------
+        numpy.ndarray
+            Posterior over intents (independent of the order of ``cues``).
+        """
+        p = self.prior.copy()
+        for c in cues:
+            p = p * self.cues[c]
+            p = p / p.sum()
+        return p
+
+    def order_effect(self, a, b):
+        """Size of the order effect between two cues.
+
+        Parameters
+        ----------
+        a, b : str
+            Cue names.
+
+        Returns
+        -------
+        float
+            Total variation distance between the posteriors for orders (a, b) and (b, a); always 0 for
+            the Bayesian resolver.
+        """
+        return 0.5 * float(np.abs(self.posterior([a, b]) - self.posterior([b, a])).sum())
+
+
+class QuantumIntentResolver(BayesIntentResolver):
+    """Quantum-like intent resolver; it reduces to :class:`BayesIntentResolver` when every angle is 0.
+
+    Parameters
+    ----------
+    intents : sequence of str
+        Names of the K possible intents.
+    prior : array_like, optional
+        Prior over intents; the initial amplitudes are its square roots.
+    """
+
+    def add_cue(self, name, likelihood, theta=0.0):
+        """Register a cue as a Kraus operator.
+
+        Parameters
+        ----------
+        name : str
+            Cue name.
+        likelihood : array_like
+            Non-negative likelihood of the cue under each intent.
+        theta : float, optional
+            Incompatibility angle in radians (0: the cue commutes with every other cue).
+
+        Returns
+        -------
+        QuantumIntentResolver
+            ``self``.
+        """
+        L = _prob(likelihood, len(self.intents), normalise=False)
+        i, j = np.argsort(L)[::-1][:2]                      # rotate in the plane of the two leading intents
+        R = np.eye(len(L))
+        c, s = np.cos(theta), np.sin(theta)
+        R[[i, i, j, j], [i, j, i, j]] = [c, -s, s, c]
+        self.cues[name] = R @ np.diag(np.sqrt(L)) @ R.T
+        return self
+
+    def posterior(self, cues):
+        """Intent probabilities :math:`|\\psi|^2` after applying the cues in order.
+
+        Parameters
+        ----------
+        cues : sequence of str
+            Names of registered cues, in the order they arrived.
+
+        Returns
+        -------
+        numpy.ndarray
+        """
+        psi = np.sqrt(self.prior)
+        for c in cues:
+            psi = self.cues[c] @ psi
+            psi = psi / np.linalg.norm(psi)
+        return psi ** 2
+
+    def resolve(self, cues):
+        """Most likely intent after the cues.
+
+        Parameters
+        ----------
+        cues : sequence of str
+            Names of registered cues, in order.
+
+        Returns
+        -------
+        intent : str
+            Most likely intent.
+        probability : float
+            Its posterior probability.
+        entropy : float
+            Entropy of the posterior in bits (high values suggest asking for clarification).
+        """
+        p = self.posterior(cues)
+        k = int(np.argmax(p))
+        H = float(-np.sum(p[p > 0] * np.log2(p[p > 0])))
+        return self.intents[k], float(p[k]), H
+
+
+def _prob(v, K, normalise=True):
+    """Validate K non-negative weights and optionally normalise them."""
+    v = np.asarray(v, float)
+    if v.shape != (K,) or np.any(v < 0) or v.sum() <= 0:
+        raise ValueError('expected %d non-negative weights' % K)
+    return v / v.sum() if normalise else v