inquanto.ansatzes

Basic ansatzes

class GeneralAnsatz(reference, *args, **kwargs)

Bases: Symbolic, Representable

Base class for a quantum state that can be represented with a single circuit.

Parameters:
circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

Any – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

abstract free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

abstract get_circuit(symbol_map=None)

Constructs a single state circuit.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

abstract symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

Self – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState()

Create a symbolic QubitState representation of the ansatz.

Returns:

QubitState – Ansatz as a QubitState.

abstract unsympify(precision=15)

Unsympifies dictionary values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision for evaluation.

Returns:

GeneralAnsatz – Updated instance of GeneralAnsatz. This operation is in-place.

class CircuitAnsatz(circuit, reference=None)

Bases: GeneralAnsatz

An ansatz that stores a single symbolic circuit.

Parameters:
circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

Any – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

CircuitAnsatz – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState()

Create a symbolic QubitState representation of the ansatz.

Returns:

QubitState – Ansatz as a QubitState.

unsympify(precision=15)

Unsympifies dictionary values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values. For CircuitAnsatz, this has no effect.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision for evaluation.

Returns:

CircuitAnsatz – Updated instance of CircuitAnsatz. This operation is in-place.

class ComposedAnsatz(*ansatzes, reference=None)

Bases: CircuitAnsatz

Composes circuit ansatzes into one circuit ansatz.

Note

The composed circuit is built by applying the arguments of the ComposedAnsatz constructor in reverse order. i.e. for two instances of CircuitAnsatz A, B, the composed circuit of ComposedAnsatz(A, B) represents the state AB \(|0\rangle\), hence B is applied first.

Examples

>>> A = CircuitAnsatz(Circuit(1).Y(0))
>>> B = CircuitAnsatz(Circuit(1).Z(0), [1])
>>> ComposedAnsatz(A, B).get_circuit()
[X q[0]; Z q[0]; Y q[0]; ]
>>> C = CircuitAnsatz(Circuit(1).Y(0))
>>> D = CircuitAnsatz(Circuit(1).Z(0))
>>> ComposedAnsatz(C, D, reference = [1]).get_circuit()
[X q[0]; Z q[0]; Y q[0]; ]
Parameters:
circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

Any – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

CircuitAnsatz – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState()

Create a symbolic QubitState representation of the ansatz.

Returns:

QubitState – Ansatz as a QubitState.

unsympify(precision=15)

Unsympifies dictionary values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values. For CircuitAnsatz, this has no effect.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision for evaluation.

Returns:

CircuitAnsatz – Updated instance of CircuitAnsatz. This operation is in-place.

class TrotterAnsatz(exponents, reference=None)

Bases: GeneralAnsatz

Ansatz representing a state built from a product of Pauli-exponentials.

This is at the core of the UCC family of ansatzes in InQuanto.

Note: This class requires numerical operators within the input QubitOperatorList.

Parameters:

Examples

>>> from inquanto.states import QubitState
>>> exponents = QubitOperatorList.from_string("a [(1j, Y0 X2)], b [(1j, Y1 X3)]")
>>> ref = QubitState([1, 1, 0, 0])
>>> ansatz = TrotterAnsatz(exponents, reference=ref)
>>> ansatz.free_symbols_ordered().as_list() # returns an lexicographically ordered set of symbols
[a, b]
>>> ansatz.free_symbols() == {Symbol("a"), Symbol("b")} # returns a set of symbols
True
>>> ansatz.subs("new_{}").free_symbols() == {Symbol("new_a"), Symbol("new_b")} # new instance
True
>>> ansatz2 = ansatz.symbol_substitution("new_{}")  # in-place substitution
>>> ansatz2 is ansatz
True
>>> ansatz.free_symbols() == {Symbol("new_a"), Symbol("new_b")}
True
circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

property exponents: QubitOperatorList

Returns the qubit operator exponents.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

TrotterAnsatz – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState(reverse=False)

Returns a QubitState object corresponding to the generated state.

This method leverages a helper function to perform direct exponentiation of individual terms and applies them to the reference state. The ansatz must have been constructed with a QubitState reference.

Danger

In general, this will blow up exponentially.

Parameters:

reverse (bool, default: False) – set to True to reverse the order of term application

Returns:

QubitState – The Ansatz state.

unsympify(precision=15)

Unsympifies coefficient values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision used for evaluation.

Returns:

TrotterAnsatz – Updated instance of TrotterAnsatz. This operation is in-place.

reference_circuit_builder(initializer, multireference_builder=None)

Building a non-symbolic reference circuit.

Parameters:

  • initializer (UnionType[int, list[Qubit], list[int], QubitSpace, QubitState, Circuit, None]) –

    A non-symbolic initializer circuit or an object that can be converted to one.

    • If initializer is an int, an empty initializer circuit is created with initializer number of qubits.

    • If initializer is a list of qubit-s, an empty initializer circuit is created with the qubits.

    • If initializer is a list of 0 or 1-s, an initializer circuit is created and X gate is added for

      indices where the initializer[index] == 1.

    • If initializer is a QubitSpace, an empty initializer circuit is created with

      qubits in the QubitSpace.

    • If initializer is a non-symbolic QubitState, an initializer circuit is created

      that represents the initializer state.

  • multireference_builder (Optional[Callable[[QubitState], Circuit]], default: None) –

    A function to prepare a multi-configuration state circuit.
    • This should instantiate a non-symbolic ansatz for a QubitState initializer and

      return the corresponding circuit.

    • If initializer has more than 1 basis state and multireference_builder is None,

      defaults to multi_configuration_preparator of MultiConfigurationState.

Raises:

ValueError – If initializer is None or if the initializer type is not supported.

Returns:

Circuit – A non-symbolic reference circuit.

Fermion Space ansatzes

class FermionSpaceStateExp(fermion_operator_exponents, fock_state, qubit_mapping=QubitMappingJordanWigner(), qubits=None, taperer=None, tapering_exponent_check_behavior='except', *args, **kwargs)

Bases: TrotterAnsatz

Fermion operator exponentiation (e.g. for UCC). Also initializes state trotterization.

Qubit tapering can optionally be performed. To enable qubit tapering, pass a TapererZ2 object to taperer. Tapering behavior can be modified by passing tapering_exponent_check_behavior as specified below.

Parameters:

  • fermion_operator_exponents (FermionOperatorList) – Excitation operators (anti-hermitian for UCC).

  • fock_state (FermionState) – Spin orbital occupations.

  • qubit_mapping (QubitMapping, default: QubitMappingJordanWigner()) – How to map fock state operators and states to qubit operators and circuits.

  • qubits (Optional[list[Qubit]], default: None) – The qubit register used to represent the ansatz state. If no register is provided, a minimal register consisting of qubits indexed from 0 to N is built, where N is the number of spin-orbitals in the reference state provided. Note that this may include qubits corresponding to spin-orbitals which the excitations do not act on.

  • taperer (Optional[TapererZ2], default: None) – The taperer object used to control how the ansatz is tapered. Set to None (default) to skip.

  • tapering_exponent_check_behavior (Literal['except', 'skip', 'discard'], default: "except") –

    Controls treatment of exponents which don’t commute with the Z2 symmetry operators. Options are:

    • "except": Tests each exponent and throws an exception if any exponent does not commute with the symmetry operators.
    • "skip": Skips exponent testing entirely. This may be dangerous (and is untested) but will be faster when exponents are known to be safe.
    • "discard": Tests each exponent and discards any that don’t commute with the Z2 symmetry operators. This should only discard excitations which don’t contribute to the ground state, but may be unsafe.

  • *args (Any) – Additional arguments offered by parent object.

  • **kwargs (Any) – Additional keyword arguments offered by parent object.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

property exponents: QubitOperatorList

Returns the qubit operator exponents.

property fermion_operator_exponents: FermionOperatorList

Returns the list of exponents of the exponential product included in the ansatz.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

TrotterAnsatz – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState(reverse=False)

Returns a QubitState object corresponding to the generated state.

This method leverages a helper function to perform direct exponentiation of individual terms and applies them to the reference state. The ansatz must have been constructed with a QubitState reference.

Danger

In general, this will blow up exponentially.

