pympo package

Submodules

pympo.bipartite module

class pympo.bipartite.AssignManager(operator: SumOfProducts)[source]

Bases: object

Manages the assignment of operators in a bipartite graph structure.

Parameters:

operator (SumOfProducts) – The operator to be managed.

operator

The operator to be managed.

Type:

SumOfProducts

ndim

The number of dimensions of the operator.

Type:

int

nops

The number of operations in the operator.

Type:

int

W_assigns

The assignment matrix for the operators.

Type:

list[list[int]]

coef_site

The coefficient site for each operator.

Type:

list[int]

unique_ops

The unique operations for each dimension.

Type:

list[list[int]]

Wsym

The symbolic representation of the assignment matrix.

Type:

list[sympy.Matrix]

assign(keep_symbol: bool = False) → list[MutableDenseMatrix][source]

Assigns new values to the internal matrices and updates the symbolic representation.

Parameters:

keep_symbol (bool) – If True, keeps the symbolic representation during the update. Defaults to False.

Returns:

The updated list of symbolic matrices.

Return type:

list[sympy.Matrix]

numerical_mpo(dtype=<class 'numpy.complex128'>, subs: dict[~sympy.core.symbol.Symbol, int | float | complex] | None = None) → list[ndarray[tuple[int, ...], dtype[_ScalarType_co]]][source]

Generate a numerical Matrix Product Operator (MPO) representation.

Parameters:

  • dtype (numpy.dtype, optional) – The data type of the MPO elements. Defaults to np.complex128.

  • subs (dict[sympy.Symbol, int | float | complex] | None, optional) – A dictionary of substitutions for symbolic coefficients. Defaults to None.

Returns:

A list of numpy arrays representing the MPO.

Return type:

list[NDArray]

Raises:

ValueError – If the dtype is not supported or if a coefficient is not a number.

reset_Wsym() → list[MutableDenseMatrix][source]
reset_core(isite: int) → MutableDenseMatrix[source]
show_graph() → None[source]

Visualizes the bipartite graph using the provided operator, W_assigns, and coef_site.

This method calls the show_assigns function from the pympo.visualize module to display the graph representation of the bipartite structure.

Returns:

None

subs(subs: dict[~sympy.core.symbol.Symbol, int | float | complex], dtype=<class 'numpy.complex128'>) → None[source]

Substitutes the symbolic coefficients with numerical values. This method would be useful when time-dependent parameters are involved. In such case, one can substitute static parameters with numerical values in advance and only time-dependent parameters are left in the symbolic form.

pympo.bipartite.assign_core(*, min_vertex_cover: list[str], U: list[str], V: list[str], E: list[tuple[str, str]], operators: SumOfProducts, isite: int, W_assigns: list[list[int]], E_assigns: list[tuple[str, str]], coef_site: list[int], visualize: bool = True) → tuple[list[str], MutableDenseMatrix][source]

Assigns core vertices and updates the bipartite graph representation. Parameters: ———– min_vertex_cover : list[str]

The minimum vertex cover of the bipartite graph.

Ulist[str]

List of vertices in set U.

Vlist[str]

List of vertices in set V.

Elist[tuple[str, str]]

List of edges in the bipartite graph.

operatorsSumOfProducts

The operators to be assigned.

isiteint

The current site index.

W_assignslist[list[int]]

The assignments of W.

E_assignslist[tuple[str, str]]

The assignments of edges.

coef_sitelist[int]

The coefficient sites.

visualizebool, optional

Whether to visualize the bipartite graph and assignments (default is True).

Returns:

tuple[list[str], sympy.Matrix]

A tuple containing the updated list of vertices in U and the matrix Wi.

pympo.bipartite.get_UVE(operator: SumOfProducts, W_assigns: list[list[int]], isite: int, Unew: list[str] | None = None) → tuple[list[str], list[str], list[tuple[str, str]], list[tuple[str, str]]][source]

Extracts and returns the sets of U, V, and E symbols and their assignments from a given operator.

