inquanto.mappings

class QubitMapping

Bases: ABC

Generic class which performs a mapping from fermions to qubits.

This class forms the base for specific mapping strategies , e.g. the Jordan-Wigner or Bravyi-Kitaev transformation. It may also be used to generate custom mappings, provided they follow the “sets of qubits” formalism of Seeley, Richard & Love (arXiv:1208.5986). Subclasses must implement the following, with more detailed descriptions given in this class’ docstrings:

Required methods:

  • flip_set() the flip qubit set for a given qubit.

  • update_set(): the update qubit set for a given qubit.

  • parity_set(): the parity qubit set for a given qubit.

  • rho_set(): the rho qubit set for a given qubit.

  • state_map_matrix(): a matrix which maps binary representations of fermionic orbital indices to qubit indices.

Required attributes:

  • _MAPPING_FLAGS: internal flags for characterising mappings. If creating a custom mapping, this should be set to ["ambiguous_qubit_number"] for maximal genericism.

OPERATOR_MAP_TYPES

A dictionary which maps input types to output types - e.g. OPERATOR_MAP_TYPES[FermionOperator] = QubitOperator.

_MAPPING_FLAGS = ['']

Internal flags for manipulating how mapping is performed. If creating a custom mapping, set this to ["ambiguous_qubit_number"].

abstract classmethod flip_set(cls, qubit, qubits)

Return the flip set for orbital i.

The flip set is defined as the set of qubits whose parity determines whether a fermionic creation/annihilation operator acting on orbital i is flipped to an annihilation/creation operator.

Parameters:

  • qubit (Union[Qubit, int]) – Index i of fermionic orbital being operated on, or a Qubit sharing the index.

  • qubits (Union[list[Qubit], int]) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

list[Qubit] – List of Qubits comprising the flip set for orbital i.

classmethod operator_map(operator, qubits=None, abs_tol=1e-10)

Map a fermionic operator or set of operators to qubits.

This method functions differently based on the input type:

Note that the attribute OPERATOR_MAP_TYPES of this class contains a map of input types to output types for this method.

Parameters:
Returns:

Union[QubitOperator, QubitOperatorString, QubitOperatorList, list, ndarray, SymmetryOperatorPauliFactorised] – The mapped operator or set of operators in the output format described above.

abstract classmethod parity_set(cls, qubit, qubits=None)

Return the parity set for orbital i.

The parity set is the set of qubits which must be acted on by a Pauli Z in the first term of the mapped operator (where qubit i is acted on by Pauli X), when mapping a creation or annihilation operator acting on orbital i.

Parameters:

  • qubit (Union[Qubit, int]) – Index i of fermionic orbital being operated on, or a Qubit sharing the index.

  • qubits (Union[list[Qubit], int, None], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

list[Qubit] – List of Qubits comprising the parity set for orbital i.

abstract classmethod rho_set(cls, qubit, qubits)

Return the rho set for orbital i.

The rho set is the set of qubits which must be acted on by a Pauli Z in the second term of the mapped operator (where qubit i is acted on by Pauli Y), when mapping a creation or annihilation operator acting on orbital i.

Parameters:

  • qubit (Union[Qubit, int]) – Index i of fermionic orbital being operated on, or a Qubit sharing the index.

  • qubits (Union[list[Qubit], int]) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

list[Qubit] – List of Qubits comprising the rho set for orbital i.

classmethod state_map(state, qubits=None)

Maps a fermionic state to a qubit state.

This method functions differently based on the input type:

  • FermionState and FermionStateString will be mapped to QubitState and QubitStateString respectively. This is the recommended usage.

  • Scipy sparse arrays will be assumed to be a fermionic state vector, and the corresponding qubit state vector will be returned in the input type.

  • Numpy arrays containing scalars will be assumed to be a fermionic state vector, and the corresponding qubit state vector will be returned as a numpy array. If containing objects other than scalars, the method will attempt to recurse.

  • Lists will be treated as iterables and the method will recurse. If this is not possible, it will be assumed that the list contains bools giving occupation numbers for a single basis state, and the corresponding qubit basis state will be returned as a QubitState.

Warning

Generally, implementations of this method use a state mapping scheme given by literature convention – e.g. for Jordan-Wigner, fermionic Fock basis states are mapped directly to qubit computational basis states). This may incur phase flips versus generating states by sequences of mapped creation operators depending on intended ordering convention.