Parameters:

reverse (bool, default: False) – set to True to reverse the order of term application

Returns:

QubitState – The Ansatz state.

unsympify(precision=15)

Unsympifies exponents and coefficient values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision used for evaluation.

Returns:

FermionSpaceStateExp – Updated instance of FermionSpaceStateExp. This operation is in-place.

class FermionSpaceAnsatzUCCSD(fermion_space, fermion_state, qubit_mapping=QubitMappingJordanWigner(), *args, **kwargs)

Bases: FermionSpaceStateExp

Unitary coupled cluster with singles and doubles excitations (UCCSD).

Builds ansatz for a given fermion_space and fermion_state. If the user-provided FermionSpace class has a defined point group symmetry this is used by default when generating the excitation operators, reducing ansatz depth.

Parameters:

  • fermion_space (FermionSpace | int) – Spin orbital indices, occupations, and spatial orbitals indices.

  • fermion_state (FermionState) – Spin orbital occupations.

  • qubit_mapping (QubitMapping, default: QubitMappingJordanWigner()) – How to map fock state operators and states to qubit operators and circuits.

  • *args (Any) – Additional arguments offered by parent object.

  • **kwargs (Any) – Additional keyword arguments offered by parent object.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

property exponents: QubitOperatorList

Returns the qubit operator exponents.

property fermion_operator_exponents: FermionOperatorList

Returns the list of exponents of the exponential product included in the ansatz.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

TrotterAnsatz – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState(reverse=False)

Returns a QubitState object corresponding to the generated state.

This method leverages a helper function to perform direct exponentiation of individual terms and applies them to the reference state. The ansatz must have been constructed with a QubitState reference.

Danger

In general, this will blow up exponentially.

Parameters:

reverse (bool, default: False) – set to True to reverse the order of term application

Returns:

QubitState – The Ansatz state.

unsympify(precision=15)

Unsympifies exponents and coefficient values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision used for evaluation.

Returns:

FermionSpaceStateExp – Updated instance of FermionSpaceStateExp. This operation is in-place.

class FermionSpaceAnsatzUCCD(fermion_space, fermion_state, qubit_mapping=QubitMappingJordanWigner(), *args, **kwargs)

Bases: FermionSpaceStateExp

Unitary coupled cluster with doubles excitations, no singles (UCCD).

Builds ansatz for a given fermion_space and fermion_state. If the user-provided FermionSpace class has a defined point group symmetry this is used by default when generating the excitation operators, reducing ansatz depth.

Parameters:

  • fermion_space (FermionSpace | int) – Spin orbital indices, occupations, and spatial orbitals indices.

  • fermion_state (FermionState) – Spin orbital occupations.

  • qubit_mapping (QubitMapping, default: QubitMappingJordanWigner()) – How to map fock state operators and states to qubit operators and circuits.

  • *args (Any) – Additional arguments offered by parent object.

  • **kwargs (Any) – Additional keyword arguments offered by parent object.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

property exponents: QubitOperatorList

Returns the qubit operator exponents.

property fermion_operator_exponents: FermionOperatorList

Returns the list of exponents of the exponential product included in the ansatz.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

TrotterAnsatz – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState(reverse=False)

Returns a QubitState object corresponding to the generated state.

This method leverages a helper function to perform direct exponentiation of individual terms and applies them to the reference state. The ansatz must have been constructed with a QubitState reference.

Danger

In general, this will blow up exponentially.

Parameters:

reverse (bool, default: False) – set to True to reverse the order of term application

Returns:

QubitState – The Ansatz state.

unsympify(precision=15)

Unsympifies exponents and coefficient values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision used for evaluation.

Returns:

FermionSpaceStateExp – Updated instance of FermionSpaceStateExp. This operation is in-place.

class FermionSpaceStateExpChemicallyAware(fermion_operator_exponents, fermion_state)

Bases: GeneralAnsatz

Efficient fermion operator exponentiation (e.g. for UCC). Also initializes state trotterization.

Synthesizes molecular orbital to molecular orbital double excitations uniquely. Changes trotter order of excitations to synthesize circuit with fewer two qubit gates compared to FermionSpaceStateExp. Circuit is synthesized in Jordan-Wigner encoding.

Parameters:

  • fermion_operator_exponents (FermionOperatorList) – Contains exponents and symbols. Assumes input exponents are ordered as single exponents first, followed by double exponents.

  • fermion_state (FermionState) – Initial fermionic reference state.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

property fermion_operator_exponents: FermionOperatorList

Returns the list of exponents of the exponential product included in the ansatz.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

FermionSpaceStateExpChemicallyAware – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState()

Create a symbolic QubitState representation of the ansatz.

Returns:

QubitState – Ansatz as a QubitState.

unsympify(precision=15)

Unsympifies dictionary values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

  • precision (int, default: 15) – The number of decimal digits of precision used for evaluation.

  • partial – Set to True to allow partial unsympification where terms containing free symbols are present. By default, free symbols in any coefficient will cause an exception.

Returns:

FermionSpaceStateExpChemicallyAware – Updated instance of FermionSpaceStateExpChemicallyAware. This operation is in-place.

class FermionSpaceAnsatzChemicallyAwareUCCSD(fermion_space, fermion_state, *args, **kwargs)

Bases: FermionSpaceStateExpChemicallyAware

Chemically aware unitary coupled cluster with singles and doubles excitations (UCCSD).

Described in https://doi.org/10.1063/5.0144680.

Builds ansatz for a given fermion_space and fermion_state. Circuit is synthesized in Jordan-Wigner encoding. If the user-provided FermionSpace class has a defined point group symmetry this is used by default when generating the excitation operators, reducing ansatz depth.

Parameters:

  • fermion_space (FermionSpace | int) – Spin orbital indices, occupations, and spatial orbitals indices.

  • fermion_state (FermionState) – Spin orbital occupations.

  • *args (Any) – Additional arguments offered by parent object.

  • **kwargs (Any) – Additional keyword arguments offered by parent object.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

property fermion_operator_exponents: FermionOperatorList

Returns the list of exponents of the exponential product included in the ansatz.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

FermionSpaceStateExpChemicallyAware – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState()

Create a symbolic QubitState representation of the ansatz.

Returns:

QubitState – Ansatz as a QubitState.

unsympify(precision=15)

Unsympifies dictionary values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

  • precision (int, default: 15) – The number of decimal digits of precision used for evaluation.

  • partial – Set to True to allow partial unsympification where terms containing free symbols are present. By default, free symbols in any coefficient will cause an exception.

Returns:

FermionSpaceStateExpChemicallyAware – Updated instance of FermionSpaceStateExpChemicallyAware. This operation is in-place.

class FermionSpaceAnsatzkUpCCGD(fermion_space, fermion_state, k_input, qubit_mapping=QubitMappingJordanWigner(), *args, **kwargs)

Bases: FermionSpaceStateExp

k-UpCCGD Ansatz.

Ansatz consisting of k factors of variationally independent unitary coupled cluster operators with generalized spin-paired doubles excitations, no singles (k-UpCCGD).

Here, generalized means occupied and virtual orbital subspaces are undistinguished, hence occupied-occupied and virtual-virtual excitations are included. See https://arxiv.org/abs/1810.02327 for more details.

If the user-provided FermionSpace class has a defined point group symmetry this is used by default when generating the excitation operators, reducing ansatz depth.

Parameters:

  • fermion_space (FermionSpace | int) – Spin orbital indices, occupations, and spatial orbitals indices.

  • fermion_state (FermionState) – Spin orbital occupations.

  • k_input (int) – Value of k in k-UpCC; results in k cluster operators.

  • qubit_mapping (QubitMapping, default: QubitMappingJordanWigner()) – How to map fock state operators and states to qubit operators and circuits.

  • *args (Any) – Additional arguments offered by parent object.

  • **kwargs (Any) – Additional keyword arguments offered by parent object.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

property exponents: QubitOperatorList

Returns the qubit operator exponents.

property fermion_operator_exponents: FermionOperatorList

Returns the list of exponents of the exponential product included in the ansatz.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

TrotterAnsatz – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState(reverse=False)

Returns a QubitState object corresponding to the generated state.