Parameters:

  • operator (SumOfProducts) – The operator containing the sum of products.

  • W_assigns (list[list[int]]) – A list of lists containing integer assignments for each operator.

  • isite (int) – The current site index.

  • Unew (list[str] | None, optional) – A list of new U symbols. Defaults to None.

Returns: tuple[list[str], list[str], list[tuple[str, str]], list[tuple[str, str]]]:

  • U: List of unique U symbols as strings.

  • V: List of unique V symbols as strings.

  • E: List of tuples representing edges between U and V symbols.

  • E_assigns: List of tuples representing the assignments of U and V symbols for each operator.

pympo.bipartite.get_bipartite(U: set[str] | list[str], V: set[str] | list[str], E: set[tuple[str, str]] | list[tuple[str, str]]) → Graph[source]

Create a bipartite graph from two sets/lists of nodes and a set/list of edges.

Parameters:

  • U (set[str] | list[str]) – A set or list of nodes for the first partition.

  • V (set[str] | list[str]) – A set or list of nodes for the second partition.

  • E (set[tuple[str, str]] | list[tuple[str, str]]) – A set or list of edges, where each edge is represented as a tuple of two nodes (one from U and one from V).

Returns:

A NetworkX graph object representing the bipartite graph.

Return type:

nx.Graph

pympo.bipartite.get_maximal_matching(G: Graph) → dict[str, str][source]

Compute the maximal matching for a bipartite graph. This function takes a bipartite graph G and returns a dictionary representing the maximal matching. The function ensures that the graph is bipartite and handles disconnected graphs by splitting them into connected components before computing the matching.

Parameters:

G (nx.Graph) – A NetworkX graph object representing a bipartite graph.

Returns:

A dictionary where keys and values are nodes in the graph, representing

the maximal matching pairs.

Return type:

dict[str, str]

Raises:

AssertionError – If the input graph G or any of its connected components is not bipartite.

pympo.bipartite.get_min_vertex_cover(G: Graph, max_matching: dict[str, str]) → list[str][source]
pympo.bipartite.is_vertex_cover(G: Graph, vertex_cover: list[str]) → bool[source]

pympo.config module

class pympo.config.Config[source]

Bases: object

backend: Literal['py', 'rs'] = 'rs'

pympo.operators module

class pympo.operators.OpProductSite(ops: list[OpSite])[source]

Bases: object

Represents a product of operators acting on multiple sites, such as z_i * z_j * z_k.

coef

Coefficient of the operator product.

Type:

int | float | complex | sympy.Basic

symbol

Symbolic representation of the operator product.

Type:

sympy.Basic

ops

List of operators in the product.

Type:

list[OpSite]

sites

List of site indices where the operators act.

Type:

list[int]

Product of operators acting on multiple sites like z_i * z_j * z_k

coef: int | float | complex | Basic
get_site_value(isite: int, n_basis: int, isdiag: bool) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]

Get the value of the operator acting on the site isite.

Parameters:

  • isite (int) – The site index.

  • n_basis (int) – The number of basis.

Returns:

The value of the operator acting on the site isite.

Return type:

NDArray

get_symbol_interval(start_site: int, end_site: int) → Basic[source]

Get the symbol of the operator acting on the sites between start_site and end_site.

When the operator is symbol = z_1 * z_6, - get_symbol_interval(0, 3) returns 1_0 * z_1 * 1_2, - get_symbol_interval(3, 8) returns 1_3 * 1_4 * 1_5 * z_6 * 1_7.

Parameters:

  • start_site (int) – The start site.

  • end_site (int) – The end site.

Returns:

The symbol of the operator acting on the sites between start_site and end_site.

Return type:

sympy.Basic

To Do:

  • Improve the performance of the function by memoization.

ops: list[OpSite]
replace(new_op: OpSite) → None[source]

Replace an existing operator in the list with a new operator.

Parameters:

new_op (OpSite) – The new operator to replace the existing one.

Raises:

