Generators Reference

`module` `generators`

Submodules:

language_model
quantum_computing
random
structured

`module` `generators.language_model`

`function` `p_first_and_last`

def p_first_and_last(
    mera_depth: int,
    axis_size_hidden: int,
    axis_size_observable: int
) → tuple[str, list[tuple[int, ]]]

Generates an einsum query and shape arguments for computing the distribution of the first and last observable in a model with the given parameters.

Args:

mera_depth (int): Number of layers in a MERA network with 4th-order tensors.
axis_size_hidden (int): Domain size of hidden variables.
axis_size_observable (int): Domain size of observable variables.

Returns:

tuple[str, list[tuple[int, ...]]]: The einsum format string, which is needed to compute the distribution, and the shapes of its arguments.

Example:

format_string, argument_shapes = p_first_and_last(mera_depth=1, axis_size_hidden=3, axis_size_observable=11)

`function` `sliding_likelihood`

def sliding_likelihood(
    mera_depth: int,
    axis_size_hidden: int,
    axis_size_observable: int,
    batch_size: int
) → tuple[str, list[tuple[int, ]]]

Generates an einsum query and shape arguments for computing the likelihood of the model on an imaginary batch of training data.

Args:

mera_depth (int): Number of layers in a MERA network with 4th-order tensors.
axis_size_hidden (int): Domain size of hidden variables.
axis_size_observable (int): Domain size of observable variables.
batch_size (int): Number of context windows to compute the likelihood for.

Returns:

tuple[str, list[tuple[int, ...]]]: The einsum format string, which is needed to compute the batch likelihood, and the shapes of its arguments.

Example:

format_string, shapes = sliding_likelihood(mera_depth=1, axis_size_hidden=3, axis_size_observable=11, batch_size=100)

`module` `generators.quantum_computing`

`function` `matrix_product_state`

def matrix_product_state(
    n=100,
    phys_dim_min=10,
    phys_dim_max=200,
    bond_dim=20,
    seed=None
)

Generates a matrix product state (MPS) for a quantum computing simulation.

Args:

n (int): The number of sites in the MPS. Default is 100.
phys_dim_min (int): The minimum physical dimension of each site. Default is 10.
phys_dim_max (int): The maximum physical dimension of each site. Default is 200.
bond_dim (int): The bond dimension between neighboring sites. Default is 20.
seed (int): The seed for the random number generator. Default is None.

Returns:

tuple: A tuple containing the einsum string and the shapes of the tensors in the MPS.

Example:

format_string, shapes = matrix_product_state(n=100, phys_dim_min=10, phys_dim_max=200, bond_dim=20, seed=0)

`function` `maxcut`

def maxcut(n=24, reg=3, p=3, seed=1)

Generates a Max-Cut quantum circuit using the Quantum Approximate Optimization Algorithm (QAOA).

Args:

n (int): Number of nodes in the graph (default: 24).
reg (int): Regularity of the graph (default: 3).
p (int): Number of QAOA steps (default: 3).
seed (int): Seed for random number generation (default: 1).

Returns:

tuple: A tuple containing the input string and the arrays of the quantum circuit.

Example:

format_string, arrays = maxcut(n=24, reg=3, p=3, seed=1)

`module` `generators.random`

`function` `regular`

def regular(n, reg, d_min=2, d_max=3, seed=None)

Create a random contraction equation that corresponds to a random regular graph.

The graph must not be connected and for large graphs it will very likely have several components

Args:

n (int): The number of terms.
reg (int): The degree of the graph.
d_min (int, optional): The minimum size of an index.
d_max (int, optional): The maximum size of an index.
seed (None or int, optional): Seed for networkx and np.random.default_rng for repeatability.

Returns:

Tuple[List[List[str]], List[str], List[Tuple[int]], Dict[str, int]]: The inputs, output, shapes, and size dictionary.

Example:

format_string, shapes = randreg_equation(n=100, reg=3, d_min=2, d_max=4, seed=None)

`function` `connected_hypernetwork`