This method leverages a helper function to perform direct exponentiation of individual terms and applies them to the reference state. The ansatz must have been constructed with a QubitState reference.

Danger

In general, this will blow up exponentially.

Parameters:

reverse (bool, default: False) – set to True to reverse the order of term application

Returns:

QubitState – The Ansatz state.

unsympify(precision=15)

Unsympifies exponents and coefficient values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision used for evaluation.

Returns:

FermionSpaceStateExp – Updated instance of FermionSpaceStateExp. This operation is in-place.

class FermionSpaceAnsatzkUpCCGSD(fermion_space, fermion_state, k_input, qubit_mapping=QubitMappingJordanWigner(), *args, **kwargs)

Bases: FermionSpaceStateExp

k-UpCCGSD ansatz.

Ansatz consisting of k factors of variationally independent unitary coupled cluster operators with fully generalized singles and generalized spin-paired doubles excitations (k-UpCCGSD).

Here, generalized means occupied and virtual orbital subspaces are undistinguished, hence occupied-occupied and virtual-virtual excitations are included. See https://arxiv.org/abs/1810.02327 for more details.

If the user-provided FermionSpace class has a defined point group symmetry this is used by default when generating the excitation operators, reducing ansatz depth.

Parameters:

  • fermion_space (FermionSpace | int) – Spin orbital indices, occupations, and spatial orbitals indices.

  • fermion_state (FermionState) – Spin orbital occupations.

  • k_input (int) – Value of k in k-UpCC; results in k cluster operators.

  • qubit_mapping (QubitMapping, default: QubitMappingJordanWigner()) – How to map fock state operators and states to qubit operators and circuits.

  • *args (Any) – Additional arguments offered by parent object.

  • **kwargs (Any) – Additional keyword arguments offered by parent object.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

property exponents: QubitOperatorList

Returns the qubit operator exponents.

property fermion_operator_exponents: FermionOperatorList

Returns the list of exponents of the exponential product included in the ansatz.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

TrotterAnsatz – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState(reverse=False)

Returns a QubitState object corresponding to the generated state.

This method leverages a helper function to perform direct exponentiation of individual terms and applies them to the reference state. The ansatz must have been constructed with a QubitState reference.

Danger

In general, this will blow up exponentially.

Parameters:

reverse (bool, default: False) – set to True to reverse the order of term application

Returns:

QubitState – The Ansatz state.

unsympify(precision=15)

Unsympifies exponents and coefficient values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision used for evaluation.

Returns:

FermionSpaceStateExp – Updated instance of FermionSpaceStateExp. This operation is in-place.

class FermionSpaceAnsatzkUpCCGSDSinglet(fermion_space, fermion_state, k_input, qubit_mapping=QubitMappingJordanWigner(), *args, **kwargs)

Bases: FermionSpaceStateExp

k-UpCCGSDSinglet ansatz.

Ansatz consisting of k factors of variationally independent unitary coupled cluster operators with fully generalized singles and generalized spin paired doubles excitations.

Here, generalized means occupied and virtual orbital subspaces are undistinguished, hence occupied-occupied and virtual-virtual excitations are included. See https://arxiv.org/abs/1810.02327 for more details.

If the user-provided FermionSpace class has a defined point group symmetry this is used by default when generating the excitation operators, reducing ansatz depth.

Adapted to singlets, so alpha-alpha and beta-beta single excitations between a given pair of spatial orbitals have the same parameter.

Parameters:

  • fermion_space (FermionSpace | int) – Spin orbital indices, occupations, and spatial orbitals indices.

  • fermion_state (FermionState) – Spin orbital occupations.

  • k_input (int) – Value of k in k-UpCC; results in k cluster operators.

  • qubit_mapping (QubitMapping, default: QubitMappingJordanWigner()) – How to map fock state operators and states to qubit operators and circuits.

  • *args (Any) – Additional arguments offered by parent object.

  • **kwargs (Any) – Additional keyword arguments offered by parent object.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

property exponents: QubitOperatorList

Returns the qubit operator exponents.

property fermion_operator_exponents: FermionOperatorList

Returns the list of exponents of the exponential product included in the ansatz.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

TrotterAnsatz – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState(reverse=False)

Returns a QubitState object corresponding to the generated state.

This method leverages a helper function to perform direct exponentiation of individual terms and applies them to the reference state. The ansatz must have been constructed with a QubitState reference.

Danger

In general, this will blow up exponentially.

Parameters:

reverse (bool, default: False) – set to True to reverse the order of term application

Returns:

QubitState – The Ansatz state.

unsympify(precision=15)

Unsympifies exponents and coefficient values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision used for evaluation.

Returns:

FermionSpaceStateExp – Updated instance of FermionSpaceStateExp. This operation is in-place.

class FermionSpaceAnsatzUCCGD(fermion_space, fermion_state, qubit_mapping=QubitMappingJordanWigner(), *args, **kwargs)

Bases: FermionSpaceStateExp

Unitary coupled cluster with fully generalized doubles excitations, no singles (UCCGD).

Here, generalized means occupied and virtual orbital subspaces are undistinguished, hence occupied-occupied and virtual-virtual excitations are included. See https://arxiv.org/abs/1810.02327 for more details.

If the user-provided FermionSpace class has a defined point group symmetry this is used by default when generating the excitation operators, reducing ansatz depth.

Parameters:

  • fermion_space (FermionSpace | int) – Spin orbital indices, occupations, and spatial orbitals indices.

  • fermion_state (FermionState) – Spin orbital occupations.

  • qubit_mapping (QubitMapping, default: QubitMappingJordanWigner()) – How to map fock state operators and states to qubit operators and circuits.

  • *args (Any) – Additional arguments offered by parent object.

  • **kwargs (Any) – Additional keyword arguments offered by parent object.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

property exponents: QubitOperatorList

Returns the qubit operator exponents.

property fermion_operator_exponents: FermionOperatorList

Returns the list of exponents of the exponential product included in the ansatz.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

TrotterAnsatz – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState(reverse=False)

Returns a QubitState object corresponding to the generated state.

This method leverages a helper function to perform direct exponentiation of individual terms and applies them to the reference state. The ansatz must have been constructed with a QubitState reference.

Danger

In general, this will blow up exponentially.

Parameters:

reverse (bool, default: False) – set to True to reverse the order of term application

Returns:

QubitState – The Ansatz state.

unsympify(precision=15)

Unsympifies exponents and coefficient values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision used for evaluation.

Returns:

FermionSpaceStateExp – Updated instance of FermionSpaceStateExp. This operation is in-place.

class FermionSpaceAnsatzUCCGSD(fermion_space, fermion_state, qubit_mapping=QubitMappingJordanWigner(), *args, **kwargs)

Bases: FermionSpaceStateExp

Unitary coupled cluster with fully generalized singles and doubles excitations (UCCGSD).

Here, generalized means occupied and virtual orbital subspaces are undistinguished, hence occupied-occupied and virtual-virtual excitations are included. See https://arxiv.org/abs/1810.02327 for more details.

If the user-provided FermionSpace class has a defined point group symmetry this is used by default when generating the excitation operators, reducing ansatz depth.

Parameters:

  • fermion_space (FermionSpace | int) – Spin orbital indices, occupations, and spatial orbitals indices.

  • fermion_state (FermionState) – Spin orbital occupations.

  • qubit_mapping (QubitMapping, default: QubitMappingJordanWigner()) – How to map fock state operators and states to qubit operators and circuits.

  • *args (Any) – Additional arguments offered by parent object.

  • **kwargs (Any) – Additional keyword arguments offered by parent object.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

property exponents: QubitOperatorList

Returns the qubit operator exponents.

property fermion_operator_exponents: FermionOperatorList

Returns the list of exponents of the exponential product included in the ansatz.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

TrotterAnsatz – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState(reverse=False)

Returns a QubitState object corresponding to the generated state.

This method leverages a helper function to perform direct exponentiation of individual terms and applies them to the reference state. The ansatz must have been constructed with a QubitState reference.

Danger

In general, this will blow up exponentially.

Parameters:

reverse (bool, default: False) – set to True to reverse the order of term application

Returns:

QubitState – The Ansatz state.

unsympify(precision=15)

