qalgebra.utils.indices module

Summary

Classes:

FockIndex	Symbolic index labeling a basis state in a LocalSpace
FockLabel	Symbolic label that evaluates to the label of a basis state
IdxSym	Index symbol in an indexed sum or product.
IndexOverFockSpace	Index range over the integer indices of a LocalSpace basis
IndexOverList	Index over a list of explicit values
IndexOverRange	Index over the inclusive range between two integers
IndexRangeBase	Base class for index ranges
IntIndex	A symbolic label that evaluates to an integer.
SpinIndex	Symbolic label for a spin degree of freedom
StrLabel	Symbolic label that evaluates to a string
SymbolicLabelBase	Base class for symbolic labels

Functions:

product	Cartesian product akin to itertools.product(), but accepting generator functions
yield_from_ranges

__all__: FockIndex, FockLabel, IdxSym, IndexOverFockSpace, IndexOverList, IndexOverRange, IntIndex, SpinIndex, StrLabel

Reference

class qalgebra.utils.indices.IdxSym(name, *, primed=0, **kwargs)

Bases: sympy.core.symbol.Symbol

Index symbol in an indexed sum or product.

Parameters

• name (str) – The label for the symbol. It must be a simple Latin or Greek letter, possibly with a subscript, e.g. 'i', 'mu', 'gamma_A'

• primed (int) – Number of prime marks (‘) associated with the symbol

Notes

The symbol can be used in arbitrary algebraic (sympy) expressions:

>>> sympy.sqrt(IdxSym('n') + 1)
sqrt(n + 1)

By default, the symbol is assumed to represent an integer. If this is not the case, you can instantiate explicitly as a non-integer:

>>> IdxSym('i').is_integer
True
>>> IdxSym('i', integer=False).is_integer
False

You may also declare the symbol as positive:

>>> IdxSym('i').is_positive
>>> IdxSym('i', positive=True).is_positive
True

The primed parameter is used to automatically create distinguishable indices in products of sums, or more generally if the same index occurs in an expression with potentially differnt values:

>>> ascii(IdxSym('i', primed=2))
"i''"
>>> IdxSym('i') == IdxSym('i', primed=1)
False

It should not be used when creating indices “by hand”

Raises

• ValueError – if name is not a simple symbol label, or if primed < 0

• TypeError – if name is not a string

is_finite = True

is_Symbol = True

is_symbol = True

is_Atom = True

property primed

incr_primed(incr=1)

Return a copy of the index with an incremented primed

property prime

equivalent to incr_primed() with incr=1

name

default_assumptions = {'finite': True, 'infinite': False}

is_infinite = False

class qalgebra.utils.indices.IntIndex(expr)

Bases: qalgebra.utils.indices.SymbolicLabelBase

A symbolic label that evaluates to an integer.

The label can be rendered via substitute():

>>> i, j = symbols('i, j', cls=IdxSym)
>>> idx = IntIndex(i+j)
>>> idx.substitute({i: 1, j:1})
2

An “incomplete” substitution (anything that still leaves a IdxSym in the label expression) will result in another IntIndex instance:

>>> idx.substitute({i: 1})
IntIndex(Add(IdxSym('j', integer=True), Integer(1)))

class qalgebra.utils.indices.FockIndex(expr)

Bases: qalgebra.utils.indices.IntIndex

Symbolic index labeling a basis state in a LocalSpace

property fock_index

class qalgebra.utils.indices.StrLabel(expr)

Bases: qalgebra.utils.indices.SymbolicLabelBase

Symbolic label that evaluates to a string

Example

>>> i = symbols('i', cls=IdxSym)
>>> A = symbols('A', cls=sympy.IndexedBase)
>>> lbl = StrLabel(A[i])
>>> lbl.substitute({i: 1})
'A_1'

class qalgebra.utils.indices.FockLabel(expr, hs)

Bases: qalgebra.utils.indices.StrLabel

Symbolic label that evaluates to the label of a basis state

This evaluates first to an index, and then to the label for the basis state of the Hilbert space for that index:

>>> hs = LocalSpace('tls', basis=('g', 'e'))
>>> i = symbols('i', cls=IdxSym)
>>> lbl = FockLabel(i, hs=hs)
>>> lbl.substitute({i: 0})
'g'