Parameters:

  • state (Union[FermionState, FermionStateString, list, ndarray, spmatrix]) – The fermionic state to be mapped.

  • qubits (Union[list[Qubit], int, None], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

Union[QubitState, QubitStateString, ndarray, spmatrix] – The mapped state in the type described above.

classmethod state_map_conventional(cls, state, qubits=None)

Map a fermionic state to a qubit state vector.

This is an alias of state_map() - see the documentation of this method for further details.

Parameters:

  • state (Union[FermionState, FermionStateString, list, ndarray, spmatrix]) – The fermionic state to be mapped.

  • qubits (Union[list[Qubit], int, None], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

Union[QubitState, QubitStateString, list, ndarray, spmatrix] – The mapped state.

abstract classmethod state_map_matrix(dimension)

Generate a state map matrix.

The state map matrix is a matrix which maps the binary representation of a fermionic basis state index to the binary representation of the corresponding qubit basis state index.

Parameters:

dimension (int) – The dimension of the matrix (i.e. the number of orbitals/qubits).

Returns:

ndarray – A matrix mapping the binary representation of a fermionic basis state index to the binary representation of the corresponding qubit basis state index.

abstract classmethod update_set(cls, qubit, qubits)

Return the update set for orbital i.

The update set is defined as the qubits which must be updated (i.e. acted on by a Pauli X when a fermionic creation or annihilation operator acts on orbital i. Note this does not include qubit i, which is treated independently.

Parameters:

  • qubit (Union[Qubit, int]) – Index i of fermionic orbital being operated on, or a Qubit sharing the index.

  • qubits (Union[list[Qubit], int]) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

list[Qubit] – List of Qubits comprising the update set for orbital i.

class QubitMappingJordanWigner

Bases: QubitMapping

Maps states and operators in a Fermionic space to states and operators in a qubit space using the Jordan-Wigner transformation.

OPERATOR_MAP_TYPES

A dictionary which maps input types to output types - e.g. OPERATOR_MAP_TYPES[FermionOperator] = QubitOperator.

_MAPPING_FLAGS = ['']

Internal flags for manipulating how mapping is performed. If creating a custom mapping, set this to ["ambiguous_qubit_number"].

classmethod flip_set(qubit, qubits=None)

Return the flip set for orbital i.

The flip set is defined as the set of qubits whose parity determines whether a fermionic creation/annihilation operator acting on orbital i is flipped to an annihilation/creation operator.

Parameters:

  • qubit (Union[int, Qubit]) – Index i of fermionic orbital being operated on, or a Qubit sharing the index.

  • qubits (Optional[list[Qubit]], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

list[Qubit] – List of Qubits comprising the flip set for orbital i.

classmethod operator_map(operator, qubits=None, abs_tol=1e-10)

Map a fermionic operator or set of operators to qubits.

This method functions differently based on the input type:

Note that the attribute OPERATOR_MAP_TYPES of this class contains a map of input types to output types for this method.

Parameters:
Returns:

Union[QubitOperator, QubitOperatorString, QubitOperatorList, list, ndarray, SymmetryOperatorPauliFactorised] – The mapped operator or set of operators in the output format described above.

classmethod parity_set(cls, qubit, qubits=None)

Return the parity set for orbital i.

The parity set is the set of qubits which must be acted on by a Pauli Z in the first term of the mapped operator (where qubit i is acted on by Pauli X), when mapping a creation or annihilation operator acting on orbital i.

Parameters:

  • qubit (Union[int, Qubit]) – Index i of fermionic orbital being operated on, or a Qubit sharing the index.

  • qubits (Optional[list[Qubit]], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

list[Qubit] – List of Qubits comprising the parity set for orbital i.

classmethod rho_set(cls, qubit, qubits=None)

Return the rho set for orbital i.

The rho set is the set of qubits which must be acted on by a Pauli Z in the second term of the mapped operator (where qubit i is acted on by Pauli Y), when mapping a creation or annihilation operator acting on orbital i.

Parameters:

  • qubit (Union[int, Qubit]) – Index i of fermionic orbital being operated on, or a Qubit sharing the index.

  • qubits (Optional[list[Qubit]], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

list[Qubit] – List of Qubits comprising the rho set for orbital i.

classmethod state_map(state, qubits=None)

Maps a fermionic state to a qubit state.

This method functions differently based on the input type:

  • FermionState and FermionStateString will be mapped to QubitState and QubitStateString respectively. This is the recommended usage.

  • Scipy sparse arrays will be assumed to be a fermionic state vector, and the corresponding qubit state vector will be returned in the input type.

  • Numpy arrays containing scalars will be assumed to be a fermionic state vector, and the corresponding qubit state vector will be returned as a numpy array. If containing objects other than scalars, the method will attempt to recurse.

  • Lists will be treated as iterables and the method will recurse. If this is not possible, it will be assumed that the list contains bools giving occupation numbers for a single basis state, and the corresponding qubit basis state will be returned as a QubitState.

Warning

Generally, implementations of this method use a state mapping scheme given by literature convention – e.g. for Jordan-Wigner, fermionic Fock basis states are mapped directly to qubit computational basis states). This may incur phase flips versus generating states by sequences of mapped creation operators depending on intended ordering convention.

Parameters:

  • state (Union[FermionState, FermionStateString, list, ndarray, spmatrix]) – The fermionic state to be mapped.

  • qubits (Union[list[Qubit], int, None], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

Union[QubitState, QubitStateString, ndarray, spmatrix] – The mapped state in the type described above.

classmethod state_map_conventional(cls, state, qubits=None)

Map a fermionic state to a qubit state vector.

This is an alias of state_map() - see the documentation of this method for further details.

Parameters:

  • state (Union[FermionState, FermionStateString, list, ndarray, spmatrix]) – The fermionic state to be mapped.

  • qubits (Union[list[Qubit], int, None], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

Union[QubitState, QubitStateString, list, ndarray, spmatrix] – The mapped state.

static state_map_matrix(dimension)

Generate a state map matrix.

The state map matrix is a matrix which maps the binary representation of a fermionic basis state index to the binary representation of the corresponding qubit basis state index.

Parameters:

dimension (int) – The dimension of the matrix (i.e. the number of orbitals/qubits).

Returns:

ndarray[Any, dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]] – A matrix mapping the binary representation of a fermionic basis state index to the binary representation of the corresponding qubit basis state index.

classmethod update_set(qubit, qubits=None)

Return the update set for orbital i.

The update set is defined as the qubits which must be updated (i.e. acted on by a Pauli X when a fermionic creation or annihilation operator acts on orbital i. Note this does not include qubit i, which is treated independently.

Parameters:

  • qubit (Union[int, Qubit]) – Index i of fermionic orbital being operated on, or a Qubit sharing the index.

  • qubits (Optional[list[Qubit]], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

list[Qubit] – List of Qubits comprising the update set for orbital i.

class QubitMappingBravyiKitaev

Bases: QubitMapping

Maps states and operators in a Fermionic space to states and operators in a qubit space using the Bravyi-Kitaev mapping.

The Bravyi-Kitaev mapping encodes both parity and occupation number information in a manner wherein it may be accessed with a logarithmic number of operations with respect to the system size. For further detail, see S. Bravyi, A. Kitaev, Ann. Phys. 298, 210 (2002).

OPERATOR_MAP_TYPES

A dictionary which maps input types to output types - e.g. OPERATOR_MAP_TYPES[FermionOperator] = QubitOperator.

_MAPPING_FLAGS = ['ambiguous_qubit_number']

Internal flags for manipulating how mapping is performed. If creating a custom mapping, set this to ["ambiguous_qubit_number"].

classmethod flip_set(cls, qubit, qubits=None)

Return the flip set for orbital i.

The flip set is defined as the set of qubits whose parity determines whether a fermionic creation/annihilation operator acting on orbital i is flipped to an annihilation/creation operator.

Parameters:

  • qubit (Union[Qubit, int]) – Index i of fermionic orbital being operated on, or a Qubit sharing the index.

  • qubits (Union[list[Qubit], int, None], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

list[Qubit] – List of Qubits comprising the flip set for orbital i.

classmethod operator_map(cls, operator, qubits, abs_tol=1e-10)

Map a fermionic operator or set of operators to qubits.

This method functions differently based on the input type:

Note that the attribute OPERATOR_MAP_TYPES of this class contains a map of input types to output types for this method.

Parameters:

  • operator (Union[FermionOperator, FermionOperatorString, FermionOperatorList, BaseChemistryIntegralOperator, list, ndarray]) – An object representing a fermionic operator or set of operators, with type behaviour specified above.

  • qubits (Union[list[Qubit], int]) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

  • abs_tol (Optional[float], default: 1e-10) – Removes terms in the output operator with magnitude lower than this, to avoid floating point errors resulting in erroneous Pauli strings.

Returns:

Union[QubitOperator, QubitOperatorString, QubitOperatorList, list, ndarray] – The mapped operator or set of operators in the output format described above.

classmethod parity_set(cls, qubit, qubits=None)

Return the parity set for orbital i.

The parity set is the set of qubits which must be acted on by a Pauli Z in the first term of the mapped operator (where qubit i is acted on by Pauli X), when mapping a creation or annihilation operator acting on orbital i.

Parameters:

  • qubit (Union[Qubit, int]) – Index i of fermionic orbital being operated on, or a Qubit sharing the index.

  • qubits (Union[list[Qubit], int, None], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

list[Qubit] – List of Qubits comprising the parity set for orbital i.

classmethod remainder_set(cls, qubit, qubits=None)

Return the remainder set (the set difference of the parity set and the flip set).

Parameters:
Return type:

list[Qubit]

classmethod rho_set(cls, qubit, qubits=None)

Return the rho set for orbital i.

The rho set is the set of qubits which must be acted on by a Pauli Z in the second term of the mapped operator (where qubit i is acted on by Pauli Y), when mapping a creation or annihilation operator acting on orbital i.

Parameters:

  • qubit (Union[Qubit, int]) – Index i of fermionic orbital being operated on, or a Qubit sharing the index.

  • qubits (Union[list[Qubit], int, None], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

list[Qubit] – List of Qubits comprising the rho set for orbital i.

classmethod state_map(state, qubits=None)

Maps a fermionic state to a qubit state.

This method functions differently based on the input type:

  • FermionState and FermionStateString will be mapped to QubitState and QubitStateString respectively. This is the recommended usage.

  • Scipy sparse arrays will be assumed to be a fermionic state vector, and the corresponding qubit state vector will be returned in the input type.

  • Numpy arrays containing scalars will be assumed to be a fermionic state vector, and the corresponding qubit state vector will be returned as a numpy array. If containing objects other than scalars, the method will attempt to recurse.

  • Lists will be treated as iterables and the method will recurse. If this is not possible, it will be assumed that the list contains bools giving occupation numbers for a single basis state, and the corresponding qubit basis state will be returned as a QubitState.

Warning

Generally, implementations of this method use a state mapping scheme given by literature convention – e.g. for Jordan-Wigner, fermionic Fock basis states are mapped directly to qubit computational basis states). This may incur phase flips versus generating states by sequences of mapped creation operators depending on intended ordering convention.

Parameters:

  • state (Union[FermionState, FermionStateString, list, ndarray, spmatrix]) – The fermionic state to be mapped.

  • qubits (Union[list[Qubit], int, None], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

Union[QubitState, QubitStateString, ndarray, spmatrix] – The mapped state in the type described above.

classmethod state_map_conventional(cls, state, qubits=None)

Map a fermionic state to a qubit state vector.

This is an alias of state_map() - see the documentation of this method for further details.

Parameters:

  • state (Union[FermionState, FermionStateString, list, ndarray, spmatrix]) – The fermionic state to be mapped.

  • qubits (Union[list[Qubit], int, None], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

Union[QubitState, QubitStateString, list, ndarray, spmatrix] – The mapped state.

classmethod state_map_matrix(dimension)

Generate a state map matrix.

The state map matrix is a matrix which maps the binary representation of a fermionic basis state index to the binary representation of the corresponding qubit basis state index.

Parameters:

dimension (int) – The dimension of the matrix (i.e. the number of orbitals/qubits).

Returns:

ndarray – A matrix mapping the binary representation of a fermionic basis state index to the binary representation of the corresponding qubit basis state index.

classmethod update_set(cls, qubit, qubits=None)

Return the update set for orbital i.

The update set is defined as the qubits which must be updated (i.e. acted on by a Pauli X when a fermionic creation or annihilation operator acts on orbital i. Note this does not include qubit i, which is treated independently.

Parameters:

  • qubit (Union[Qubit, int]) – Index i of fermionic orbital being operated on, or a Qubit sharing the index.

  • qubits (Union[list[Qubit], int, None], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

list[Qubit] – List of Qubits comprising the update set for orbital i.

class QubitMappingParity

Bases: QubitMapping

Maps states and operators in a Fermionic space to states and operators in a qubit space using the parity mapping.

The parity mapping uses qubits to store the parity of sums of fermionic occupation numbers, thereby reducing the number of operations required to enforce anticommutation relations (but commensurately increasing the number of operations required to update occupation numbers).

OPERATOR_MAP_TYPES

A dictionary which maps input types to output types - e.g. OPERATOR_MAP_TYPES[FermionOperator] = QubitOperator.

_MAPPING_FLAGS = ['ambiguous_qubit_number']

Internal flags for manipulating how mapping is performed. If creating a custom mapping, set this to ["ambiguous_qubit_number"].

classmethod flip_set(cls, qubit, qubits=None)

Return the flip set for orbital i.

The flip set is defined as the set of qubits whose parity determines whether a fermionic creation/annihilation operator acting on orbital i is flipped to an annihilation/creation operator.

Parameters:

  • qubit (Union[Qubit, int]) – Index i of fermionic orbital being operated on, or a Qubit sharing the index.

  • qubits (Union[list[Qubit], int, None], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

list[Qubit] – List of Qubits comprising the flip set for orbital i.

classmethod operator_map(cls, operator, qubits, abs_tol=1e-10)

Map a fermionic operator or set of operators to qubits.

This method functions differently based on the input type:

Note that the attribute OPERATOR_MAP_TYPES of this class contains a map of input types to output types for this method.

Parameters:

  • operator (Union[FermionOperator, FermionOperatorString, FermionOperatorList, BaseChemistryIntegralOperator, list, ndarray]) – An object representing a fermionic operator or set of operators, with type behaviour specified above.

  • qubits (Union[list[Qubit], int]) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

  • abs_tol (Optional[float], default: 1e-10) – Removes terms in the output operator with magnitude lower than this, to avoid floating point errors resulting in erroneous Pauli strings.

Returns:

Union[QubitOperator, QubitOperatorString, QubitOperatorList, list, ndarray] – The mapped operator or set of operators in the output format described above.

classmethod parity_set(cls, qubit, qubits=None)

Return the parity set for orbital i.

The parity set is the set of qubits which must be acted on by a Pauli Z in the first term of the mapped operator (where qubit i is acted on by Pauli X), when mapping a creation or annihilation operator acting on orbital i.

Parameters:

  • qubit (Union[Qubit, int]) – Index i of fermionic orbital being operated on, or a Qubit sharing the index.

  • qubits (Union[list[Qubit], int, None], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

list[Qubit] – List of Qubits comprising the parity set for orbital i.

classmethod rho_set(qubit, qubits=None)

Return the rho set for orbital i.

The rho set is the set of qubits which must be acted on by a Pauli Z in the second term of the mapped operator (where qubit i is acted on by Pauli Y), when mapping a creation or annihilation operator acting on orbital i.

Parameters:

  • qubit (Union[Qubit, int]) – Index i of fermionic orbital being operated on, or a Qubit sharing the index.

  • qubits (Union[list[Qubit], int, None], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

list[Qubit] – List of Qubits comprising the rho set for orbital i.

classmethod state_map(state, qubits=None)

Maps a fermionic state to a qubit state.

This method functions differently based on the input type:

  • FermionState and FermionStateString will be mapped to QubitState and QubitStateString respectively. This is the recommended usage.

  • Scipy sparse arrays will be assumed to be a fermionic state vector, and the corresponding qubit state vector will be returned in the input type.

  • Numpy arrays containing scalars will be assumed to be a fermionic state vector, and the corresponding qubit state vector will be returned as a numpy array. If containing objects other than scalars, the method will attempt to recurse.

  • Lists will be treated as iterables and the method will recurse. If this is not possible, it will be assumed that the list contains bools giving occupation numbers for a single basis state, and the corresponding qubit basis state will be returned as a QubitState.

Warning

Generally, implementations of this method use a state mapping scheme given by literature convention – e.g. for Jordan-Wigner, fermionic Fock basis states are mapped directly to qubit computational basis states). This may incur phase flips versus generating states by sequences of mapped creation operators depending on intended ordering convention.

Parameters:

  • state (Union[FermionState, FermionStateString, list, ndarray, spmatrix]) – The fermionic state to be mapped.

  • qubits (Union[list[Qubit], int, None], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

Union[QubitState, QubitStateString, ndarray, spmatrix] – The mapped state in the type described above.

classmethod state_map_conventional(cls, state, qubits=None)

Map a fermionic state to a qubit state vector.

This is an alias of state_map() - see the documentation of this method for further details.

Parameters:

  • state (Union[FermionState, FermionStateString, list, ndarray, spmatrix]) – The fermionic state to be mapped.

  • qubits (Union[list[Qubit], int, None], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

Union[QubitState, QubitStateString, list, ndarray, spmatrix] – The mapped state.

static state_map_matrix(dimension)

Generate a state map matrix.

The state map matrix is a matrix which maps the binary representation of a fermionic basis state index to the binary representation of the corresponding qubit basis state index.

Parameters:

dimension (int) – The dimension of the matrix (i.e. the number of orbitals/qubits).

Returns:

ndarray – A matrix mapping the binary representation of a fermionic basis state index to the binary representation of the corresponding qubit basis state index.

classmethod update_set(cls, qubit, qubits=None)

Return the update set for orbital i.

The update set is defined as the qubits which must be updated (i.e. acted on by a Pauli X when a fermionic creation or annihilation operator acts on orbital i. Note this does not include qubit i, which is treated independently.

Parameters:

  • qubit (Union[Qubit, int]) – Index i of fermionic orbital being operated on, or a Qubit sharing the index.

  • qubits (Union[list[Qubit], int, None], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

list[Qubit] – List of Qubits comprising the update set for orbital i.

class QubitMappingParaparticular

Bases: QubitMapping

Maps fermions to qubits a paraparticular mapping – i.e. without encoding Fermionic statistics.

This mapping does not encode the fermionic anticommutation relations. Fermionic operators and states are treated as though they were operators and states on a Hilbert space of paraparticles – i.e. particles which obey bosonic commutation relations, but are explicitly restricted to an occupation number of 0 or 1. Qubits can be considered to be paraparticles, so all this mapping does is convert a creation/annihilation operator (\({\sigma^+,\sigma^-}\)) decomposition to a Pauli decomposition.

Warning

This will lead to erroneous results if used as a drop-in replacement for conventional fermion-qubit mapping schemes. The intended use-case for this mapping is for instances where the lack of encoded fermionic anticommutation relations is harmless due to their encoding elsewhere in the problem - for instance, when creating an ansatz used in a variational optimisation (arXiv:2101.11607).

OPERATOR_MAP_TYPES

A dictionary which maps input types to output types - e.g. OPERATOR_MAP_TYPES[FermionOperator] = QubitOperator.

_MAPPING_FLAGS = ['']

Internal flags for manipulating how mapping is performed. If creating a custom mapping, set this to ["ambiguous_qubit_number"].

classmethod flip_set(qubit, qubits=None)

Return the flip set for orbital i.

The flip set is defined as the set of qubits whose parity determines whether a fermionic creation/annihilation operator acting on orbital i is flipped to an annihilation/creation operator.

Parameters:

  • qubit (Union[int, Qubit]) – Index i of fermionic orbital being operated on, or a Qubit sharing the index.

  • qubits (Optional[list[Qubit]], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

list[Qubit] – List of Qubits comprising the flip set for orbital i.

classmethod operator_map(operator, qubits=None, abs_tol=1e-10)

Map a fermionic operator or set of operators to qubits.

This method functions differently based on the input type:

Note that the attribute OPERATOR_MAP_TYPES of this class contains a map of input types to output types for this method.

Parameters:
Returns:

Union[QubitOperator, QubitOperatorString, QubitOperatorList, list, ndarray, SymmetryOperatorPauliFactorised] – The mapped operator or set of operators in the output format described above.

classmethod parity_set(qubit, qubits=None)

Return the parity set for orbital i.

The parity set is the set of qubits which must be acted on by a Pauli Z in the first term of the mapped operator (where qubit i is acted on by Pauli X), when mapping a creation or annihilation operator acting on orbital i.

Parameters:

  • qubit (Union[int, Qubit]) – Index i of fermionic orbital being operated on, or a Qubit sharing the index.

  • qubits (Optional[list[Qubit]], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

list[Qubit] – List of Qubits comprising the parity set for orbital i.

classmethod rho_set(qubit, qubits=None)

Return the rho set for orbital i.

The rho set is the set of qubits which must be acted on by a Pauli Z in the second term of the mapped operator (where qubit i is acted on by Pauli Y), when mapping a creation or annihilation operator acting on orbital i.

Parameters:

  • qubit (Union[int, Qubit]) – Index i of fermionic orbital being operated on, or a Qubit sharing the index.

  • qubits (Optional[list[Qubit]], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

list[Qubit] – List of Qubits comprising the rho set for orbital i.

classmethod state_map(state, qubits=None)

Maps a fermionic state to a qubit state.

This method functions differently based on the input type:

  • FermionState and FermionStateString will be mapped to QubitState and QubitStateString respectively. This is the recommended usage.

  • Scipy sparse arrays will be assumed to be a fermionic state vector, and the corresponding qubit state vector will be returned in the input type.

  • Numpy arrays containing scalars will be assumed to be a fermionic state vector, and the corresponding qubit state vector will be returned as a numpy array. If containing objects other than scalars, the method will attempt to recurse.

  • Lists will be treated as iterables and the method will recurse. If this is not possible, it will be assumed that the list contains bools giving occupation numbers for a single basis state, and the corresponding qubit basis state will be returned as a QubitState.

Warning

Generally, implementations of this method use a state mapping scheme given by literature convention – e.g. for Jordan-Wigner, fermionic Fock basis states are mapped directly to qubit computational basis states). This may incur phase flips versus generating states by sequences of mapped creation operators depending on intended ordering convention.

Parameters:

  • state (Union[FermionState, FermionStateString, list, ndarray, spmatrix]) – The fermionic state to be mapped.

  • qubits (Union[list[Qubit], int, None], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

Union[QubitState, QubitStateString, ndarray, spmatrix] – The mapped state in the type described above.

classmethod state_map_conventional(cls, state, qubits=None)

Map a fermionic state to a qubit state vector.

This is an alias of state_map() - see the documentation of this method for further details.

Parameters:

  • state (Union[FermionState, FermionStateString, list, ndarray, spmatrix]) – The fermionic state to be mapped.

  • qubits (Union[list[Qubit], int, None], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

Union[QubitState, QubitStateString, list, ndarray, spmatrix] – The mapped state.

static state_map_matrix(dimension)

Generate a state map matrix.

The state map matrix is a matrix which maps the binary representation of a fermionic basis state index to the binary representation of the corresponding qubit basis state index.

Parameters:

dimension (int) – The dimension of the matrix (i.e. the number of orbitals/qubits).

Returns:

ndarray[Any, dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]] – A matrix mapping the binary representation of a fermionic basis state index to the binary representation of the corresponding qubit basis state index.

classmethod update_set(qubit, qubits=None)

Return the update set for orbital i.

The update set is defined as the qubits which must be updated (i.e. acted on by a Pauli X when a fermionic creation or annihilation operator acts on orbital i. Note this does not include qubit i, which is treated independently.

Parameters:

  • qubit (Union[int, Qubit]) – Index i of fermionic orbital being operated on, or a Qubit sharing the index.

  • qubits (Optional[list[Qubit]], default: None) – A list of qubits containing the register to be mapped to or an integer giving the size of the register. Qubits do not need to be in order. Optional (minimum necessary register indexed 0-len(qubits) will be assumed) but may be needed for some mappings.

Returns:

list[Qubit] – List of Qubits comprising the update set for orbital i.