|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/quantum/blob/v0.7.6/tensorflow_quantum/datasets/spin_system.py#L562-L820) |

2D transverse field Ising-model quantum data set.

    tfq.datasets.spin_system.tfi_rectangular(
        qubits, boundary_condition='torus', data_dir=None
    )

\\\[
H = - \\sum_{\\langle i,j
angle} \\sigma_i\^z \\sigma_{j}\^z - g\\sigma_i\^x
\\\]

Contains 51 circuit parameterizations corresponding to
the ground states of the 2D TFI chain for g in \[2.5,3.5\].
This dataset contains 51 datapoints. Each datapoint is represented by a
circuit ([`cirq.Circuit`](https://quantumai.google/reference/python/cirq/Circuit)), a label (Python `float`) a Hamiltonian
([`cirq.PauliSum`](https://quantumai.google/reference/python/cirq/PauliSum)) and some additional metadata. Each Hamiltonian in a
datapoint is a 2D TFI rectangular lattice with boundary condition
`boundary_condition` on `qubits` whos order parameter dictates the value of
label. The circuit in a datapoint prepares (an approximation to) the ground
state of the Hamiltonian in the datapoint.

#### Example usage:

    qbs = cirq.GridQubit.rect(9, 1)
    circuits, labels, pauli_sums, addinfo  =
        tfq.datasets.tfi_rectangular(qbs, "torus")

You can print the available order parameters

    [info.g for info in addinfo]
    [2.5, 2.52, 2.54, ... ,3.46 , 3.48, 3.5]

and the circuit corresponding to the ground state for a certain order
parameter

    print(circuits[10])
                       ┌──────────────────────┐   ┌───────────────────── ...
    (0, 0): ───H────ZZ─────────────────────────ZZ─────────────────────── ...
                    │                          │
    (1, 0): ───H────ZZ^0.948896────────────────┼──────────ZZ──────────── ...
                                               │          │
    (2, 0): ───H────ZZ─────────────────────────┼──────────┼───────────── ...
                    │                          │          │
    (3, 0): ───H────┼──────────ZZ──────────────┼──────────┼───────────── ...
       .            .                          .          .
       .            .                          .          .

The labels indicate the phase of the system

    >>> labels[10]
    0

Additionally, you can obtain the [`cirq.PauliSum`](https://quantumai.google/reference/python/cirq/PauliSum) representation of the
Hamiltonian

    print(pauli_sums[10])
    -2.700*X((0, 0))-2.700*X((1, 0))-2.700*X((2, 0))-2.700*X((3, 0))-
    2.700*X((4, 0))-2.700*X((5, 0))-2.700*X((6, 0))-2.700*X((7, 0))- ...
    -1.000*Z((3, 0))*Z((6, 0))-1.000*Z((4, 0))*Z((5, 0))

The fourth output, `addinfo`, contains additional information
about each instance of the system (see `tfq.datasets.spin_system.SpinSystem`
).

For instance, you can print the ground state obtained from
exact diagonalization

    addinfo[10].gs
    [-0.11843355-0.30690906j -0.04374221-0.11335368j -0.04374221-0.11335368j
     -0.02221491-0.0575678j  -0.04374221-0.11335368j -0.02221491-0.0575678j

     -0.04374221-0.11335368j -0.02221491-0.0575678j  -0.04374221-0.11335368j
     -0.04374221-0.11335368j -0.11843355-0.30690906j]

with corresponding ground state energy

    addinfo[10].gs_energy
    -26.974953331962762

You can also inspect the parameters

    addinfo[10].params
    {'theta_0': 0.948896, 'theta_1': 0.90053445, ...
    'theta_8': 0.76966083, 'theta_9': 0.87608284}

and change them to experiment with different parameter values by using
the unresolved variational circuit returned by tfichain

    >>> new_params = {}
    ... for symbol_name, value in addinfo[10].params.items():
    ...    new_params[symbol_name] = 0.5 * value
    >>> new_params
    {'theta_0': 0.47444799542427063, 'theta_1': 0.4502672255039215, ...
    'theta_8': 0.38483041524887085, 'theta_9': 0.43804141879081726}
    >>> new_circuit = cirq.resolve_parameters(addinfo[10].var_circuit,
    ... new_params)
    >>> print(new_circuit)
                       ┌──────────────────────┐   ┌───────────────────── ...
    (0, 0): ───H────ZZ─────────────────────────ZZ─────────────────────── ...
                    │                          │
    (1, 0): ───H────ZZ^0.474───────────────────┼──────────ZZ──────────── ...
                                               │          │
    (2, 0): ───H────ZZ─────────────────────────┼──────────┼───────────── ...
                    │                          │          │
    (3, 0): ───H────┼──────────ZZ──────────────┼──────────┼───────────── ...
       .            .                          .          .
       .            .                          .          .

<br />

<br />

<br />

| ## Args ||
|---|---|
| `qubits` | Python `lst` of [`cirq.GridQubit`](https://quantumai.google/reference/python/cirq/GridQubit)s. Supported number of spins are \[9, 12, 16\]. |
| `boundary_condition` | Python `str` indicating the boundary condition of the chain. Supported boundary conditions are \["torus"\]. |
| `data_dir` | Optional Python `str` location where to store the data on disk. Defaults to `/tmp/.keras`. |

<br />

<br />

<br />

| ## Returns ||
|---|---|
| A Python `lst` cirq.Circuit of depth ceil(len(qubits) / 2) with resolved parameters. A Python `lst` of labels, 0, for the phase (`g<3.04`), 1 for the critical point (`g==3.04`) and 2 for the phase (`g>3.04`). A Python `lst` of [`cirq.PauliSum`](https://quantumai.google/reference/python/cirq/PauliSum)s. A Python `lst` of `namedtuple` instances containing the following fields: <br /> - `g`: Numpy `float` order parameter. - `gs`: Complex `np.ndarray` ground state wave function from exact diagonalization. - `gs_energy`: Numpy `float` ground state energy from exact diagonalization. - `res_energy`: Python `float` residual between the circuit energy and the exact energy from exact diagonalization. - `fidelity`: Python `float` overlap between the circuit state and the exact ground state from exact diagonalization. - `params`: Dict with Python `str` keys and Numpy`float` values. Contains \\(M imes P \\) parameters. Here \\(M\\) is the number of parameters per circuit layer and \\(P\\) the circuit depth. - `var_circuit`: Variational [`cirq.Circuit`](https://quantumai.google/reference/python/cirq/Circuit) quantum circuit with unresolved Sympy parameters. ||

<br />