# map_transfer_vertex_generators

### map_transfer_vertex_generators(operator, map_action, identity, compose=None)

Map a [`TransferVertexOperator`](qiskit_fermions.operators.TransferVertexOperator.html.md#qiskit_fermions.operators.TransferVertexOperator) to another operator type.

This is a generic function to aid in implementing new mappers for
[`TransferVertexOperator`](qiskit_fermions.operators.TransferVertexOperator.html.md#qiskit_fermions.operators.TransferVertexOperator) instances. At its core, it simply iterates over the
terms of the operator, mapping each encountered [`TransferAction`](qiskit_fermions.operators.transfer_action.TransferAction.html.md#qiskit_fermions.operators.transfer_action.TransferAction) with the
user-provided `map_action` function. In combination with the user-provided `identity`
generator, this allows mapping to arbitrary output types.

#### NOTE
The output type `T` must support multiplication by a scalar via `__mul__`.
If `compose=None` it must also support composition of two instances via `__and__`.
[`SparseObservable`](https://quantum.cloud.ibm.com/docs/api/qiskit/qiskit.quantum_info.SparseObservable) does not, which is why the example below
names [`compose()`](https://quantum.cloud.ibm.com/docs/api/qiskit/qiskit.quantum_info.SparseObservable#compose) explicitly; a type with an
`__and__` (such as [`SparsePauliOp`](https://quantum.cloud.ibm.com/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp)) can rely on the default.

#### NOTE
The mapping written out below is a deliberately minimal illustration of this function, not a
replacement for [`transfer_vertex_jordan_wigner()`](qiskit_fermions.mappers.library.transfer_vertex_jordan_wigner.html.md#qiskit_fermions.mappers.library.transfer_vertex_jordan_wigner): it covers only nearest-neighbor
interactions, and it is neither parallelized nor memory-bounded. Reach for the library
function rather than copying this one.

```pycon
>>> from qiskit_fermions.mappers import map_transfer_vertex_generators
>>> from qiskit_fermions.operators import TransferAction, TransferVertexOperator
>>> from qiskit.quantum_info import SparseObservable
>>>
>>> def jordan_wigner_nearest_neighbor(mode: TransferAction) -> SparseObservable:
...     left, right = mode
...     if left == right:
...         return SparseObservable.from_sparse_list(
...             [("Z", [left], 1.0)], num_qubits=num_qubits
...         )
...     if abs(left - right) != 1:
...         raise NotImplementedError(
...             "This mapping only handles nearest neighbor interactions"
...         )
...     # `T_lr` and `T_rl` differ, so the orientation must be compared rather than
...     # differenced. The coefficient is -1/2 either way; the Pauli letters swap instead.
...     lo, hi = min(left, right), max(left, right)
...     pauli = "XX" if left < right else "YY"
...     return SparseObservable.from_sparse_list(
...         [(pauli, [lo, hi], -0.5)], num_qubits=num_qubits
...     )
>>>
>>> num_qubits = 4
>>> def identity() -> SparseObservable:
...     return SparseObservable.identity(num_qubits)
>>>
>>> op = TransferVertexOperator.from_dict({
...     ((0, 0),): 2.0,
...     ((0, 1),): 0.5,
...     ((1, 1), (1, 2)): 1.0,
... })
>>> qop = map_transfer_vertex_generators(
...     op, jordan_wigner_nearest_neighbor, identity, compose=SparseObservable.compose
... )
>>> print(sorted(qop.simplify().to_sparse_list()))
[('XX', [0, 1], (-0.25+0j)), ('YX', [1, 2], -0.5j), ('Z', [0], (2+0j))]
```

* **Parameters:**
  * **operator** ([*TransferVertexOperator*](qiskit_fermions.operators.TransferVertexOperator.html.md#qiskit_fermions.operators.TransferVertexOperator)) – the operator to be mapped.
  * **map_action** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable) *[* *[*[*tuple*](https://docs.python.org/3/builtins/stdtypes.html#tuple) *[*[*int*](https://docs.python.org/3/builtins/functions.html#int) *,* [*int*](https://docs.python.org/3/builtins/functions.html#int) *]* *]* *,* *T* *]*) – the function to map a single [`TransferAction`](qiskit_fermions.operators.transfer_action.TransferAction.html.md#qiskit_fermions.operators.transfer_action.TransferAction) to the desired
    output type.
  * **identity** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable) *[* *[* *]* *,* *T* *]*) – the function to generate the multiplicative identity instance of the output type.
  * **compose** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable) *[* *[**T* *,* *T* *]* *,* *T* *]*  *|* *None*) – an optional function to implement the compositiion logic of two output type
    instances. If this is not provided, it will default to using [`operator.and_()`](https://docs.python.org/3/library/operator.html#operator.and_).
* **Returns:**
  The mapped operator.
* **Return type:**
  *T*