:py:mod:`meetupmatcher.matcher`
===============================

.. py:module:: meetupmatcher.matcher


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   meetupmatcher.matcher.ProblemStatement
   meetupmatcher.matcher.SolutionNumbers
   meetupmatcher.matcher.PairUpResult
   meetupmatcher.matcher.PairUpStatistics



Functions
~~~~~~~~~

.. autoapisummary::

   meetupmatcher.matcher._solve_numeric
   meetupmatcher.matcher.solve_numeric
   meetupmatcher.matcher.lexicographic_greater
   meetupmatcher.matcher.sample
   meetupmatcher.matcher._pair_up
   meetupmatcher.matcher.pair_up



.. py:exception:: NoSolution


   Bases: :py:obj:`Exception`

   Common base class for all non-exit exceptions.


.. py:exception:: TooFewPeople


   Bases: :py:obj:`NoSolution`

   Common base class for all non-exit exceptions.


.. py:exception:: IncompatibleAvailabilities


   Bases: :py:obj:`NoSolution`

   Common base class for all non-exit exceptions.


.. py:class:: ProblemStatement


   All information required to determine the number of groups

   .. py:attribute:: n_people
      :type: int

      

   .. py:attribute:: n_notwo
      :type: int

      

   .. py:method:: __post_init__()



.. py:class:: SolutionNumbers


   Number of groups and similar information

   .. py:property:: n_people
      :type: int

      Total number of people

   .. py:attribute:: partitions
      :type: tuple[int, int, int]

      

   .. py:attribute:: removed
      :type: int
      :value: 0

      


.. py:function:: _solve_numeric(ps: ProblemStatement) -> SolutionNumbers


.. py:function:: solve_numeric(ps: ProblemStatement) -> SolutionNumbers


.. py:function:: lexicographic_greater(a: numpy.ndarray, b: numpy.ndarray) -> bool

   Return True if a is lexicographically greater than b


.. py:function:: sample(mask: numpy.ndarray, n: int, availabilities: numpy.ndarray | None = None, *, rng: numpy.random.Generator | None = None, max_joint_av_boon=5, wasted_resource_offset=3) -> tuple[numpy.ndarray, int]

   Put people in a group of fixed size in a way that helps to maximize the number
   of joint availabilities of each group in the ent.

   :param mask:
   :param n: Sample/group size
   :param availabilities:
   :param rng:
   :param max_joint_av_boon: This limits the probability boost for joint availabilities.
   :param wasted_resource_offset: The lower this parameter, the more we punish people with
                                  many availabilities being assigned to a group where the joint availability
                                  does not "profit from it"

   :returns: Set of indices of people belonging into group, joint availabilities


.. py:class:: PairUpResult


   Concrete solution that matched people to groups

   .. py:property:: av_sums
      :type: numpy.ndarray


   .. py:property:: n_removed
      :type: int


   .. py:property:: min_av_sum
      :type: int


   .. py:property:: mean_av_sum
      :type: float


   .. py:attribute:: segmentation
      :type: list[set[int]]

      

   .. py:attribute:: removed
      :type: set[int]

      

   .. py:attribute:: cost
      :type: numpy.ndarray

      

   .. py:attribute:: joint_availabilities
      :type: numpy.ndarray

      

   .. py:method:: __post_init__()



.. py:function:: _pair_up(sn: SolutionNumbers, idx: numpy.ndarray, notwo: numpy.ndarray, best_cost: numpy.ndarray, availabilities: numpy.ndarray | None = None, *, rng: numpy.random.Generator | None = None) -> PairUpResult | None

   Single trial of pairing up people.

   :param sn: SolutionNumbers, specifying the number of groups of each size
   :param idx:
   :param notwo: Boolean array: Who vetoes to be in a group of only two-people
   :param best_cost: Minimal objective function so far
   :param availabilities: Boolean array of n_people x n_timeslots
   :param rng: Random number generator

   :returns: None if we abort early because the current solution is worse than the best


.. py:class:: PairUpStatistics


   Statistics about the sampling process that optimizes the objective function

   .. py:attribute:: df
      :type: pandas.DataFrame

      

   .. py:attribute:: best
      :type: numpy.ndarray

      

   .. py:attribute:: solution_pair_avs
      :type: numpy.ndarray

      


.. py:function:: pair_up(sn: SolutionNumbers, idx: numpy.ndarray, notwo: numpy.ndarray | None = None, availabilities: numpy.ndarray | None = None, *, max_tries=1000000, abort_after_stable=100000, rng: numpy.random.Generator | None = None) -> tuple[PairUpResult, PairUpStatistics]

   Pair up people by optimizing the objective function over multiple trials.

   :param sn: SolutionNumbers, specifying the number of groups of each size
   :param idx: Indices of people to be paired up
   :param notwo: Boolean array: Who vetoes to be in a group of only two-people
   :param availabilities: Boolean array of n_people x n_timeslots
   :param max_tries: Maximum number of trials
   :param abort_after_stable: Abort after this many trials without improvement
   :param rng: Random number generator

   :returns: PairUpResult, PairUpStatistics