AssertionError – If the site of the new operator is not found in the existing operators.

Modifies:

self.symbol: Updates the symbol by multiplying the symbols of all operators. self.ops: Replaces the operator at the matching site with the new operator.

sites: list[int]
symbol: Basic
class pympo.operators.OpSite(symbol: Basic | str, isite: int, *, value: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, isdiag: bool = False)[source]

Bases: object

Represents an operator acting on a specific site in a quantum system.

symbol

The symbolic representation of the operator.

Type:

sympy.Basic

isite

The site index on which the operator acts.

Type:

int

value

The numerical value of the operator, if available.

Type:

NDArray | None

isdiag

Indicates if the operator is diagonal.

Type:

bool

Operator z_i acting on site i.

isdiag: bool
isite: int
symbol: Basic
value: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None
class pympo.operators.SumOfProducts(ops: Sequence[OpProductSite | OpSite] = [])[source]

Bases: object

Sum of products of operators acting on multiple sites like z_i * z_j + z_k * z_l

Parameters:

ops (Sequence[OpProductSite | OpSite], optional) – List of operator products. Defaults to [].

coefs

Coefficients of the operator products.

Type:

list[int | float | complex | sympy.Basic]

ops

List of operator products.

Type:

list[OpProductSite]

symbols

List of symbolic representations of the operator products.

Type:

list[sympy.Basic]

coefs: list[int | float | complex | Basic]
get_unique_ops_site(i: int) → set[OpSite][source]
property isdiag_list: list[bool]
property nbasis_list: list[int]
property ndim: int
property nops: int
ops: list[OpProductSite]
simplify() → SumOfProducts[source]

Concatenate common operator such as q_i * a_j + q_i * a^dagger_j -> q_i * (a_j + a^dagger_j)

Note that the computational complexity is O(n^2) where n is the number of operators.

property symbol: Basic | int | float | complex
symbols: list[Basic]
to_mpo() → list[ndarray[tuple[int, ...], dtype[_ScalarType_co]]][source]
pympo.operators.get_eye_site(i: int, n_basis: int | None = None) → OpSite[source]

Create an identity operator site.

Parameters:

i (int): The index of the site. n_basis (int | None, optional): The number of basis states. If provided,

an array of ones with length n_basis is created. Defaults to None.

Returns:

OpSite: An operator site with the identity operator.

pympo.operators.omit_eye_site(latex_symbol: str) → str[source]
Parameters:

latex_symbol (str) – The latex symbol of the operator like $hat{1}_0hat{z}_1$.

Returns:

The latex symbol of the operator without

the identity operator like $hat{z}_1$.

Return type:

str

pympo.utils module

pympo.utils.export_itensor_hdf5(mpo: list[ndarray[tuple[int, ...], dtype[Any]]], filename: Path | str, name: str = 'H') → None[source]

EXPERIMENTAL and SUPPORT BOSON MPO ONLY

Parameters:

  • mpo (Mpo) – The MPO to export.

  • filename (Path | str) – The path to the .h5 file.

  • name (str) – The name of the MPO in the .h5 file.

One needs to prepare the hdf5 file in advance with ITensors.jl.

`julia using ITensors, ITensorMPS, HDF5 N = 6 sites = siteinds("Boson", N, dim=10) f = h5open("mpo.h5", "w") write(f, "H", randomMPO(sites)) close(f) `

Then, one can use pympo.utils.export_itensor_hdf5 to export the MPO.

`python export_itensor_hdf5(mpo, "mpo.h5", "H") `

Finally, one can use MPO in ITensor.jl.

`julia using ITensors, ITensorMPS, HDF5 f = h5open("mpo.h5", "r") H = read(f, "H") close(f) sites = [siteinds(H)[i][2] for i in 1:length(H)] `

Returns:

None

See also

pympo.utils.export_npz(mpo: list[ndarray[tuple[int, ...], dtype[Any]]], filename: Path | str) → None[source]

Export an MPO to a numpy .npz file.