def connected_hypernetwork(
    number_of_tensors: int,
    regularity: float,
    max_tensor_order: int = None,
    max_edge_order: int = 2,
    diagonals_in_hyper_edges: bool = False,
    number_of_output_indices: int = 0,
    max_output_index_order: int = 1,
    diagonals_in_output_indices: bool = False,
    number_of_self_edges: int = 0,
    max_self_edge_order: int = 2,
    number_of_single_summation_indices: int = 0,
    global_dim: bool = False,
    min_axis_size: int = 2,
    max_axis_size: int = 10,
    seed: Optional[int] = None,
    return_size_dict: bool = False
) → Union[Tuple[str, Collection[Tuple[int, ]], Dict[str, int]], Tuple[str, Collection[Tuple[int, ]]]]

Generate a random connected Hyper Tensor Network (HTN).

Returns an einsum expressions string representing the HTN, shapes of the tensors and optionally a dictionary containing the index sizes.

Args:

number_of_tensors (int): Number of tensors/arrays in the TN.
regularity (float): ‘Regularity’ of the TN. This determines how many indices/axes each tensor shares with others on average (not counting output indices, global dimensions, self edges and single summation indices).
max_tensor_order (int, optional): The maximum order (number of axes/dimensions) of the tensors. If None, use an upper bound calculated from other parameters.
max_edge_order (int, optional): The maximum order of hyperedges.
diagonals_in_hyper_edges (bool, optional): Whether diagonals can appear in hyper edges, e.g. in “aab,ac,ad -> bcd” a is a hyper edge with a diagonal in the first tensor.
number_of_output_indices (int, optional): Number of output indices/axes (i.e. the number of non-contracted indices) including global dimensions. Defaults to 0 if global_dim = False, i.e., a contraction resulting in a scalar, and to 1 if global_dim = True.
max_output_index_order (int, optional): Restricts the number of times the same output index can occur.
diagonals_in_output_indices (bool, optional): Whether diagonals can appear in output indices, e.g. in “aab,ac -> abc” a is an output index with a diagonal in the first tensor.
number_of_self_edges (int, optional): The number of self edges/traces (e.g. in “ab,bcdd->ac” d represents a self edge).
max_self_edge_order (int, optional): The maximum order of a self edge e.g. in “ab,bcddd->ac” the self edge represented by d has order 3.
number_of_single_summation_indices (int, optional): The number of indices that are not connected to any other tensors and do not show up in the ouput (e.g. in “ab,bc->c” a is a single summation index).
min_axis_size (int, optional): Minimum size of an axis/index (dimension) of the tensors.
max_axis_size (int, optional): Maximum size of an axis/index (dimension) of the tensors.
seed (int, optional): If not None, seed numpy’s random generator with this.
global_dim (bool, optional): Add a global, ‘broadcast’, dimension to every operand.
return_size_dict (bool, optional): Return the mapping of indices to sizes.

Returns:

Tuple[str, List[Tuple[int]], Optional[Dict[str, int]]]: The einsum expression string, the shapes of the tensors/arrays, and the dict of index sizes (only returned if return_size_dict=True).

Examples: ‘usual’ Tensor Hyper Networks

eq, shapes, size_dict = random_tensor_hyper_network(
    number_of_tensors=10,
    regularity=2.5,
    max_tensor_order=10,
    max_edge_order=5,
    number_of_output_indices=5,
    min_axis_size=2,
    max_axis_size=4,
    return_size_dict=True,
    seed=12345
)
# Then, eq, shapes, and size_dict are:
eq = 'bdca,abhcdg,cbmd,cfd,ed,e,figj,gl,h,nik->jnmkl'
shapes = [(2, 2, 2, 2), (2, 2, 4, 2, 2, 3), (2, 2, 4, 2), (2, 2, 2), (2, 2), (2,), (2, 4, 3, 3), (3, 2), (4,), (3, 4, 3)]
size_dict = {'a': 2, 'b': 2, 'c': 2, 'd': 2, 'e': 2, 'f': 2, 'g': 3, 'h': 4, 'i': 4, 'j': 3, 'k': 3, 'l': 2, 'm': 4, 'n': 3}

