toqito.perms.perfect_matchings
==============================

.. py:module:: toqito.perms.perfect_matchings

.. autoapi-nested-parse::

   Perfect matchings refers to ways of grouping an even number of objects into pairs.





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

.. py:function:: perfect_matchings(num)

   Give all perfect matchings of `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. [@QETLAB_link].

   .. rubric:: Examples

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

   ```python exec="1" source="above"
   from toqito.perms import perfect_matchings

   print(perfect_matchings(4))
   ```

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

   :returns: An array containing all valid perfect matchings of size `num`.