Unsympifies exponents and coefficient values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision used for evaluation.

Returns:

FermionSpaceStateExp – Updated instance of FermionSpaceStateExp. This operation is in-place.

class FermionSpaceAnsatzUCCSDSinglet(fermion_space, fermion_state, qubit_mapping=QubitMappingJordanWigner(), *args, **kwargs)

Bases: FermionSpaceStateExp

Unitary coupled cluster with singles and doubles excitations (UCCSD).

Builds ansatz for a given fermion_space and fermion state.

Adapted to singlets, so alpha-alpha and beta-beta single excitations between a given pair of spatial orbitals have the same parameter.

If the user-provided FermionSpace class has a defined point group symmetry this is used by default when generating the excitation operators, reducing ansatz depth.

Parameters:

  • fermion_space (FermionSpace | int) – Spin orbital indices, occupations, and spatial orbitals indices.

  • fermion_state (FermionState) – Spin orbital occupations.

  • qubit_mapping (QubitMapping, default: QubitMappingJordanWigner()) – How to map fock state operators and states to qubit operators and circuits.

  • *args (Any) – Additional arguments offered by parent object.

  • **kwargs (Any) – Additional keyword arguments offered by parent object.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

property exponents: QubitOperatorList

Returns the qubit operator exponents.

property fermion_operator_exponents: FermionOperatorList

Returns the list of exponents of the exponential product included in the ansatz.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

TrotterAnsatz – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState(reverse=False)

Returns a QubitState object corresponding to the generated state.

This method leverages a helper function to perform direct exponentiation of individual terms and applies them to the reference state. The ansatz must have been constructed with a QubitState reference.

Danger

In general, this will blow up exponentially.

Parameters:

reverse (bool, default: False) – set to True to reverse the order of term application

Returns:

QubitState – The Ansatz state.

unsympify(precision=15)

Unsympifies exponents and coefficient values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision used for evaluation.

Returns:

FermionSpaceStateExp – Updated instance of FermionSpaceStateExp. This operation is in-place.

class PerfectPairing(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

Enum describing perfect pairing options for tUPS ansatz.

Perfect pairing refers to what qubits (orbitals) are considered nearest neighbours.

NONE: uses traditional energy ordering. ORBITAL_ENERGY: links the lowest and highest energy orbitals and filters inwards.

NONE = 'none'
ORBITAL_ENERGY = 'orbital_energy'
capitalize()

Return a capitalized version of the string.

More specifically, make the first character have upper case and the rest lower case.

casefold()

Return a version of the string suitable for caseless comparisons.

center(width, fillchar=' ', /)

Return a centered string of length width.

Padding is done using the specified fill character (default is a space).

count(sub[, start[, end]]) → int

Return the number of non-overlapping occurrences of substring sub in string S[start:end]. Optional arguments start and end are interpreted as in slice notation.

encode(encoding='utf-8', errors='strict')

Encode the string using the codec registered for encoding.

encoding

The encoding in which to encode the string.

errors

The error handling scheme to use for encoding errors. The default is ‘strict’ meaning that encoding errors raise a UnicodeEncodeError. Other possible values are ‘ignore’, ‘replace’ and ‘xmlcharrefreplace’ as well as any other name registered with codecs.register_error that can handle UnicodeEncodeErrors.

endswith(suffix[, start[, end]]) → bool

Return True if S ends with the specified suffix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. suffix can also be a tuple of strings to try.

expandtabs(tabsize=8)

Return a copy where all tab characters are expanded using spaces.

If tabsize is not given, a tab size of 8 characters is assumed.

find(sub[, start[, end]]) → int

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Return -1 on failure.

format(*args, **kwargs) → str

Return a formatted version of S, using substitutions from args and kwargs. The substitutions are identified by braces (‘{’ and ‘}’).

format_map(mapping) → str

Return a formatted version of S, using substitutions from mapping. The substitutions are identified by braces (‘{’ and ‘}’).

index(sub[, start[, end]]) → int

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Raises ValueError when the substring is not found.

isalnum()

Return True if the string is an alpha-numeric string, False otherwise.

A string is alpha-numeric if all characters in the string are alpha-numeric and there is at least one character in the string.

isalpha()

Return True if the string is an alphabetic string, False otherwise.

A string is alphabetic if all characters in the string are alphabetic and there is at least one character in the string.

isascii()

Return True if all characters in the string are ASCII, False otherwise.

ASCII characters have code points in the range U+0000-U+007F. Empty string is ASCII too.

isdecimal()

Return True if the string is a decimal string, False otherwise.

A string is a decimal string if all characters in the string are decimal and there is at least one character in the string.

isdigit()

Return True if the string is a digit string, False otherwise.

A string is a digit string if all characters in the string are digits and there is at least one character in the string.

isidentifier()

Return True if the string is a valid Python identifier, False otherwise.

Call keyword.iskeyword(s) to test whether string s is a reserved identifier, such as “def” or “class”.

islower()

Return True if the string is a lowercase string, False otherwise.

A string is lowercase if all cased characters in the string are lowercase and there is at least one cased character in the string.

isnumeric()

Return True if the string is a numeric string, False otherwise.

A string is numeric if all characters in the string are numeric and there is at least one character in the string.

isprintable()

Return True if the string is printable, False otherwise.

A string is printable if all of its characters are considered printable in repr() or if it is empty.

isspace()

Return True if the string is a whitespace string, False otherwise.

A string is whitespace if all characters in the string are whitespace and there is at least one character in the string.

istitle()

Return True if the string is a title-cased string, False otherwise.

In a title-cased string, upper- and title-case characters may only follow uncased characters and lowercase characters only cased ones.

isupper()

Return True if the string is an uppercase string, False otherwise.

A string is uppercase if all cased characters in the string are uppercase and there is at least one cased character in the string.

join(iterable, /)

Concatenate any number of strings.

The string whose method is called is inserted in between each given string. The result is returned as a new string.

Example: ‘.’.join([‘ab’, ‘pq’, ‘rs’]) -> ‘ab.pq.rs’

ljust(width, fillchar=' ', /)

Return a left-justified string of length width.

Padding is done using the specified fill character (default is a space).

lower()

Return a copy of the string converted to lowercase.

lstrip(chars=None, /)

Return a copy of the string with leading whitespace removed.

If chars is given and not None, remove characters in chars instead.

static maketrans()

Return a translation table usable for str.translate().

If there is only one argument, it must be a dictionary mapping Unicode ordinals (integers) or characters to Unicode ordinals, strings or None. Character keys will be then converted to ordinals. If there are two arguments, they must be strings of equal length, and in the resulting dictionary, each character in x will be mapped to the character at the same position in y. If there is a third argument, it must be a string, whose characters will be mapped to None in the result.

partition(sep, /)

Partition the string into three parts using the given separator.

This will search for the separator in the string. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing the original string and two empty strings.

removeprefix(prefix, /)

Return a str with the given prefix string removed if present.

If the string starts with the prefix string, return string[len(prefix):]. Otherwise, return a copy of the original string.

removesuffix(suffix, /)

Return a str with the given suffix string removed if present.

If the string ends with the suffix string and that suffix is not empty, return string[:-len(suffix)]. Otherwise, return a copy of the original string.

replace(old, new, count=-1, /)

Return a copy with all occurrences of substring old replaced by new.

count

Maximum number of occurrences to replace. -1 (the default value) means replace all occurrences.

If the optional argument count is given, only the first count occurrences are replaced.

rfind(sub[, start[, end]]) → int

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Return -1 on failure.

rindex(sub[, start[, end]]) → int

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Raises ValueError when the substring is not found.

rjust(width, fillchar=' ', /)

Return a right-justified string of length width.

Padding is done using the specified fill character (default is a space).

rpartition(sep, /)

Partition the string into three parts using the given separator.

This will search for the separator in the string, starting at the end. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing two empty strings and the original string.

rsplit(sep=None, maxsplit=-1)

Return a list of the substrings in the string, using sep as the separator string.

sep

The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including \n \r \t \f and spaces) and will discard empty strings from the result.

maxsplit

Maximum number of splits (starting from the left). -1 (the default value) means no limit.

Splitting starts at the end of the string and works to the front.

rstrip(chars=None, /)