Tensor Hyper Networks with self edges (of higher order), single summation indices, output indices of higher order and a global dimension

eq, shapes = random_tensor_hyper_network(
    number_of_tensors=10,
    regularity=2.5,
    max_tensor_order=5,
    max_edge_order=6,
    number_of_output_indices=5,
    max_output_index_order=3,
    number_of_self_edges=4,
    max_self_edge_order=3,
    number_of_single_summation_indices=3,
    global_dim=True,
    min_axis_size=2,
    max_axis_size=4,
    seed=12345
)
# Then, eq and shapes are:
eq = 'cabxk,gkegax,wldxbrb,ctoxdfo,xvdlv,weehx,nfnkx,spgpixqu,xjimhm,ijx->uvwtx'
shapes = [(3, 2, 4, 3, 2), (2, 2, 3, 2, 2, 3), (4, 4, 3, 3, 4, 3, 4), (3, 4, 3, 3, 3, 3, 3), (3, 3, 3, 4, 3), (4, 3, 3, 2, 3), (4, 3, 4, 2, 3), (3, 3, 2, 3, 2, 3, 2, 2), (3, 4, 2, 2, 2, 2), (2, 4, 3)]

Tensor Hyper Networks as above but with diagonals in hyper edges and output indices

eq, shapes = random_tensor_hyper_network(
    number_of_tensors=10,
    regularity=3.0,
    max_tensor_order=10,
    max_edge_order=3,
    diagonals_in_hyper_edges=True,
    number_of_output_indices=5,
    max_output_index_order=3,
    diagonals_in_output_indices=True,
    number_of_self_edges=4,
    max_self_edge_order=3,
    number_of_single_summation_indices=3,
    global_dim=True,
    min_axis_size=2,
    max_axis_size=4,
    seed=12345
)
# Then, eq and shapes are:
eq = 'cabxk,gkegax,wldxbrb,ctoxdfo,xvdlv,weehx,nfnkx,spgpixqu,xjimhm,ijx->uvwtx'
shapes = [(3, 2, 4, 3, 2), (2, 2, 3, 2, 2, 3), (4, 4, 3, 3, 4, 3, 4), (3, 4, 3, 3, 3, 3, 3), (3, 3, 3, 4, 3), (4, 3, 3, 2, 3), (4, 3, 4, 2, 3), (3, 3, 2, 3, 2, 3, 2, 2), (3, 4, 2, 2, 2, 2), (2, 4, 3)]

`function` `connected_network`

def connected_network(
    number_of_tensors: int,
    regularity: float,
    number_of_output_indices: int = 0,
    min_axis_size: int = 2,
    max_axis_size: int = 10,
    seed: Optional[int] = None,
    global_dim: bool = False,
    return_size_dict: bool = False
) → Union[Tuple[str, Collection[Tuple[int, ]], Dict[str, int]], Tuple[str, Collection[Tuple[int, ]]]]

Generate a random connected Tensor Network (TN).

Args:

number_of_tensors (int): Number of tensors/arrays in the TN.
regularity (float): ‘Regularity’ of the TN. This determines how many indices/axes each tensor shares with others on average (not counting output indices and a global dimension).
number_of_output_indices (int, optional): Number of output indices/axes (i.e. the number of non-contracted indices) including the global dimension. Defaults to 0 in case of no global dimension, i.e., a contraction resulting in a scalar, and to 1 in case there is a global dimension.
min_axis_size (int, optional): Minimum size of an axis/index (dimension) of the tensors.
max_axis_size (int, optional): Maximum size of an axis/index (dimension) of the tensors.
seed (int, optional): If not None, seed numpy’s random generator with this.
global_dim (bool, optional): Add a global, ‘broadcast’, dimension to every operand.
return_size_dict (bool, optional): Return the mapping of indices to sizes.

Returns:

Tuple[str, List[Tuple[int]], Optional[Dict[str, int]]]: The einsum expression string, the shapes of the tensors/arrays, and the dict of index sizes (only returned if return_size_dict=True).

