nitrogen.tensor

Tensor networks, contractions, and operators.

class nitrogen.tensor.ConfigurationOperator(shape, dtype=<class 'numpy.float64'>)

Bases: object

Base class for matrix elements in a configuration representation.

shape

The one-sided operator shape

Type

tuple

dtype

The operator data type.

Type

data-type

block(bra_configs, ket_configs=None)

Calculate a block of the operator matrix.

Parameters

  • bra_configs (array_like) – A list of left-hand-side configurations.

  • ket_configs (array_like or {'symmetric', 'diagonal'}, optional) – A list of right-hand-side configurations. If None, then the diagonal block given by bra_configs will be calculated.

class nitrogen.tensor.DirectProductOperator(factors, labels, shape)

Bases: nitrogen.tensor.TensorOperator

Direct product tensor operator, with implicit identities for unspecified index-pairs.

shape

The one-sided shape

Type

tuple

factors

The non-identity tensor factors

Type

list

labels

The one-sided labels for each factor

Type

list of lists

A direct product of tensors

Parameters

  • factors (list of Tensors) – The factors.

  • labels (list of lists) – Each element is a list with the negative integer labels that the corresponding element represents.

  • shape (tuple) – The operator shape. Axes that are not referred to in labels will implicitly have an Identity tied to them with the correct dimension as given by shape.

Notes

Each label is used once, e.g. [-1,-3] means the corresponding tensor has shape (n,n,m,m) where n is the dimension of label -1 and m is the dimension of label -3.

class nitrogen.tensor.DirectSumConfigurationOperator(*args)

Bases: nitrogen.tensor.ConfigurationOperator

A sum of configuration operators

ConfigurationOperator sum

class nitrogen.tensor.DirectSumOperator(*args)

Bases: nitrogen.tensor.TensorOperator

A tensor operator equal to the simple sum of other TensorOperator objects.

TensorOperator sum

asConfigurationOperator(config_funs, labels=None)

return a ConfigurationOperator object wrapping this TensorOperator using the supplied basis functions

class nitrogen.tensor.QuadratureConfigurationOperator(F, left, right, config_funs, labels=None)

Bases: nitrogen.tensor.ConfigurationOperator

Configuration operator map of a QuadruatureOperator tensor operator

class nitrogen.tensor.QuadratureOperator(F, left, right)

Bases: nitrogen.tensor.TensorOperator

A full rank quadrature operator

Parameters

  • F (ndarray) – The values of a quadrature grid.

  • left (list of ndarray) – The FBR-to-quadrature transformation operators of the left indices

  • right (list of ndarray) – The FBR-to-quadrature transformation operators of the right indices

Notes

Entries of None in left or right are interpreted as identity.

asConfigurationOperator(config_funs, labels=None)

return a ConfigurationOperator object wrapping this TensorOperator using the supplied basis functions

class nitrogen.tensor.SingleIndexOperator(A, index, shape)

Bases: nitrogen.tensor.ConfigurationOperator

A 1-group operator in configuration representation. The representation is assumed to be separably orthonormal in each configuration index

Parameters

  • A (ndarray) – A square matrix representing the 1-body operator for axis index of the configuratoin representation.

  • index (int) – The 1-body index.

  • shape (tuple) – The full configuration space shape

class nitrogen.tensor.Tensor(v, mask=None)

Bases: object

A general tensor array class, supporting diagonal structure.

\[V_{ijk\cdots} = v_{abc\cdots} \delta_{a\cdots} \delta_{b\cdots} \cdots\]
v

The core array. (The non-zero values.)

Type

ndarray

mask

The apparent-to-core index map.

Type

ndarray

shape

The apparent tensor shape.

Type

tuple

ndim

The order of the tensor. (The number of apparent indices.)

Type

int

dtype

The data type of the core array.

Type

data-type

Parameters

  • v (ndarray) – The core array for the tensor.

  • mask (array_like) – The apparent indices of the tensor. Each axis (0, 1, …) of the core array v must be included at least once. Repeated indices form a diagonal set.

