def test_spin2(electrons, orbitals, mapping, terms_exp, monkeypatch):
r"""Tests the correctness of the total spin observable :math:`\hat{S}^2`
built by the function `'spin2'`.
The parametrized inputs are `.terms` attribute of the total spin `QubitOperator.
The equality checking is implemented in the `qchem` module itself as it could be
something useful to the users as well.
"""
S2 = qchem.spin2(electrons, orbitals, mapping=mapping)
S2_qubit_op = QubitOperator()
monkeypatch.setattr(S2_qubit_op, "terms", terms_exp)
assert qchem._qubit_operators_equivalent(S2_qubit_op, S2)
def test_exception_spin2(electrons, orbitals, msg_match):
"""Test that the function `'spin2'` throws an exception if the
number of electrons or the number of orbitals is less than zero."""
with pytest.raises(ValueError, match=msg_match):
qchem.spin2(electrons, orbitals)
# In the equation above, :math:`N_e` is the number of active electrons,
# :math:`\hat{c}` and :math:`\hat{c}^\dagger` are respectively the electron annihilation and
# creation operators, and
# :math:`\langle \alpha, \beta \vert \hat{s}_1 \cdot \hat{s}_2 \vert \gamma, \delta \rangle`
# is the matrix element of the two-particle spin operator
# :math:`\hat{s}_1 \cdot \hat{s}_2` in the basis of Hartree-Fock *spin* orbitals
# [#fetterbook]_. The :math:`\mathrm{H}_2` molecule has two electrons that populate,
# within the minimal basis set approximation, four *spin* orbitals. As a reminder, the
# variable ``qubits`` output by the :func:`~.pennylane_qchem.qchem.molecular_hamiltonian`
# above stores the number of spin orbitals included the basis.
#
# In order to build the spin operator :math:`\hat{S}^2` we call the
# :func:`~.pennylane_qchem.qchem.spin2` function.
electrons = 2
S2 = qchem.spin2(electrons, qubits, mapping="jordan_wigner")
print(S2)
##############################################################################
# The :func:`~.pennylane_qchem.qchem.spin2` function uses
# :func:`~.pennylane_qchem.qchem._spin2_matrix_elements` and
# :func:`~.pennylane_qchem.qchem.observable` to compute the
# matrix elements in the equation above and to build the many-body observable,
# respectively.
#
# .. note::
#
# The :func:`~.pennylane_qchem.qchem.observable` function can be used to build any
# many-body observable as long as we have access to the matrix elements of the
# one- and/or two-particle operators in the basis of single-particle states.