:py:mod:`perms.perfect_matchings`
=================================

.. py:module:: perms.perfect_matchings

.. autoapi-nested-parse::

   Perfect matchings.



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


Functions
~~~~~~~~~

.. autoapisummary::

   perms.perfect_matchings.perfect_matchings



.. py:function:: perfect_matchings(num)

   Give all perfect matchings of :code:`num` objects.

   The input can be either an even natural number (the number of objects to be matched) or a `numpy` array containing
   an even number of distinct objects to be matched.

   Returns all perfect matchings of a given list of objects. That is, it returns all ways of grouping an even number of
   objects into pairs.

   This function is adapted from QETLAB. :cite:`QETLAB_link`.

   .. rubric:: Examples

   This is an example of how to generate all perfect matchings of the numbers 1, 2, 3, 4.

   >>> from toqito.perms import perfect_matchings
   >>> perfect_matchings(4)
   array([[1, 2, 3, 4],
          [1, 3, 2, 4],
          [1, 4, 3, 2]])

   .. rubric:: References

   .. bibliography::
       :filter: docname in docnames

   :param num: Either an even integer, indicating that you would like all perfect matchings of the
               integers 1,2, ... N, or a `list` or `np.array` containing an even number of distinct
               entries, indicating that you would like all perfect matchings of those entries.
   :return: An array containing all valid perfect matchings of size :code:`num`.