Function reference

BBA functions

union_address(address, union): -> list
Parameters:
  • address (string) – address (binary format)

  • union (string) – previous union in the arrangement (binary format)

Returns:

unions in Adj(address)

Return type:

list

>>> cdp.union_address('110000', '111000')
['110100', '110010', '110001
address_union(address, union): -> list
Parameters:
  • address (string) – previous address in the arrangement (binary format)

  • union (string) – union (binary format)

Returns:

addresses in Adj(union)

Return type:

list

>>> cdp.address_union('011000', '111000')
['110000', '101000']
searchpath(n, point, t, unions, H = None, W_des = None): -> list

Note

This function is recursive. It is a core function for cdp.bba(), though it can work globally.

Parameters:
  • n (int) – required length of the arrangement

  • point (string) – point to add

  • t ('a' or 'u') – type of the point (‘a’ for address, ‘u’ for union)

  • unions (list) – unions in the arrangement

  • H (list) – addresses in the arrangement

  • W_des (list) – desired balance for the arrangement, optional

Returns:

resulting arrangement of the length n

Return type:

list

>>> cdp.searchpath(n=10, point = '110000', t = 'a', unions = ['111000'])
['110000', '100100', '000110', '000011', '001001', '010001', '010010', '011000', '001100', '101000']
variance_score(bit_sums, s, W_des = None): -> float
Parameters:
  • bit_sums (list) – current balance of the arrangement

  • s (list) – point to add

  • W_des – desired balance, optional

Returns:

penalty for the point based on how much less balanced the arrangement becomes after it is added

Return type:

float

>>> cdp.variance_score([2, 4, 4, 3, 3, 4], '110001')
0.25
return_address_message(code, mode): -> string or list
Parameters:
  • code (list of string) – an address in the index format (for example, [0, 1, 2]) or address in the binary format (for example, ‘111000’)

  • mode ('a' or 'mN') – indicates whether an address has index or binary format if latter, than second letter (N) indicates number of pools

Returns:

corresponding address in the binary format (‘111000’) or in index format ([0, 1, 2])

Return type:

string or list

>>> cdp.return_address_message([1, 2, 4], 'm7')
'0110100'
>>> cdp.return_address_message('0111100', 'a')
[1, 2, 3, 4]
sum_bits(arr): -> list
Parameters:

arr (list) – arrangement with addresses

Returns:

balance of the arrangement

Return type:

list

>>> cdp.sum_bits(['110001', '100101', '000111', '001110', '011010', '010110', '110100', '101100', '101001'])
[5, 4, 4, 6, 4, 4]
starts(m, r, start = None): -> dict
Parameters:
  • m (int) – number of pools in the arrangement

  • r (int) – address weight in the arrangement, i.e. to how many pools one item is added

  • start (str) – desired first address in binary format, optional

Returns:

possible pairs of addresses and unions in the dictionary, where addresses are keys, and unions are values

Return type:

list

>>> cdp.starts(5, 3)
{'11100': ['11110', '11101'],
'11010': ['11110', '11011'],
'11001': ['11101', '11011'],
'10110': ['11110', '10111'],
'10101': ['11101', '10111'],
'10011': ['11011', '10111'],
'01110': ['11110', '01111'],
'01101': ['11101', '01111'],
'01011': ['11011', '01111'],
'00111': ['10111', '01111']}
>>> cdp.starts(5, 2, start = '11000')
{'11000': ['11100', '11010', '11001']}
bba(m, r, n, start_a=None, W_des=None) list, list

Note

Search for arrangement may take some time, especially with large parameters. This function is slower than cdp.rcbba(), but is more reliable.

Parameters:
  • m (int) – number of pools

  • r (int) – address weight, i.e. to how many pools one item is added

  • n (int) – number of items

  • start_a (str) – desired first address of the arrangement, optional

  • W_des – desired balance for the resulting arrangement

Returns:

  1. list with number of item in each pool, i.e. balance;

  2. list with address arrangement

Return type:

list, list

>>> b, H = cdp.bba(n_pools=12, iters=4, len_lst=250)
>>> b
[81, 85, 85, 85, 81, 82, 87, 81, 85, 81, 84, 83]
>>> H
[[0, 1, 2, 3],[0, 1, 3, 6],[0, 1, 6, 8],[1, 6, 8, 9],[6, 8, 9, 11], ... ]

rcBBA functions

item_per_pool(addresses, m): -> numpy array
Parameters:
  • addresses (numpy array) – matrix with addresses

  • m (int) – number of pools

Returns:

balance of the arrangement

Return type:

numpy array

>>> cdp.item_per_pool([[2, 3, 4, 7], [0, 2, 3, 7], [0, 3, 7, 8], [0, 1, 3, 7], [0, 1, 3, 6], [0, 3, 4, 6], [2, 3, 4, 6], [2, 4, 6, 8], [1, 2, 4, 8], [1, 4, 7, 8]], 10)
array([5, 4, 5, 7, 6, 0, 4, 5, 4])
list_union(address_matrix): -> numpy array
Parameters:

address_matrix (numpy array) – matrix with addresses

Returns:

matrix with unions

Return type:

numpy array

>>> cdp.item_per_pool(np.array([[2, 3, 4, 7], [0, 2, 3, 7], [0, 3, 7, 8], [0, 1, 3, 7], [0, 1, 3, 6], [0, 3, 4, 6], [2, 3, 4, 6], [2, 4, 6, 8], [1, 2, 4, 8], [1, 4, 7, 8]]))
array([[0, 2, 3, 4, 7], [0, 2, 3, 7, 8], [0, 1, 3, 7, 8], [0, 1, 3, 6, 7], [0, 1, 3, 4, 6], [0, 2, 3, 4, 6], [2, 3, 4, 6, 8], [1, 2, 4, 6, 8], [1, 2, 4, 7, 8]])
bAU_search(address_matrix, m, I_res): -> list
Parameters:
  • address_matrix (numpy array) – matrix with addresses

  • m (int) – number of pools

  • I_res (list) – residual index set

Returns:

list of possible b’s

Return type:

list of lists

>>> cdp.bAU_search(np.array([[0, 1, 2, 3, 9], [0, 1, 2, 4, 9], [1, 2, 4, 8, 9], [2, 4, 7, 8, 9], [4, 6, 7, 8, 9]]), 10, [0, 1, 2, 3, 4, 5, 6, 7, 8])
array([[0, 1, 2, 3, 5], [0, 1, 2, 3, 6], [0, 1, 2, 3, 7], [0, 1, 2, 3, 8]])
permutation_map(address_matrix, k, b, m, I_res, p=-1): -> numpy array
Parameters:
  • address_matrix (numpy array) – matrix with addresses

  • k (int) – row index

  • b (list) – target address

  • m (int) – number of pools

  • I_res (list) – residual index set

Returns:

matrix with addresses permuted acccording to found map

Return type:

numpy array

>>> cdp.permutation_map(np.array([[0, 1, 8], [1, 2, 8], [2, 3, 8], [3, 4, 8], [4, 6, 8], [6, 7, 8], [5, 7, 8], [0, 5, 8], [1, 5, 8], [4, 5, 8], [0, 4, 8], [0, 2, 8], [0, 3, 8], [3, 7, 8], [3, 6, 8], [2, 6, 8], [2, 7, 8], [1, 7, 8], [1, 6, 8], [5, 6, 8], [3, 5, 8], [2, 5, 8], [2, 4, 8]]), -1, (0, 1, 3), 9, [0, 1, 2, 3, 4, 5, 6, 7, 8])
array([[2, 3, 4], [0, 3, 4], [0, 3, 5], [1, 3, 5], [1, 3, 7], [3, 7, 8], [3, 6, 8], [2, 3, 6], [3, 4, 6], [1, 3, 6], [1, 2, 3], [0, 2, 3], [2, 3, 5], [3, 5, 8], [3, 5, 7], [0, 3, 7], [0, 3, 8], [3, 4, 8], [3, 4, 7], [3, 6, 7], [3, 5, 6], [0, 3, 6], [0, 1, 3]])
gen_elementary_sequence(m, r, I_res, w, b = None): -> numpy array, list
Parameters:
  • m (int) – number of pools

  • r (int) – address weight, i.e. number of pools to which one item is added

  • I_res (list) – residual index set

  • w (int) – required length of the component

  • b (list) – required first address of the permuted sequence, optional

Returns:

  1. generated component

  2. updated residual index set

Return type:

numpy array, list

>>> component, I_res_new = cdp.gen_elementary_sequence(9, 3, [0, 1, 2, 3, 4, 5, 6, 7, 8], 23, (0, 1, 4))
>>> component
array([[2, 3, 4], [0, 3, 4], [0, 4, 7], [4, 5, 7], [4, 5, 6], [1, 4, 6], [1, 4, 8], [2, 4, 8], [0, 2, 4], [2, 4, 7], [2, 4, 5], [1, 4, 5], [1, 3, 4], [3, 4, 8], [4, 6, 8], [0, 4, 6], [4, 6, 7], [1, 4, 7], [3, 4, 7], [3, 4, 5], [0, 4, 5], [0, 4, 8], [0, 1, 4]])
>>> I_res_new
array([0, 1, 2, 3, 5, 6, 7, 8]))
permute(start, b, m, I_res): -> dict
Parameters:
  • start (list) – an address that needs to be permuted

  • b (list) – target address, i.e. how start should look like after the permutation

  • m (int) – number of pools

  • I_res (list) – available residual index set for the permutation map