Parameters:

  • mpo – The MPO to export.

  • filename – The path to the .npz file.

Returns:

None

pympo.utils.fill_diag(core: ndarray[tuple[int, ...], dtype[Any]]) → ndarray[tuple[int, ...], dtype[Any]][source]
pympo.utils.full_matrix(mpo: list[ndarray[tuple[int, ...], dtype[Any]]]) → ndarray[source]
pympo.utils.import_itensor_hdf5(filename: Path | str, name: str = 'H') → list[ndarray[tuple[int, ...], dtype[Any]]][source]

Import an MPO from a .h5 file exported by ITensor.jl HDF5 format.

Parameters:

  • filename (Path | str) – The path to the .h5 file.

  • name (str) – The name of the MPO in the .h5 file.

Returns:

The MPO.

One needs to prepare the hdf5 file in advance with ITensors.jl.

`julia using ITensors, ITensorMPS, HDF5 N = 6 sites = siteinds("Boson", N, dim=10) f = h5open("mpo.h5", "w") write(f, "H", randomMPO(sites)) close(f) `

Then, one can use pympo.utils.import_itensor_hdf5 to import the MPO.

`python mpo = import_itensor_hdf5("mpo.h5", "H") `

See also

pympo.utils.import_npz(filename: Path | str) → list[ndarray[tuple[int, ...], dtype[Any]]][source]

Import an MPO from a numpy .npz file exported by pympo.utils.export_npz.

Parameters:

filename – The path to the .npz file.

Returns:

The MPO.

pympo.utils.qr(mpo: list[ndarray[tuple[int, ...], dtype[Any]]]) → list[ndarray[tuple[int, ...], dtype[Any]]][source]
pympo.utils.sum_mpo(mpo1: list[ndarray[tuple[int, ...], dtype[Any]]], mpo2: list[ndarray[tuple[int, ...], dtype[Any]]]) → list[ndarray[tuple[int, ...], dtype[Any]]][source]
pympo.utils.svd(mpo: list[ndarray[tuple[int, ...], dtype[Any]]], eps: float, already_qr: bool = False) → list[ndarray[tuple[int, ...], dtype[Any]]][source]
pympo.utils.to_mps(tensor: ndarray) → list[ndarray[tuple[int, ...], dtype[Any]]][source]
pympo.utils.to_tensor_train(matrix_or_vector: ndarray, dims: list[int]) → list[ndarray[tuple[int, ...], dtype[Any]]][source]

pympo.visualize module

pympo.visualize.show_assigns(operators: SumOfProducts, W_assigns: list[list[int]], coef_site: list[int], scale: float = 0.8) → None[source]
pympo.visualize.show_bipartite(U: set[str] | list[str], V: set[str] | list[str], E: set[tuple[str, str]] | list[tuple[str, str]], retained_E: list[tuple[str, str]] | None = None) → tuple[Graph, dict[str, tuple[int, int]]][source]
pympo.visualize.show_maximal_matching(G: Graph, pos: dict[str, tuple[int, int]]) → dict[str, str][source]
pympo.visualize.show_min_vertex_cover(G: Graph, pos: dict[str, tuple[int, int]], max_matching: dict[str, str]) → list[str][source]

Module contents

class pympo.AssignManager(operator: SumOfProducts)[source]

Bases: object

Manages the assignment of operators in a bipartite graph structure.

Parameters:

operator (SumOfProducts) – The operator to be managed.

operator

The operator to be managed.

Type:

SumOfProducts

ndim

The number of dimensions of the operator.

Type:

int

nops

The number of operations in the operator.

Type:

int

W_assigns

The assignment matrix for the operators.

Type:

list[list[int]]

coef_site

The coefficient site for each operator.

Type:

list[int]

unique_ops

The unique operations for each dimension.

Type:

list[list[int]]

Wsym

The symbolic representation of the assignment matrix.

Type:

list[sympy.Matrix]

assign(keep_symbol: bool = False) → list[MutableDenseMatrix][source]