Return a copy of the string with trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

split(sep=None, maxsplit=-1)

Return a list of the substrings in the string, using sep as the separator string.

sep

The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including \n \r \t \f and spaces) and will discard empty strings from the result.

maxsplit

Maximum number of splits (starting from the left). -1 (the default value) means no limit.

Note, str.split() is mainly useful for data that has been intentionally delimited. With natural text that includes punctuation, consider using the regular expression module.

splitlines(keepends=False)

Return a list of the lines in the string, breaking at line boundaries.

Line breaks are not included in the resulting list unless keepends is given and true.

startswith(prefix[, start[, end]]) → bool

Return True if S starts with the specified prefix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. prefix can also be a tuple of strings to try.

strip(chars=None, /)

Return a copy of the string with leading and trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

swapcase()

Convert uppercase characters to lowercase and lowercase characters to uppercase.

title()

Return a version of the string where each word is titlecased.

More specifically, words start with uppercased characters and all remaining cased characters have lower case.

translate(table, /)

Replace each character in the string using the given translation table.

table

Translation table, which must be a mapping of Unicode ordinals to Unicode ordinals, strings, or None.

The table must implement lookup/indexing via __getitem__, for instance a dictionary or list. If this operation raises LookupError, the character is left untouched. Characters mapped to None are deleted.

upper()

Return a copy of the string converted to uppercase.

zfill(width, /)

Pad a numeric string with zeros on the left, to fill a field of the given width.

The string is never truncated.

class FermionSpaceAnsatzsUPS(fermion_space, fermion_state, excitations=None, qubit_mapping=QubitMappingJordanWigner(), *args, **kwargs)

Bases: FermionSpaceStateExp

Fermionic ansatz for the symmetrised Unitary Product State (sUPS).

This is defined in https://doi.org/10.1038/s41534-023-00744-2 using generalised anti-Hermitian spin adapted singles and paired doubles.

Builds ansatz for a given fermion_space and fermion_state.

Parameters:

  • fermion_space (FermionSpace) – Spin orbital indices, occupations and spatial orbital indices. Contains methods to generate the excitations.

  • fermion_state (FermionState) – Spin orbital occupations.

  • excitations (Optional[Sequence[tuple[str, int, int]]], default: None) – Sequence of excitations indexed by a string “s” or “d” corresponding to single or double excitation, annhilate index and create index of the spatial orbitals. If this is left unspecified, create 1 copy of the singles and doubles, equivalent to k=1 kUpCCGSDSinglet ansatz.

  • qubit_mapping (QubitMapping, default: QubitMappingJordanWigner()) – How to map fock state operators and states to qubit operators and circuits.

  • *args (Any) – Additional arguments offered by parent object.

  • **kwargs (Any) – Additional keyword arguments offered by parent object.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

property exponents: QubitOperatorList

Returns the qubit operator exponents.

property fermion_operator_exponents: FermionOperatorList

Returns the list of exponents of the exponential product included in the ansatz.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

TrotterAnsatz – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState(reverse=False)

Returns a QubitState object corresponding to the generated state.

This method leverages a helper function to perform direct exponentiation of individual terms and applies them to the reference state. The ansatz must have been constructed with a QubitState reference.

Danger

In general, this will blow up exponentially.

Parameters:

reverse (bool, default: False) – set to True to reverse the order of term application

Returns:

QubitState – The Ansatz state.

unsympify(precision=15)

Unsympifies exponents and coefficient values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision used for evaluation.

Returns:

FermionSpaceStateExp – Updated instance of FermionSpaceStateExp. This operation is in-place.

class FermionSpaceAnsatztUPS(fermion_space, fermion_state, layers=1, orbital_optimisation=False, perfect_pairing=PerfectPairing.NONE, qubit_mapping=QubitMappingJordanWigner(), *args, **kwargs)

Bases: FermionSpaceStateExp

Fermionic ansatz for the tiled Unitary Product State (tUPS).

This is defined in https://doi.org/10.1103/PhysRevResearch.6.023300 using generalised anti-Hermitian spin adapted singles and paired doubles.

Perfect pairing has been implemented which can be used with keyword :code: PerfectPairing.ORBITAL_ENERGY (default is :code: PerfectPairing.NONE).

This works by pairing the lowest energy spatial MO and highest energy spatial MO as if they were nearest neighbours and folds inwards. To keep the neat tiling pattern, and therefore the optimal circuit resources, the fermionic operators have to be permuted, alongside the fermion state AND the chemical operator which has to be done separately.

Builds ansatz for a given fermion_space and fermion_state.

Parameters:

  • fermion_space (FermionSpace) – Spin orbital indices, occupations and spatial orbital indices. Contains methods to generate the excitations.

  • fermion_state (FermionState) – Spin orbital occupations.

  • layers (int, default: 1) – Number of layers within ansatz. Default 1.

  • orbital_optimisation (bool, default: False) – Whether to tag on the orbital optimisation circuit at the end of the tUPS ansatz. Default False.

  • perfect_pairing (PerfectPairing, default: PerfectPairing.NONE) – An instance of the PerfectPairing enum describing whether to use NONE, or ORBITAL_ENERGY.

  • qubit_mapping (QubitMapping) – How to map fock state operators and states to qubit operators and circuits. Only Jordan–Wigner currently supported.

  • *args (Any) – Additional arguments offered by parent object.

  • **kwargs (Any) – Additional keyword arguments offered by parent object.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

property exponents: QubitOperatorList

Returns the qubit operator exponents.

property fermion_operator_exponents: FermionOperatorList

Returns the list of exponents of the exponential product included in the ansatz.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

TrotterAnsatz – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState(reverse=False)

Returns a QubitState object corresponding to the generated state.

This method leverages a helper function to perform direct exponentiation of individual terms and applies them to the reference state. The ansatz must have been constructed with a QubitState reference.

Danger

In general, this will blow up exponentially.

Parameters:

reverse (bool, default: False) – set to True to reverse the order of term application

Returns:

QubitState – The Ansatz state.

unsympify(precision=15)

Unsympifies exponents and coefficient values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision used for evaluation.

Returns:

FermionSpaceStateExp – Updated instance of FermionSpaceStateExp. This operation is in-place.

Multi-configurational ansatzes

class MultiConfigurationAnsatz(configurations, reference=None)

Bases: GeneralAnsatz

Variational ansatz consisting of selected occupation configurations, using Givens rotations.

Consists of occupation configurations which have symbolic coefficients.

Follows logic of https://quantum-journal.org/papers/q-2022-06-20-742/, with in-house developed procedures to control Givens rotations.

Finds necessary controls of Givens rotation boxes using method based on hamming distances (and their qubit-wise decompositions) of all configurations relative to the first.

For single excitations (2 qubits), hamming distance = 2, the 1-body Givens rotation (G1) in Figure 12 of https://quantum-journal.org/papers/q-2022-06-20-742/ is used.

For double excitations (4 qubits), hamming distance = 4, the 2-body Givens rotation (G2) in Figure 11 of https://quantum-journal.org/papers/q-2022-06-20-742/ is used.

Excitations that are higher than doubles are achieved by nesting a controlled G1 inside a ladder of controlled-SWAPs (G1(>2)).

Note

Supports only basis configurations which have the same number of 1s in the bit string. This corresponds to configurations with the same particle number as Jordan-Wigner encoding is assumed.

Parameters:
circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None)

Constructs a single state circuit.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

MultiConfigurationAnsatz – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState()

Create a symbolic QubitState representation of the ansatz.

Returns:

QubitState – Ansatz as a QubitState.

unsympify(precision=15)

Unsympifies dictionary values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values. For MultiConfigurationAnsatz, this has no effect.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision for evaluation.

Returns:

MultiConfigurationAnsatz – Updated instance of MultiConfigurationAnsatz. This operation is in-place.

class MultiConfigurationState(input_states)

Bases: GeneralAnsatz

State preparation for a selected linear combination of occupation configurations with fixed coefficients.

Configuration coefficients must be real-valued.

Follows logic of https://quantum-journal.org/papers/q-2022-06-20-742/, with in-house developed procedures to control Givens rotations.