array()

Calculate the full array, realizing implicit diagonals

Returns

The full apparent tensor.

Return type

ndarray

copy()

Create a copy of this Tensor

Returns

A copy of this Tensor. Both the core and mask ndarrays are copied.

Return type

Tensor

class nitrogen.tensor.TensorNetwork(tensors, labels)

Bases: object

A single term tensor network

tensors

A list of Tensor or ndarray objects.

Type

list

labels

A list of lists containing the index labels of each element of tensors.

Type

list

Create a TensorNetwork

Parameters

  • tensors (list) – A list of Tensor or ndarray objects.

  • labels (list) – A list of lists containing the index labels of each element of tensors.

con(sequence=None, forder=None, check=True)

Contract this network with con().

Parameters

  • sequence (optional) – See con().

  • forder (optional) – See con().

  • check (optional) – See con().

Returns

Return type

Tensor

class nitrogen.tensor.TensorOperator(shape, dtype=<class 'numpy.float64'>)

Bases: object

Base class for tensor operators.

shape

The one-sided shape of the tensor operator.

Type

tuple

dtype

The data type.

Type

data-type

asConfigurationOperator(config_funs, labels=None)

return a ConfigurationOperator object wrapping this TensorOperator using the supplied basis functions

contract(network=None)

Contract the tensor operator with a TensorNetwork.

Parameters

network (TensorNetwork, optional) – A tensor network to contract with the operator. If None, then no indices will be contracted.

Returns

The contracted result

Return type

ndarray

Notes

The tensor operator has external indices labeled (-1, -3, -5, …) on the left side with dimensions given by shape and (-2, -4, -6, …) on the right side.

The input tensor network will be contracted with the operator based on the negative integer elements in its respective labels attributes. Missing negative labels in the network will not be contracted.

class nitrogen.tensor.TensorToConfigurationOperator(T, config_funs, labels=None)

Bases: nitrogen.tensor.ConfigurationOperator

A generic ConfigurationOperator wrapper for TensorOperator’s with a given configuration basis set.

configs_funs

The configuration basis functions

Type

list of ndarrays

nC

The number of configuration indices

Type

integer

labels

The TensorOperator index labels for each configuration group

Type

list of list

T

The TensorOperator being wrapped.

Type

TensorOperator

Parameters

  • T (TensorOperator) – The operator to be recast.

  • config_funs (list of ndarrays) – config_funs[i][j] is the basis-function array for the jth function of the ith group.

  • labels (list of list, optional) – The index labels of each basis function factor. If None (default), this is assumed to be [[0], [1], [2], ...].

nitrogen.tensor.check_labels(tensors, labels, sequence, forder)

Check labels, sequence and forder for a given tensor list

nitrogen.tensor.con(tensors, labels, sequence=None, forder=None, check=True)

An ncon style contraction function. See [NCON].

Parameters

  • tensors (list of Tensors or ndarrays) – The tensors forming the network.

  • labels (list of lists of index labels) – The axis of each tensor is labeled with an integer index. Positive labels occur in pairs and are contracted. Negative labels are external legs and uncontracted.

  • sequence (list, optional) – The contraction sequence of the positive index labels. The default is by ascending order.

  • forder (list, optional) – The order of the uncontracted indices in the final result tensor. By default, this is in negative ascending order (-1, -2, …)

  • check (boolean, optional) – Perform checks on inputs. The default is True.

Returns

Result

Return type

Tensor

Notes

Contraction is not necessarily performed strictly in the order given by sequence. When contracting some index labeled by an element of sequence, a look-ahead is performed for all later elements in sequence which have the same tensor connectivity. These contractions are performed simultaneously and removed from the sequence list.

References

NCON

R. N. C. Pfeifer, G. Evenbly, S. Singh, and G. Vidal. “NCON: a tensor network contractor for MATLAB”. arXiv:1402.0939. (2015) https://arxiv.org/abs/1402.0939

nitrogen.tensor.diagonal(a)

Return the Tensor with a as its simple diagonal.