Returns:

permutation map

Return type:

dict

>>> cdp.permute([0, 1, 2], (0, 1, 4), 6, [0, 1, 2, 4, 5, 8])
{2: 4, 0: 0, 1: 1, 3: 2, 4: 5, 5: 8}
balancing_weights(arr): -> numpy array
Parameters:

arr (numpy array) – residual balance vector

Returns:

residual balance vector without negative numbers

Return type:

numpy array

>>> cdp.balancing_weights(np.array([8, 7, 0, 9, 10, 10, 0, -1, 13, 0]))
array([ 8,  8,  0,  9, 10, 10,  0,  0, 13,  0])
AU_balance(new_weights, perm_vec): -> numpy array
Parameters:
  • new_weights (numpy array) – residual balance vector

  • perm_vec (dict) – permutation map

Returns:

permuted residual balance vector

Return type:

numpy array

>>> cdp.AU_balance(np.array([8, 9, 9, 0, 10, 9, 0, 0, 12, 0]), {2: 4, 0: 0, 1: 1, 3: 2, 4: 5, 5: 8})
array([ 8,  9, 10,  9,  9, 12])
reccom(j, r, n, I_res, weights, w_check = None, H = None): -> numpy array
Parameters:
  • j (int) – number of pools, iteration counter

  • r (int) – address weight, i.e. to how many pools one item is added

  • n (int) – number of items

  • I_res (list) – residual index set

  • weights (numpy array) – residual balance vector

  • w_check (numpy array) – residual balance vector before adding next component

  • H (numpy array) – matrix with addresses (arrangement)