Finds necessary controls of Givens rotation boxes using method based on hamming distances (and their qubit-wise decompositions) of all configurations relative to the first.

For single excitations (2 qubits), hamming distance = 2, the 1-body Givens rotation (G1) in Figure 12 of https://quantum-journal.org/papers/q-2022-06-20-742/ is used.

For double excitations (4 qubits), hamming distance = 4, the 2-body Givens rotation (G2) in Figure 11 of https://quantum-journal.org/papers/q-2022-06-20-742/ is used.

Excitations that are higher than doubles are achieved by nesting a controlled G1 inside a ladder of controlled-SWAPs (G1(>2)).

Note

Supports only basis configurations which have the same number of 1s in the bit string. This corresponds to configurations with the same particle number as Jordan-Wigner encoding is assumed.

Parameters:

input_states (QubitState) – Multi-reference qubit state input, providing basis configurations and numerical coefficients. Coefficients must be real and normalized.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

Any – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState()

Create a symbolic QubitState representation of the ansatz.

Returns:

QubitState – Ansatz as a QubitState.

unsympify(precision=15)

Unsympifies coefficients in the input states.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision used for evaluation.

Returns:

MultiConfigurationState – Updated instance of MultiConfigurationState.

class MultiConfigurationStateBox(input_states)

Bases: GeneralAnsatz

State preparation for a selected linear combination of occupation configurations with fixed coefficients.

Serves as a wrapper for pytket’s StatePreparationBox.

Converts input QubitState to ndarray state vector (exponentially scaling), passes this to StatePreparationBox which prepares the state vector using multiplexed-Ry and multiplexed-Rz gates.

See https://cqcl.github.io/tket/pytket/api/circuit.html#pytket.circuit.StatePreparationBox.

Parameters:

input_states (QubitState) – Multi-reference QubitState input, providing basis configurations and numerical coefficients.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

Transform – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

Any – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState()

Create a symbolic QubitState representation of the ansatz.

Returns:

QubitState – Ansatz as a QubitState.

unsympify(precision=15)

Unsympifies coefficients in the configuration state strings and the input states.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision for evaluation.

Returns:

MultiConfigurationStateBox – Updated instance of MultiConfigurationStateBox. This operation is in-place.

class MultiConfigurationAnsatzSparse(input_statestrings, reference=None)

Bases: GeneralAnsatz

Based on Gleinig and Hoefler’s 2021 IEEE paper https://ieeexplore.ieee.org/document/9586240.

State preparation for a selected linear combination of computational basis states. Takes a set basis states S represented by a sequence of QubitStateString (for example, Slater determinants).

Generates a circuit with statevector that is the linear combination of selected basis states, with |S| - 1 symbolic rotation angles for |S| basis states.

The symbolic parameters can be mapped to basis state coefficients.

Note

Basis states do not need to preserve Hamming weight (can have different numbers of 1s).

Parameters:
circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

Any – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

free_symbols()

Returns the free symbols in the object.

Returns:

Set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None)

Constructs a single state circuit.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

MultiConfigurationAnsatzSparse – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState()

Create a symbolic QubitState representation of the ansatz.

Returns:

QubitState – Ansatz as a QubitState.

unsympify(precision=15)

Unsympifies dictionary values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values. For MultiConfigurationAnsatzSparse, this has no effect.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision for evaluation.

Returns:

MultiConfigurationAnsatzSparse – Updated instance of MultiConfigurationAnsatzSparse. This operation is in-place.

class MultiConfigurationStateSparse(input_qubit_state)

Bases: GeneralAnsatz

Based on Gleinig and Hoefler’s 2021 IEEE paper https://ieeexplore.ieee.org/document/9586240.

State preparation for a selected linear combination of computational basis states with specified coefficients. Takes a set basis states S represented by a QubitState (for example, Slater determinants).

Generates a circuit with statevector that is the linear combination of selected basis states, with |S| - 1 symbolic rotation angles for |S| basis states.

Basis state coefficients are fixed, hence no symbolic parameters here.

Note

Basis states do not need to preserve Hamming weight (can have different numbers of 1s).

Parameters:

input_qubit_state (QubitState) – Multi-reference qubit state input, providing basis configurations and numerical coefficients. Coefficients must be normalized.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

free_symbols()

Returns the free symbols in the object.

Returns:

Set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

Any – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState()

Create a symbolic QubitState representation of the ansatz.

Returns:

QubitState – Ansatz as a QubitState.

unsympify(precision=15)

Unsympifies coefficients in the input states.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision used for evaluation.

Returns:

MultiConfigurationStateSparse – Updated instance of MultiConfigurationStateSparse.

Rotational ansatzes

class RealGeneralizedBasisRotationAnsatz(reference, multireference_builder=None)

Bases: BaseRealBasisRotationAnsatz

Basis rotation ansatz that allows for generalized real unitary rotations.

Constructs the ansatz \(\hat{R} \ket{\Psi}\) where \(\hat{R}\) is given by the Thouless theorem: \(\hat{R} = \exp\left[ \sum_{ij}[\ln U]_{ij} a_i^\dagger a_j \right]\) and \(U\) is a single-particle basis rotation matrix (real, unitary). See https://arxiv.org/abs/1711.04789.

Note

Supports generalized rotations which may mix spin channels.

Note

Uses a Jordan-Wigner mapping for encoding rotations.

Parameters:
ansatz_parameters_from_unitary(rotation_unitary)

Converts a real unitary rotation to ansatz parameters.

Performs a QR decomposition of the rotation matrix to find ansatz parameters.

Parameters:

rotation_unitary (ndarray[tuple[Any, ...], dtype[float64]]) – A real unitary matrix with shape (N_{so}, N_{so}) where N_{so} is the of number of spin-orbitals/qubits. Assumes the spin-orbital encoding: [0a, 0b, 1a, 1b, 2a…].

Returns:

dict[Symbol, int | float | complex | Expr] – The ansatz parameters.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

BaseRealBasisRotationAnsatz – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState()

Create a symbolic QubitState representation of the ansatz.

Returns:

QubitState – Ansatz as a QubitState.

unsympify(precision=15)

Unsympifies dictionary values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision for evaluation.

Returns:

BaseRealBasisRotationAnsatz – Updated instance of BaseRealBasisRotationAnsatz. This operation is in-place.

class RealRestrictedBasisRotationAnsatz(reference, multireference_builder=None)

Bases: BaseRealBasisRotationAnsatz

Basis rotation ansatz that allows for restricted-spin, real unitary rotations.

Constructs the ansatz \(\hat{R} \ket{\Psi}\) where \(\hat{R}\) is given by the Thouless theorem: \(\hat{R} = \exp\left[ \sum_{ij}[\ln U]_{ij} a_i^\dagger a_j \right]\) and \(U\) is a single-particle basis rotation matrix (real, unitary). See https://arxiv.org/abs/1711.04789.

Note

Supports rotations which act on both spin channels equivalently, and independently.

Note

Uses a Jordan-Wigner mapping for encoding rotations.

Parameters:
ansatz_parameters_from_unitary(rotation_unitary)

Converts a real unitary rotation to ansatz parameters.

Performs a QR decomposition of the rotation matrix to find ansatz parameters.

Parameters:

rotation_unitary (ndarray[tuple[Any, ...], dtype[float64]]) – A real unitary matrix with shape (n_orb, n_orb) where n_orb is the of number of spatial orbitals. This rotation is applied to both spin channels.

Returns:

dict[Symbol, int | float | complex | Expr] – The ansatz parameters.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

BaseRealBasisRotationAnsatz – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState()

Create a symbolic QubitState representation of the ansatz.

Returns:

QubitState – Ansatz as a QubitState.

unsympify(precision=15)

Unsympifies dictionary values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision for evaluation.

Returns:

BaseRealBasisRotationAnsatz – Updated instance of BaseRealBasisRotationAnsatz. This operation is in-place.

class RealUnrestrictedBasisRotationAnsatz(reference, multireference_builder=None)

Bases: BaseRealBasisRotationAnsatz

Basis rotation ansatz that allows for unrestricted-spin, real unitary rotations.