property fock_index

substitute(var_map)

Substitute in the expression describing the label.

If the result of the substitution no longer contains any IdxSym, this returns a “rendered” label.

class qalgebra.utils.indices.SpinIndex(expr, hs)

Bases: qalgebra.utils.indices.StrLabel

Symbolic label for a spin degree of freedom

This evaluates to a string representation of an integer or half-integer. For values of e.g. 1, -1, 1/2, -1/2, the rendered resulting string is “+1”, “-1”, “+1/2”, “-1/2”, respectively (in agreement with the convention for the basis labels in a spin degree of freedom)

>>> i = symbols('i', cls=IdxSym)
>>> hs = SpinSpace('s', spin='1/2')
>>> lbl = SpinIndex(i/2, hs)
>>> lbl.substitute({i: 1})
'+1/2'

Rendering an expression that is not integer or half-integer valued results in a ValueError.

property fock_index

substitute(var_map)

Substitute in the expression describing the label.

If the result of the substitution no longer contains any IdxSym, this returns a “rendered” label.

class qalgebra.utils.indices.IndexOverList(index_symbol, values)

Bases: qalgebra.utils.indices.IndexRangeBase

Index over a list of explicit values

Parameters

• index_symbol (IdxSym) – The symbol iterating over the value

• values (list) – List of values for the index

iter()

substitute(var_map)

piecewise_one(expr)

Value of 1 for all index values in the range, 0 otherwise

A Piecewise object that is 1 for any value of expr in the range of possible index values, and 0 otherwise.

class qalgebra.utils.indices.IndexOverRange(index_symbol, start_from, to, step=1)

Bases: qalgebra.utils.indices.IndexRangeBase

Index over the inclusive range between two integers

Parameters

• index_symbol (IdxSym) – The symbol iterating over the range

• start_from (int) – Starting value for the index

• to (int) – End value of the index

• step (int) – Step width by which index increases

iter()

property range

substitute(var_map)

piecewise_one(expr)

Value of 1 for all index values in the range, 0 otherwise

A Piecewise object that is 1 for any value of expr in the range of possible index values, and 0 otherwise.

class qalgebra.utils.indices.IndexOverFockSpace(index_symbol, hs)

Bases: qalgebra.utils.indices.IndexRangeBase

Index range over the integer indices of a LocalSpace basis

Parameters

• index_symbol (IdxSym) – The symbol iterating over the range

• hs (LocalSpace) – Hilbert space over whose basis to iterate

iter()

substitute(var_map)

piecewise_one(expr)

Value of 1 for all index values in the range, 0 otherwise

A Piecewise object that is 1 for any value of expr in the range of possible index values, and 0 otherwise.

class qalgebra.utils.indices.IndexRangeBase(index_symbol)

Bases: object

Base class for index ranges

Index ranges occur in indexed sums or products.

abstract iter()

abstract substitute(var_map)

abstract piecewise_one(expr)

Value of 1 for all index values in the range, 0 otherwise

A Piecewise object that is 1 for any value of expr in the range of possible index values, and 0 otherwise.

class qalgebra.utils.indices.SymbolicLabelBase(expr)

Bases: object

Base class for symbolic labels

A symbolic label is a SymPy expression that contains one or more IdxSym, and can be rendered into an integer or string label by substituting integer values for each IdxSym.

See IntIndex for an example.

substitute(var_map)

Substitute in the expression describing the label.

If the result of the substitution no longer contains any IdxSym, this returns a “rendered” label.

property free_symbols

Free symbols in the expression describing the label

qalgebra.utils.indices.product(*generators, repeat=1)

Cartesian product akin to itertools.product(), but accepting generator functions

Unlike itertools.product() this function does not convert the input iterables into tuples. Thus, it can handle large or infinite inputs. As a drawback, however, it only works with “restartable” iterables (something that iter() can repeatably turn into an iterator, or a generator function (but not the generator iterator that is returned by that generator function)

Parameters

• generators – list of restartable iterators or generator functions

• repeat – number of times generators should be repeated

Adapted from https://stackoverflow.com/q/12093364/

qalgebra.utils.indices.yield_from_ranges(ranges)