Utilities for Matching - Cupid Matching

Skip to content

# `matching_utils` module

matching-related utilities

## `MatchingFunctionParam = Callable[[Matching, list[Any]], np.ndarray]` `module-attribute`

Same with a list of additional parameters

## `Matching` `dataclass`

stores the numbers of couples and singles of every type;

muxy is an (X,Y)-matrix n is an X-vector m is an Y-vector mux0 and mu0y are generated as the corresponding numbers of singles

Source code in `cupid_matching/matching_utils.py`

    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    @dataclass
    class Matching:
        """stores the numbers of couples and singles of every type;

        muxy is an (X,Y)-matrix
        n is an X-vector
        m is an Y-vector
        mux0 and mu0y are generated as the corresponding numbers of singles
        """

        mux0: np.ndarray = field(init=False)
        mu0y: np.ndarray = field(init=False)
        muxy: np.ndarray
        n: np.ndarray
        m: np.ndarray

        def __str__(self):
            X, Y = self.muxy.shape
            n_couples = np.sum(self.muxy)
            n_men, n_women = np.sum(self.n), np.sum(self.m)
            repr_str = (
                f"This is a matching with {n_men}  men, {n_women} single women.\n"
            )
            repr_str += f"   with {n_couples} couples,\n \n"
            repr_str += f" We have {X} types of men and {Y} of women."
            print_stars(repr_str)

        def __post_init__(self):
            X, Y = test_matrix(self.muxy)
            Xn = test_vector(self.n)
            Ym = test_vector(self.m)
            if Xn != X:
                bs_error_abort(
                    f"muxy is a ({X}, {Y}) matrix but n has {Xn} elements."
                )
            if Ym != Y:
                bs_error_abort(
                    f"muxy is a ({X}, {Y}) matrix but m has {Ym} elements."
                )
            self.mux0, self.mu0y = _get_singles(self.muxy, self.n, self.m)

        def unpack(self):
            muxy, mux0, mu0y = self.muxy, self.mux0, self.mu0y
            min_xy, min_x0, min_0y = np.min(muxy), np.min(mux0), np.min(mu0y)
            if min_xy < 0.0:
                breakpoint()
                bs_error_abort(f"The smallest muxy is {min_xy}")
            if min_x0 < 0.0:
                breakpoint()
                bs_error_abort(f"The smallest mux0 is {min_x0}")
            if min_0y < 0.0:
                breakpoint()
                bs_error_abort(f"The smallest mux0 is {min_0y}")
            return muxy, mux0, mu0y, self.n, self.m