Constructs the ansatz \(\hat{R} \ket{\Psi}\) where \(\hat{R}\) is given by the Thouless theorem: \(\hat{R} = \exp\left[ \sum_{ij}[\ln U]_{ij} a_i^\dagger a_j \right]\) and \(U\) is a single-particle basis rotation matrix (real, unitary). See https://arxiv.org/abs/1711.04789.

Note

Supports rotations which transform each spin channel independently.

Note

Uses a Jordan-Wigner mapping for encoding rotations.

Parameters:
ansatz_parameters_from_unitary(rotation_unitary_a, rotation_unitary_b)

Converts a real unitary rotation to ansatz parameters.

Performs a QR decomposition of the rotation matrix to find ansatz parameters.

Parameters:

  • rotation_unitary_a (ndarray[tuple[Any, ...], dtype[float64]]) – A real unitary matrix with shape (n_orb, n_orb) where n_orb is the of number of spatial orbitals. This rotation is applied to the alpha spin channel.

  • rotation_unitary_b (ndarray[tuple[Any, ...], dtype[float64]]) – A real unitary matrix with shape (n_orb, n_orb) where n_orb is the of number of spatial orbitals. This rotation is applied to the beta spin channel. Must be the same shape as rotation_unitary_a.

Returns:

dict[Symbol, int | float | complex | Expr] – The ansatz parameters.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

BaseRealBasisRotationAnsatz – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState()

Create a symbolic QubitState representation of the ansatz.

Returns:

QubitState – Ansatz as a QubitState.

unsympify(precision=15)

Unsympifies dictionary values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision for evaluation.

Returns:

BaseRealBasisRotationAnsatz – Updated instance of BaseRealBasisRotationAnsatz. This operation is in-place.

generalized_basis_rotation_to_circuit(rotation_unitary)

Converts a real unitary basis rotation to a circuit.

Supports generalized real rotations, which may couple and mix spin channels.

Note

Uses a Jordan-Wigner mapping for encoding rotations.

Parameters:

rotation_unitary (ndarray[tuple[Any, ...], dtype[float64]]) – A real unitary matrix with shape (N_{so}, N_{so}) where N_{so} is the of number of spin-orbitals/qubits. Assumes the spin-orbital encoding: [0a, 0b, 1a, 1b, 2a…].

Returns:

Circuit – A circuit representing the basis rotation matrix, the number of qubits equals to the number of spin-orbitals.

restricted_basis_rotation_to_circuit(rotation_unitary)

Converts a real unitary basis rotation to a circuit.

Rotation is applied to both alpha and beta spin channels.

Note

Uses a Jordan-Wigner mapping for encoding rotations.

Parameters:

rotation_unitary (ndarray[tuple[Any, ...], dtype[float64]]) – A real unitary matrix with shape (n_{orb}, n_{orb}) where n_{orb} is the of number of spatial orbitals.

Returns:

Circuit – A circuit representing the basis rotation matrix, the number of qubits equals to the number of spin-orbitals.

unrestricted_basis_rotation_to_circuit(rotation_unitary_a, rotation_unitary_b)

Converts a pair of real unitary basis rotations to a circuit.

Each rotation matrix corresponds to a spin channel.

Note

Uses a Jordan-Wigner mapping for encoding rotations.

Parameters:

  • rotation_unitary_a (ndarray[tuple[Any, ...], dtype[float64]]) – A real unitary matrix with shape (n_{orb}, n_{orb}) where n_{orb} is the of number of spatial orbitals. This rotation is applied to the alpha spin channel.

  • rotation_unitary_b (ndarray[tuple[Any, ...], dtype[float64]]) – A real unitary matrix with shape (n_{orb}, n_{orb}) where n_{orb} is the of number of spatial orbitals. This rotation is applied to the alpha spin channel. Must be the same shape as rotation_unitary_a.

Returns:

Circuit – A circuit representing the basis rotation matrix, where the number of qubits equals the number of spin-orbitals.

rotate_ansatz_restricted(ansatz, rotation_unitary)

Rotate an ansatz by a real unitary basis rotation.

Rotation is applied to both alpha and beta spin channels. Uses restricted_basis_rotation_to_circuit() in combination with CircuitAnsatz and ComposedAnsatz to build a new state.

Note

Uses a Jordan-Wigner mapping for encoding rotations.

Parameters:

  • ansatz (GeneralAnsatz) – Input ansatz to be rotated. Must be encoded with the Jordan-Wigner mapping.

  • rotation_unitary (ndarray[tuple[Any, ...], dtype[float64]]) – A real unitary matrix with shape (n_{orb}, n_{orb}) where n_{orb} is the of number of spatial orbitals.

Returns:

ComposedAnsatz – A new ansatz with the rotation appended to the state preparation circuit.

Other ansatzes

class HamiltonianVariationalAnsatz(fermion_state, hamiltonian_operator=FermionOperator(), qubit_mapping=QubitMappingJordanWigner(), s=1, *args, **kwargs)

Bases: TrotterAnsatz

Hamiltonian Variational Ansatz introduced in https://arxiv.org/abs/1507.08969.

Parameters:

  • fermion_state (FermionState) – Spin orbital occupations. If applied to molecules, this should represent a single configuration mean field state.

  • hamiltonian_operator (FermionOperator, default: FermionOperator()) – The hamiltonian operator produced by driver.

  • qubit_mapping (QubitMapping, default: QubitMappingJordanWigner()) – How to map Fock state operators and states to qubit operators and circuits.

  • s (int, default: 1) – The number of terms in the multiplication; the total number of parameters will be 5*s.

  • *args (Any) – Additional arguments offered by parent object.

  • **kwargs (Any) – Additional keyword arguments offered by parent object.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

property exponents: QubitOperatorList

Returns the qubit operator exponents.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None, compiler_pass=None)

Constructs a single state circuit.

Parameters:
Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property split_hamiltonian: tuple[FermionOperator, FermionOperator, FermionOperator]

Split hamiltonian into diagonal and non-diagonal elements.

Hamiltonian is separated into three terms \(H_{diag}\), \(H_{hop}\), and \(H_{ex}\), each one a FermionOperator. These will be exponentiated to build the Hamiltonian Variational Ansatz.

Diagonal terms:
\(H_{diag} = \sum_p (e_p a^\dagger_p a_p) + \sum_{p,q}( h_{pqqp} a^\dagger_p a_p a^\dagger_q a_q )\)
in terms of FermionOperator:
\(((p,1), (p,0)) : e_p\) and \(((p,1), (q,1), (p,0), (q,0)) : h_{pqqp}\)
Hopping terms:
\(H_{hop} = \sum_{p,q} (e_{p,q} a^\dagger_p a_q) + \sum_{p,r,q} ( h_{prrp} a^\dagger_p a_q a^\dagger_r a_r )\)
in terms of FermionOperator:
\(((p,1), (q,0)) : e_p,q\) and \(((p,1), (q,1), (q,0), (r,0)) : h_{pqqp}\)
Exchange terms:
\(H_{ex} = \sum_{p,q,r,s} ( h_{pqrs} a^\dagger_p a^\dagger_r a_r a_s)\)
in terms of FermionOperator:
\((((p,1), (q,1), (r,0), (s,0)) : h_{pqrs}\)
Returns:

Diagonal, hopping, and exchange operators extracted from the Hamiltonian.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

TrotterAnsatz – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState(reverse=False)

Returns a QubitState object corresponding to the generated state.

This method leverages a helper function to perform direct exponentiation of individual terms and applies them to the reference state. The ansatz must have been constructed with a QubitState reference.

Danger

In general, this will blow up exponentially.

Parameters:

reverse (bool, default: False) – set to True to reverse the order of term application

Returns:

QubitState – The Ansatz state.

unsympify(precision=15)

Unsympifies coefficients of the qubit operator list and the Hamiltonian operator.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision for evaluation.

Returns:

HamiltonianVariationalAnsatz – Updated instance of HamiltonianVariationalAnsatz. This operation is in-place.

class LayeredAnsatz(rotations_def, reference, n_layers=1, inter_block_entangler=True, entangler_def=None, cap_layers=True, cap_def=None)

Bases: GeneralAnsatz

Parent class for ansatzes with layered replicas of a group of circuit primitives (such as HEA).

Hierarchy:

  • Block (CustomGateDef): Consists of a collection of parametric pytket.circuit.OpType operations added to a circuit.

  • Layer (CircBox): Consists of a rotation block and (possibly) an entangler block. If inter_block_entangler=True (default), rotation blocks between layers are separated by a block of two_qubit operations (entangler).

Parameters:

  • rotations_def (list[CustomGateDef]) – A list of circuit primitives as CustomGateDefs to be placed inside a layer.

  • reference (int | list[Qubit] | list[int] | QubitSpace | QubitState | Circuit) – A reference state circuit or any valid initializer for reference_circuit_builder().

  • n_layers (int, default: 1) – Number of layers to be added to circuit.

  • inter_block_entangler (bool, default: True) – If True add a block of two-qubit gate primitives between rotation blocks within a layer.

  • entangler_def (Optional[CustomGateDef], default: None) – Definition of the two-qubit entangler primitive.

  • cap_layers (bool, default: True) – If True end circuit by adding one extra block of rotations.

  • cap_def (Optional[list[CustomGateDef]], default: None) – A list of circuit primitives as CustomGateDefs for the cap.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None)

