# quimb.experimental.operatorbuilder¶

## Classes¶

 `HilbertSpace` Take a set of 'sites' (any sequence of sortable, hashable objects), and `SparseOperatorBuilder` Object for building operators with sparse structure. Specifically,

## Functions¶

 `fermi_hubbard_from_edges`(edges[, t, U, mu]) `fermi_hubbard_spinless_from_edges`(edges[, t, mu]) `heisenberg_from_edges`(edges[, j, b, hilbert_space]) Create a Heisenberg Hamiltonian on the graph defined by `edges`.

## Package Contents¶

quimb.experimental.operatorbuilder.fermi_hubbard_from_edges(edges, t=1.0, U=1.0, mu=0.0)
quimb.experimental.operatorbuilder.fermi_hubbard_spinless_from_edges(edges, t=1.0, mu=0.0)
quimb.experimental.operatorbuilder.heisenberg_from_edges(edges, j=1.0, b=0.0, hilbert_space=None)

Create a Heisenberg Hamiltonian on the graph defined by `edges`.

Parameters:
• edges (Iterable[tuple[hashable, hashable]]) – The edges, as pairs of hashable ‘sites’, that define the graph. Multiple edges are allowed, and will be treated as a single edge.

• j (float or tuple[float, float, float], optional) – The Heisenberg exchange coupling constant(s). If a single float is given, it is used for all three terms. If a tuple of three floats is given, they are used for the xx, yy, and zz terms respectively. Note that positive values of `j` correspond to antiferromagnetic coupling.

• b (float or tuple[float, float, float], optional) – The magnetic field strength(s). If a single float is given, it is used taken as a z-field. If a tuple of three floats is given, they are used for the x, y, and z fields respectively.

• hilbert_space (HilbertSpace, optional) – The Hilbert space to use. If not given, one will be constructed automatically from the edges.

Returns:

H

Return type:

SparseOperatorBuilder

class quimb.experimental.operatorbuilder.HilbertSpace(sites, order=None)

Take a set of ‘sites’ (any sequence of sortable, hashable objects), and map this into a ‘register’ or linearly indexed range, optionally using a particular ordering. One can then calculate the size of the Hilbert space, including number conserving subspaces, and get a compact ‘bitbasis’ with which to construct sparse operators.

Parameters:
• sites (int or sequence of hashable objects) – The sites to map into a linear register. If an integer, simply use `range(sites)`.

• order (callable or sequence of hashable objects, optional) – If provided, use this to order the sites. If a callable, it should be a sorting key. If a sequence, it should be a permutation of the sites, and `key=order.index` will be used.

set_ordering(order=None)
classmethod from_edges(edges, order=None)

Construct a HilbertSpace from a set of edges, which are pairs of sites.

site_to_reg(site)

Convert a site to a linear register index.

reg_to_site(reg)

Convert a linear register index back to a site.

has_site(site)

Check if this HilbertSpace contains a given site.

config_to_bit(config)

Encode a ‘configuration’ as a bit.

Parameters:

config (dict[hashable, int]) – A dictionary mapping sites to their occupation number / spin.

Returns:

bit – The bit corresponding to this configuration.

Return type:

int

config_to_flatconfig(config)

Turn a configuration into a flat configuration, assuming the order given by this `HilbertSpace`.

Parameters:

config (dict[hashable, int]) – A dictionary mapping sites to their occupation number / spin.

Returns:

flatconfig – A flat configuration, with the occupation number of each site in the order given by this `HilbertSpace`.

Return type:

ndarray[uint8]

bit_to_config(bit)

Decode a bit to a configuration.

Parameters:

bit (int) – The bit to decode.

Returns:

config – A dictionary mapping sites to their occupation number / spin.

Return type:

dict[hashable, int]

flatconfig_to_config(flatconfig)

Turn a flat configuration into a configuration, assuming the order given by this `HilbertSpace`.

Parameters:

flatconfig (ndarray[uint8]) – A flat configuration, with the occupation number of each site in the order given by this `HilbertSpace`.

Returns:

config – A dictionary mapping sites to their occupation number / spin.

Return type:

dict[hashable, int]

rand_config(k=None)

Get a random configuration, optionally requiring it has `k` bits set.

property sites
The ordered tuple of all sites in the Hilbert space.
property nsites
The total number of sites in the Hilbert space.
get_size(*k)

Compute the size of this Hilbert space, optionally taking into account number / z-spin conservation.

Parameters:

k (int or tuple of (int, int)) –

If provided, compute the size of number conserving subspace(s):

```- If a single int, compute the size of the subspace with
``k`` particles / up states: ``comb(nsites, k)``.
- If a tuple of (int, int), compute the size of the subspace
of the product of spaces where each pair (n, k) corresponds
to n sites with k particles / up states. The sum of every n
should equal ``nsites``.
```

get_bitbasis(*k, dtype=np.int64)

Get a basis for the Hilbert space, in terms of an integer bitarray, optionally taking into account number / z-spin conservation.

Parameters:
• k (int or tuple of (int, int)) –

If provided, get the basis for a number conserving subspace(s):

