mdopt.optimiser.utils module#

This module contains different combinatorial optimisation utilities.

First, we define the tensors which represent logical operation. We use the following tensors: IDENTITY, COPY, XOR, SWAP.

According to our convention, each tensor has legs (vL, vR, pU, pD), where v stands for “virtual”, p – for “physical”, and L, R, U, D stand for “left”, “right”, “up”, “down”.

class mdopt.optimiser.utils.ConstraintString(constraints: List[ndarray], sites: List[List[int]])#

Class for storing a string of logical constraints in the Matrix Product Operator format. Logical constraints are to be passed in the form of 4-dimensional MPO tensors.

constraints#

A list of logical constraints of which the string consists.

Type:

List[np.ndarray]

sites#

Each list inside corresponds to a constraint from the constraints list, and contains the sites to which each constraint is applied. For example, [[3, 5], [2, 4, 6], …] means applying constraints[0] to sites 3 and 5, constraints[1] to sites 2, 4, 6 etc.

Type:

List[List[int]]

Raises:

ValueError –

  • Empty list of constraints. - Empty list of sites. - The sites list is longer than the constraints list. - Non-unique sites in the sites list. - The list of sites has gaps, indicating breaks in the constraints string.

flat(sort: bool = False) → List[int]#

Returns a flattened list of sites.

mpo() → List[ndarray]#

Returns an MPO list aligned to the span of this constraint string.

span() → int#

Returns the span (length) of the constraint string.

mdopt.optimiser.utils.apply_constraints(mps: CanonicalMPS, strings: List[List[int]], logical_tensors: List[ndarray], chi_max: int = 10000, cut: float = 1e-17, renormalise: bool = True, strategy: str = 'Naive', silent: bool = False, dense: bool = False, return_entropies_and_bond_dims: bool = False) → CanonicalMPS | ndarray#

This function applies logical constraints to an MPS.

Parameters:

  • mps (CanonicalMPS) – The MPS to which the logical constraints are being applied.

  • strings (List[List[int]]) – The list of arguments for ConstraintString.

  • logical_tensors (List[np.ndarray]) – List of logical tensors for ConstraintString.

  • chi_max (int) – Maximum bond dimension to keep in the contractor.

  • cut (float) – The lower boundary of the spectrum in the contractor. All singular values below this value are truncated.

  • renormalise (bool) – Whether to renormalise the orthogonality centre after each constraint application.

  • result_to_explicit (bool) – Whether to transform the resulting MPS into the Explicit form.

  • strategy (str) – The contractor strategy. Available options are “Optimised” and “Naive”.

  • silent (bool) – Whether to show the progress bar or not.

  • return_entropies_and_bond_dims (bool) – Whether to return the entanglement entropies and bond dimensions at each bond.

  • dense (bool) – Whether to perform the calculations in the dense form. To be used only for small systems (<= 20 sites).

Returns:

  • mps (CanonicalMPS) – The resulting MPS.

  • entropies, bond_dims (List[float], List[int]) – The list of entanglement entropies at each bond. Returned only if return_entropies_and_bond_dims is set to True.

mdopt.optimiser.utils.parity(bitstring: str, indices: list[int]) → int#

Returns the parity of the bits at the given indices in the bitstring.

mdopt.optimiser.utils.random_constraints(num_bits: int, constraint_size: int, rng: Generator) → dict#

Generate random XOR and SWAP site constraints for a bitstring.

Parameters:

  • num_bits (int) – The total number of bits in the bitstring. Must be at least 3.

  • constraint_size (int) – The maximum possible length of the constraint, i.e., the number of XOR sites.

  • rng (numpy.random.Generator) – A NumPy random number generator instance for reproducibility.

Returns:

A dictionary containing the following keys:

  • ’xor_left_sites’: list of int

    List with one index selected as the left XOR site.

  • ’xor_bulk_sites’: list of int

    List of indices selected as bulk XOR sites, between left and right.

  • ’xor_right_sites’: list of int

    List with one index selected as the right XOR site.

  • ’swap_sites’: list of int

    List of indices between left and right XOR sites, excluding the bulk XOR sites.

  • ’all_constrained_bits’: list of int

    Sorted list of all selected XOR site indices (left, bulk, right).

Return type:

dict

Raises:

ValueError – If num_bits is less than 3.