Constructs a single state circuit.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

LayeredAnsatz – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState()

Create a symbolic QubitState representation of the ansatz.

Returns:

QubitState – Ansatz as a QubitState.

unsympify(precision=15)

Unsympifies dictionary values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values. For LayeredAnsatz, this has no effect.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision for evaluation.

Returns:

LayeredAnsatz – Updated instance of LayeredAnsatz. This operation is in-place.

class HardwareEfficientAnsatz(rotation_operations, reference, n_layers, entangler_operation=OpType.CX)

Bases: LayeredAnsatz

Hardware Efficient Ansatz as defined in https://arxiv.org/abs/1704.05018.

Consists of n_layers layers of circuit primitives. Each layer consists of a rotation block and an entangler block.

Parameters:

  • rotation_operations (list[OpType]) – Define blocks of rotations as Ry, RxRy or RxRyRz.

  • reference (int | list[Qubit] | list[int] | QubitSpace | QubitState | Circuit) – Initial state of qubit register. A reference state circuit or any valid initializer for reference_circuit_builder().

  • n_layers (int) – Number of layers.

  • entangler_operation (OpType, default: OpType.CX) – The operation to build the entangler block. Default value is a CX gate.

circuit_resources(return_circuit=False)

Returns crude resource estimates for the implementation of unoptimized ansatz preparation circuit (e.g. gatecount).

This proceeds via decomposition of boxes in the state preparation circuit, followed by rebasing to the native TKET gateset (CX, TK1, Phase). Analysis of the circuit is performed on a copy – the original circuit stored in this object is left unmodified.

Parameters:

return_circuit (bool, default: False) – If set to True, the rebased circuit will be included as an additional element of the dictionary under the key “circuit”.

Returns:

dict[str, int | Circuit] – A dictionary of resource estimates of the ansatz circuit keyed by resource label (e.g. “depth”), optionally including the rebased circuit.

clone()

Performs shallow copy of the object.

Return type:

Self

copy()

Performs deep copy of the object.

Return type:

Self

default_pass()

Get the default compiler pass for the ansatz type.

Returns:

BasePass – A tket pass object.

df_numeric(symbol_map=None, *, space=None, backend=None, dtype=complex, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_numeric_representation() to generate a numeric vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Danger

This is an exponentially exploding method!

Parameters:
Returns:

DataFrame – A dataframe representing the object.

df_symbolic(symbol_map=None, *, space=None, tol=ANSATZ_ABSOLUTE_TOLERANCE)

Returns a pandas.DataFrame representation of the ansatz state.

Uses get_symbolic_representation() to generate a symbolic vector for the ansatz state, and returns a dataframe with coefficients alongside their corresponding computational basis states.

Assumes lexicographical ordering of basis states.

Symbolic coefficients are simplified before being added to dataframe.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation. Passed to get_symbolic_representation().

  • space (Any, default: None) – Basis information to represent the object. Passed to get_symbolic_representation().

  • tol (float, default: ANSATZ_ABSOLUTE_TOLERANCE) – Absolute tolerance below which terms in the ansatz will be omitted from the dataframe. If negative, no terms are discarded.

Returns:

DataFrame – A dataframe representing the object.

free_symbols()

Returns the free symbols in the object.

Returns:

set[Symbol] – Unordered set of symbols.

free_symbols_ordered()

Returns the free symbols in increasing lexicographic order.

Returns:

SymbolEnsemble – Ordered free symbols in object.

generate_report()

Returns a dict with data describing state object.

Return type:

dict[str, int]

get_circuit(symbol_map=None)

Constructs a single state circuit.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

Returns:

Circuit – A circuit that represent the state.

get_circuit_no_ref(symbol_map=None)

Constructs a single state circuit without the reference state.

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Optional symbol mapping for substitution.

  • compiler_pass – Optional compiler pass for circuit compilation.

Returns:

Circuit – A circuit that represent the referenceless state.

get_numeric_representation(symbol_map=None, *, space=None, backend=None, dtype=complex)

Constructs a single numeric matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

  • backend (Optional[Backend], default: None) – An optional backend to use to build the representation.

  • dtype (Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str, None], default: complex) – Specifies what dtype the return array should be converted.

Returns:

ndarray[tuple[Any, ...], dtype[complexfloating]] – A matrix/vector representing the object.

get_symbolic_representation(symbol_map=None, *, space=None)

Constructs a single symbolic matrix/vector representation.

Danger

This is an exponentially exploding method!

Parameters:

  • symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – A symbol substitution map before constructing the representation.

  • space (Any, default: None) – Basis information to represent the object.

Returns:

Expr – A symbolic expression as a representation, which is a symbolic NDArray.

make_hashable()

Returns a hashable representation of the ansatz object.

Returns:

Hashable – Hashable representation of ansatz.

property n_qubits: int

Returns the number of qubits.

property n_symbols: int

Returns the number of free symbols in the object.

reference_qubit_state()

Create a symbolic QubitState representation of the reference state.

Returns:

QubitState – Reference state as a QubitState.

reset_reference(reference, multireference_builder=None)

Resetting the reference state of the ansatz in place.

Note

The number of qubits in the new reference has to match with the already existing reference state.

Parameters:
Returns:

Self – Returns self with the modified reference.

property state_circuit: Circuit

Returns the symbolic state circuit with a default compilation.

property state_symbols: SymbolEnsemble

Returns the ordered parameter symbols this state uses.

subs(symbol_map)

Returns a new objects with symbols substituted.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None]) – A mapping for substitution of free symbols.

Returns:

Self – A copy of self with symbols substituted according to the provided map.

symbol_substitution(symbol_map=None)

Performs an in-place symbol substation in the object.

Parameters:

symbol_map (Union[dict[Symbol, Expr], dict[Symbol, float], dict[Symbol, float | complex | Expr], Callable[[Symbol], Expr], str, None], default: None) – Dictionary or Callable mapping existing symbols to new symbols or values.

Note

While this is an in-place operation, consistency in free_symbols_ordered() is not guaranteed.

Returns:

LayeredAnsatz – self, with symbols substituted.

to_CircuitAnsatz(symbol_map=None, compiler_pass=None, ignore_default_pass=False)

Cast the ansatz as CircuitAnsatz with optional symbol substitution and compilation control.

Note

Some ansatzes have built in tket compiler passes. These can be ignored when casting to the CircuitAnsatz using ignore_default_pass. This can be combined with the user defined compiler_pass for full control. If the result of self.default_pass is not ignored and a compiler_pass is defined then both sets of passes will be combined and applied.

Parameters:
Returns:

CircuitAnsatz – A new CircuitAnsatz ansatz.

to_QubitState()

Create a symbolic QubitState representation of the ansatz.

Returns:

QubitState – Ansatz as a QubitState.

unsympify(precision=15)

Unsympifies dictionary values.

Replaces symbolic expressions that do not contain free symbols with their corresponding numeric values. For LayeredAnsatz, this has no effect.

Parameters:

precision (int, default: 15) – The number of decimal digits of precision for evaluation.

Returns:

LayeredAnsatz – Updated instance of LayeredAnsatz. This operation is in-place.