```- If a single int, compute the size of the subspace with
``k`` particles / up states: ``comb(nsites, k)``.
- If a tuple of (int, int), compute the size of the subspace
of the product of spaces where each pair (n, k) corresponds
to n sites with k particles / up states. The sum of every n
should equal ``nsites``.
```

• dtype (np.dtype, optional) – The dtype of the bitarray, should be an integer type with at least `nsites` bits.

Returns:

bits – The basis, each integer element being a binary representation of a configuration.

Return type:

numpy.ndarray

__repr__()

Return repr(self).

class quimb.experimental.operatorbuilder.SparseOperatorBuilder(terms=(), hilbert_space=None)

Object for building operators with sparse structure. Specifically, a sum of terms, where each term is a product of operators, where each of these local operators acts on a single site and has at most one entry per row.

Parameters:
• terms (sequence, optional) – The terms to initialize the builder with. `add_term` is simply called on each of these.

• hilbert_space (HilbertSpace) – The Hilbert space to build the operator in. If this is not supplied then a minimal Hilbert space will be constructed from the sites used, when required.

property sites_used
A tuple of the sorted coordinates/sites seen so far.
property nsites
The total number of coordinates/sites seen so far.
property terms
A tuple of the simplified terms seen so far.
property nterms
The total number of terms seen so far.
property locality
The locality of the operator, the maximum support of any term.
property hilbert_space
The Hilbert space of the operator. Created from the sites seen
so far if not supplied at construction.
property coupling_map
site_to_reg(site)

Get the register / linear index of coordinate `site`.

reg_to_site(reg)

Get the site of register / linear index `reg`.

Add a term to the operator.

Parameters:
• coeff (float, optional) – The overall coefficient of the term.

• ops (sequence of tuple[str, hashable]) –

The operators of the term, together with the sites they act on. Each term should be a pair of `(operator, site)`, where `operator` can be:

• `'x'`, `'y'`, `'z'`: Pauli matrices

• `'sx'`, `'sy'`, `'sz'`: spin operators (i.e. scaled Pauli matrices)

• `'+'`, `'-'`: creation/annihilation operators

• `'n'`, `'sn'`, or `'h'`: number, symmetric number (n - 1/2) and hole (1 - n) operators

And `site` is a hashable object that represents the site that the operator acts on.

jordan_wigner_transform()

Transform the terms in this operator by pre-prending pauli Z strings to all creation and annihilation operators, and then simplifying the resulting terms.

build_coo_data(*k, parallel=False)

Build the raw data for a sparse matrix in COO format. Optionally in a reduced k basis and in parallel.

Parameters:
• k (int or tuple of (int, int)) –

If provided, get the basis for a number conserving subspace(s):

```- If a single int, compute the size of the subspace with
``k`` particles / up states: ``comb(nsites, k)``.
- If a tuple of (int, int), compute the size of the subspace
of the product of spaces where each pair (n, k) corresponds
to n sites with k particles / up states. The sum of every n
should equal ``nsites``.
```

• parallel (bool, optional) – Whether to build the matrix in parallel (multi-threaded).

Returns:

• coo (array) – The data entries for the sparse matrix in COO format.

• cis (array) – The row indices for the sparse matrix in COO format.

• cjs (array) – The column indices for the sparse matrix in COO format.

• N (int) – The total number of basis states.

build_sparse_matrix(*k, stype='csr', parallel=False)

Build a sparse matrix in the given format. Optionally in a reduced k basis and in parallel.

Parameters:
• k (int or tuple of (int, int)) –

If provided, get the basis for a number conserving subspace(s):

```- If a single int, compute the size of the subspace with
``k`` particles / up states: ``comb(nsites, k)``.
- If a tuple of (int, int), compute the size of the subspace
of the product of spaces where each pair (n, k) corresponds
to n sites with k particles / up states. The sum of every n
should equal ``nsites``.
```

• parallel (bool, optional) – Whether to build the matrix in parallel (multi-threaded).

Return type:

scipy.sparse matrix

build_dense()

Get the dense (numpy.ndarray) matrix representation of this operator.

build_local_terms()

Get a dictionary of local terms, where each key is a sorted tuple of sites, and each value is the local matrix representation of the operator on those sites. For use with e.g. tensor network algorithms.

Note terms acting on the same sites are summed together and the size of each local matrix is exponential in the locality of that term.

Returns:

Hk – The local terms.

Return type:

dict[tuple[hashable], numpy.ndarray]

config_coupling(config)

Get a list of other configurations coupled to `config` by this operator, and the corresponding coupling coefficients. This is for use with VMC for example.

Parameters:

config (dict[site, int]) – The configuration to get the coupling for.

Returns:

• coupled_configs (list[dict[site, int]]) – Each distinct configuration coupled to `config`.

• coeffs (list[float]) – The corresponding coupling coefficients.

show(filler='.')

Print an ascii representation of the terms in this operator.

build_state_machine_greedy()
draw_state_machine(method='greedy', figsize='auto')
build_mpo(method='greedy', **mpo_opts)
__repr__()

Return repr(self).