\[A_{ii'jj'\cdots} = a_{ij\cdots}\delta_{ii'}\delta_{jj'} \cdots\]
Parameters

a (ndarray) – The core array

Returns

A – A diagonal tensor with a along its generalized diagonal.

Return type

Tensor

nitrogen.tensor.eyeN(d, N, dtype=<class 'numpy.float64'>)
Construct a d x d x … (N times)

identity tensor

Parameters

  • d (int) – The dimension of each index

  • N (int) – The number of indices.

  • dtype (data-type, optional) – The data-type. The default is np.float64.

Returns

I – The N-dimensional identity tensors

Return type

ndarray

Notes

If N == 1, then a ‘ones’ array of length d is returned.

nitrogen.tensor.interleaveNetworks(net1, net2)

Merge two TensorNetworks by interleaving their external indices.

The external indices of net1 are mapped from [-1, -2, -3, … ] to [-1, -3, -5, …]. The external indices of net2 are mapped from [-1, -2, -3, … ] to [-2, -4, -6, …].

Parameters
Returns

Return type

TensorNetwork

nitrogen.tensor.label2grppos(labels)

Convert a list of lists of labels to a group/position map

nitrogen.tensor.mask2train(mask)

Calculate the delta train core and apparent indices from a mask

Parameters

mask (ndarray) – Tensor mask

Returns

train – A list of delta factors with core and apparent indices grouped separately.

Return type

nested list

nitrogen.tensor.offsetPostiveLabels(labels, offset)

Add an offset to all positive labels

Parameters

  • labels (list of list) – A nested list of labels

  • offset (integer) – The positive offset

Returns

The new nested list

Return type

list

nitrogen.tensor.reduceTrain(mask, pairs)

Compute a reduced train of delta factors by contracting pairs of indices.

Parameters

mask (ndarray) – Mask array

Returns

  • train (list) – Train of new delta factors

  • app2app (ndarray) – Map from left-over old apparent indices to new apparent indices

nitrogen.tensor.replaceLabel(labels, oldLabel, newLabel)

Replace an index label in a nested list of lists.

Parameters

  • labels (list of list) – A nested list of labels

  • oldLabel (integer) – The old label

  • newLabel (integer) – The new label

Returns

The new nested list

Return type

list

nitrogen.tensor.sorted_neg(labels)

Return unique negative labels in descending order

nitrogen.tensor.sorted_pos(labels)

Return unique positive labels in ascending order

nitrogen.tensor.tensorContract(A, B, axes)

Contract diagonal tensors

Parameters

  • A (Tensor or ndarray) – Tensor to be contracted.

  • B (Tensor or ndarray) – Tensor to be contracted.

  • axes (list of (2,)) – Apparent axis pairs to be contracted. The first element of each pair is an axis of A. The second element is an axis of B.

Returns

C – The result

Return type

Tensor

nitrogen.tensor.tensorDirectProduct(tensors, force_copy=False)

Direct product of multiple tensors. This may share references with input tensors unless force_copy is True

nitrogen.tensor.tensorPermute(A, perm, copy_core=False)

Permute Tensor axes

nitrogen.tensor.tensorTrace(A, axes)

Perform a multi-index trace over sets of pairs of indices.

Parameters

  • A (Tensor or ndarray) – The input tensor.

  • axes (list of (2,)) – The axis pairs to trace over. Axes must all be unique and be between 0 and A.ndim-1.

Returns

B – The result

Return type

Tensor

nitrogen.tensor.train2subs_mask(train, app2app, nc_old, na_new)

Compute the einsum subscripts for core processing as well as the new Tensor mask given a reduced, contracted train of delta factors.

Parameters

  • train (list) – the reduced train, as returned by reduceTrain()

  • app2app (ndarray) – the apparent index map, as returned by reduceTrain()

  • nc_old (int) – The original number of core indices

  • na_new (int) – The new number of apparent indices

Returns

  • core_sub, out_sub (list) – einsum subscripts for core processing

  • new_mask (list) – New Tensor mask.