Example:

eq, shapes, size_dict = random_tensor_network(
   number_of_tensors = 10,
   regularity = 3.5,
   number_of_output_indices = 5,
   min_axis_size = 2,
   max_axis_size = 4,
   return_size_dict = True,
   global_dim = False,
   seed = 12345
)
# Then, eq, shapes, and size_dict are:
eq = 'gafoj,mpab,uhlbcdn,cqlipe,drstk,ve,fk,ongmq,hj,i->sturv'
shapes = [(3, 4, 4, 2, 3), (3, 2, 4, 2), (4, 4, 2, 2, 4, 2, 3), (4, 2, 2, 4, 2, 2), (2, 4, 3, 4, 4), (2, 2), (4, 4), (2, 3, 3, 3, 2), (4, 3), (4,)]
size_dict = {'a': 4, 'b': 2, 'c': 4, 'd': 2, 'e': 2, 'f': 4, 'g': 3, 'h': 4, 'i': 4, 'j': 3, 'k': 4, 'l': 2, 'm': 3, 'n': 3, 'o': 2, 'p': 2, 'q': 2, 'r': 4, 's': 3, 't': 4, 'u': 4, 'v': 2}

`module` `generators.structured`

`function` `generate_mcm`

def generate_mcm(
    num_matrices=10,
    min_dim=10,
    max_dim=1000,
    is_shuffle=False,
    seed=None
)

Generate a matrix chain multiplication problem.

Args:

num_matrices (int): The number of matrices in the chain (default: 10).
min_dim (int): The minimum dimension of each matrix (default: 10).
max_dim (int): The maximum dimension of each matrix (default: 1000).
is_shuffle (bool): Whether to shuffle the einsum string and shapes (default: False).
seed (int): The seed value for reproducibility (default: None).

Returns:

tuple: A tuple containing the einsum string and the shapes of the matrices.

Raises:

AssertionError: If the lists of einsum string and shapes have different sizes.

Example:

generate_mcm(num_matrices=10, min_dim=10, max_dim=1000, is_shuffle=True, seed=0)

`function` `tree`

def tree(n=100, d_min=4, d_max=12, n_outer=2, seed=1)

Create a random contraction equation that corresponds to a tree.

Args:

n (int): The number of tensors.
d_min (int, optional): The minimum size of an index.
d_max (int, optional): The maximum size of an index.
n_outer (int, optional): The number of outer indices.
seed (int, optional): Seed for generator.

Returns:

tuple: A tuple containing the contraction equation format string and the shapes of the tensors.

`function` `lattice`

def lattice(dims, cyclic=False, d_min=2, d_max=None, seed=None)

Create a random contraction equation that corresponds to a lattice.

Args:

dims (sequence of int): The size of each dimension, with the dimensionality being the length of the sequence.
cyclic (bool or sequence of bool, optional): Whether each dimension is cyclic or not. If a sequence, must be the same length as dims.
d_min (int, optional): The minimum size of an index.
d_max (int, optional): The maximum size of an index. If None, defaults to d_min, i.e. all indices are the same size.
seed (None or int, optional): Seed for random.Random for repeatability.

Returns:

tuple: A tuple containing the contraction equation format string and the shapes of the inputs.

Raises:

TypeError: If cyclic is a sequence but not the same length as dims.

Generators Reference

module generators

module generators.language_model

function p_first_and_last

function sliding_likelihood

module generators.quantum_computing

function matrix_product_state

function maxcut

module generators.random

function regular

function connected_hypernetwork

function connected_network

module generators.structured

function generate_mcm

function tree

function lattice

`module` `generators`

`module` `generators.language_model`

`function` `p_first_and_last`

`function` `sliding_likelihood`

`module` `generators.quantum_computing`

`function` `matrix_product_state`

`function` `maxcut`

`module` `generators.random`

`function` `regular`

`function` `connected_hypernetwork`

`function` `connected_network`

`module` `generators.structured`

`function` `generate_mcm`

`function` `tree`

`function` `lattice`