Assigns new values to the internal matrices and updates the symbolic representation.

Parameters:

keep_symbol (bool) – If True, keeps the symbolic representation during the update. Defaults to False.

Returns:

The updated list of symbolic matrices.

Return type:

list[sympy.Matrix]

numerical_mpo(dtype=<class 'numpy.complex128'>, subs: dict[~sympy.core.symbol.Symbol, int | float | complex] | None = None) → list[ndarray[tuple[int, ...], dtype[_ScalarType_co]]][source]

Generate a numerical Matrix Product Operator (MPO) representation.

Parameters:

  • dtype (numpy.dtype, optional) – The data type of the MPO elements. Defaults to np.complex128.

  • subs (dict[sympy.Symbol, int | float | complex] | None, optional) – A dictionary of substitutions for symbolic coefficients. Defaults to None.

Returns:

A list of numpy arrays representing the MPO.

Return type:

list[NDArray]

Raises:

ValueError – If the dtype is not supported or if a coefficient is not a number.

reset_Wsym() → list[MutableDenseMatrix][source]
reset_core(isite: int) → MutableDenseMatrix[source]
show_graph() → None[source]

Visualizes the bipartite graph using the provided operator, W_assigns, and coef_site.

This method calls the show_assigns function from the pympo.visualize module to display the graph representation of the bipartite structure.

Returns:

None

subs(subs: dict[~sympy.core.symbol.Symbol, int | float | complex], dtype=<class 'numpy.complex128'>) → None[source]

Substitutes the symbolic coefficients with numerical values. This method would be useful when time-dependent parameters are involved. In such case, one can substitute static parameters with numerical values in advance and only time-dependent parameters are left in the symbolic form.

class pympo.OpSite(symbol: Basic | str, isite: int, *, value: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, isdiag: bool = False)[source]

Bases: object

Represents an operator acting on a specific site in a quantum system.

symbol

The symbolic representation of the operator.

Type:

sympy.Basic

isite

The site index on which the operator acts.

Type:

int

value

The numerical value of the operator, if available.

Type:

NDArray | None

isdiag

Indicates if the operator is diagonal.

Type:

bool

Operator z_i acting on site i.

isdiag: bool
isite: int
symbol: Basic
value: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None
class pympo.SumOfProducts(ops: Sequence[OpProductSite | OpSite] = [])[source]

Bases: object

Sum of products of operators acting on multiple sites like z_i * z_j + z_k * z_l

Parameters:

ops (Sequence[OpProductSite | OpSite], optional) – List of operator products. Defaults to [].

coefs

Coefficients of the operator products.

Type:

list[int | float | complex | sympy.Basic]

ops

List of operator products.

Type:

list[OpProductSite]

symbols

List of symbolic representations of the operator products.

Type:

list[sympy.Basic]

coefs: list[int | float | complex | Basic]
get_unique_ops_site(i: int) → set[OpSite][source]
property isdiag_list: list[bool]
property nbasis_list: list[int]
property ndim: int
property nops: int
ops: list[OpProductSite]
simplify() → SumOfProducts[source]

Concatenate common operator such as q_i * a_j + q_i * a^dagger_j -> q_i * (a_j + a^dagger_j)

Note that the computational complexity is O(n^2) where n is the number of operators.

property symbol: Basic | int | float | complex
symbols: list[Basic]
to_mpo() → list[ndarray[tuple[int, ...], dtype[_ScalarType_co]]][source]
pympo.assign_core(*, min_vertex_cover: list[str], U: list[str], V: list[str], E: list[tuple[str, str]], operators: SumOfProducts, isite: int, W_assigns: list[list[int]], E_assigns: list[tuple[str, str]], coef_site: list[int], visualize: bool = True) → tuple[list[str], MutableDenseMatrix][source]

Assigns core vertices and updates the bipartite graph representation. Parameters: ———– min_vertex_cover : list[str]

The minimum vertex cover of the bipartite graph.

Ulist[str]