Returns:

the arrangement with new component added

Return type:

numpy array

>>> cdp.reccom(9, 3, 10, [0, 1, 2, 4, 5, 6, 7, 8], np.array([1, 2, 1, 2, 3, 3, 3, 3, 3, 0]), np.array([2, 1, 1, 2, 0, 0, 0, 0, 0, 0]), np.array([[0, 2, 3], [0, 1, 3], [0, 1, 9], [0, 2, 9], [2, 3, 9]]))
array([[0, 1, 2], [1, 2, 5], [1, 4, 5], [0, 4, 5], [0, 2, 4], [0, 2, 3], [0, 1, 3], [0, 1, 9], [0, 2, 9], [2, 3, 9]])
rcbba(m, r, n): -> list, list
Parameters:
  • m (int) – number of pools

  • r (int) – address weight, i.e. to how many pools one item is added

  • n (int) – number of items

Returns:

  1. list with number of items in each pool, i.e. balance;

  2. list with address arrangement

Return type:

list, list

>>> cdp.reccom(9, 3, 10, [0, 1, 2, 4, 5, 6, 7, 8], np.array([1, 2, 1, 2, 3, 3, 3, 3, 3, 0]), np.array([2, 1, 1, 2, 0, 0, 0, 0, 0, 0]), np.array([[0, 2, 3], [0, 1, 3], [0, 1, 9], [0, 2, 9], [2, 3, 9]]))
array([[0, 1, 2], [1, 2, 5], [1, 4, 5], [0, 4, 5], [0, 2, 4], [0, 2, 3], [0, 1, 3], [0, 1, 9], [0, 2, 9], [2, 3, 9]])

Tests

check_unique(lists): -> Boolean, Boolean
Parameters:

lists (list of lists) – an arrangement for the test

Returns:

  1. are addresses unique (True)

  2. are unions unique (True)

Return type:

Boolean, Boolean

>>> b, H = cdp.rcbba(10, 5, 100)
>>> check_unique(H)
(True, True)