List of vertices in set U.

Vlist[str]

List of vertices in set V.

Elist[tuple[str, str]]

List of edges in the bipartite graph.

operatorsSumOfProducts

The operators to be assigned.

isiteint

The current site index.

W_assignslist[list[int]]

The assignments of W.

E_assignslist[tuple[str, str]]

The assignments of edges.

coef_sitelist[int]

The coefficient sites.

visualizebool, optional

Whether to visualize the bipartite graph and assignments (default is True).

Returns:

tuple[list[str], sympy.Matrix]

A tuple containing the updated list of vertices in U and the matrix Wi.

pympo.get_UVE(operator: SumOfProducts, W_assigns: list[list[int]], isite: int, Unew: list[str] | None = None) → tuple[list[str], list[str], list[tuple[str, str]], list[tuple[str, str]]][source]

Extracts and returns the sets of U, V, and E symbols and their assignments from a given operator.

Parameters:

  • operator (SumOfProducts) – The operator containing the sum of products.

  • W_assigns (list[list[int]]) – A list of lists containing integer assignments for each operator.

  • isite (int) – The current site index.

  • Unew (list[str] | None, optional) – A list of new U symbols. Defaults to None.

Returns: tuple[list[str], list[str], list[tuple[str, str]], list[tuple[str, str]]]:

  • U: List of unique U symbols as strings.

  • V: List of unique V symbols as strings.

  • E: List of tuples representing edges between U and V symbols.

  • E_assigns: List of tuples representing the assignments of U and V symbols for each operator.

pympo.get_bipartite(U: set[str] | list[str], V: set[str] | list[str], E: set[tuple[str, str]] | list[tuple[str, str]]) → Graph[source]

Create a bipartite graph from two sets/lists of nodes and a set/list of edges.

Parameters:

  • U (set[str] | list[str]) – A set or list of nodes for the first partition.

  • V (set[str] | list[str]) – A set or list of nodes for the second partition.

  • E (set[tuple[str, str]] | list[tuple[str, str]]) – A set or list of edges, where each edge is represented as a tuple of two nodes (one from U and one from V).

Returns:

A NetworkX graph object representing the bipartite graph.

Return type:

nx.Graph

pympo.get_eye_site(i: int, n_basis: int | None = None) → OpSite[source]

Create an identity operator site.

Parameters:

i (int): The index of the site. n_basis (int | None, optional): The number of basis states. If provided,

an array of ones with length n_basis is created. Defaults to None.

Returns:

OpSite: An operator site with the identity operator.

pympo.get_maximal_matching(G: Graph) → dict[str, str][source]

Compute the maximal matching for a bipartite graph. This function takes a bipartite graph G and returns a dictionary representing the maximal matching. The function ensures that the graph is bipartite and handles disconnected graphs by splitting them into connected components before computing the matching.

Parameters:

G (nx.Graph) – A NetworkX graph object representing a bipartite graph.

Returns:

A dictionary where keys and values are nodes in the graph, representing

the maximal matching pairs.

Return type:

dict[str, str]

Raises:

AssertionError – If the input graph G or any of its connected components is not bipartite.

pympo.get_min_vertex_cover(G: Graph, max_matching: dict[str, str]) → list[str][source]
pympo.get_min_vertex_cover2(u, e, max_matching)
pympo.show_assigns(operators: SumOfProducts, W_assigns: list[list[int]], coef_site: list[int], scale: float = 0.8) → None[source]
pympo.show_bipartite(U: set[str] | list[str], V: set[str] | list[str], E: set[tuple[str, str]] | list[tuple[str, str]], retained_E: list[tuple[str, str]] | None = None) → tuple[Graph, dict[str, tuple[int, int]]][source]
pympo.show_maximal_matching(G: Graph, pos: dict[str, tuple[int, int]]) → dict[str, str][source]
pympo.show_min_vertex_cover(G: Graph, pos: dict[str, tuple[int, int]], max_matching: dict[str, str]) → list[str][source]