Hubungan paket ini dengan ffsim

Penting

Konsep-konsep dalam panduan ini hanya tersedia di Python API.

ffsim dan paket ini membagi pekerjaan, bukan saling tumpang tindih, dengan satu garis pemisah:

ffsim memegang	qiskit-fermions memegang
Operator ansatz tingkat tinggi (UCJOpSpinBalanced, UCCSDOpRestrictedReal dan kerabatnya), yang dibangun dari amplitudo coupled-cluster atau vektor parameter	Circuit fermionik (FermionicCircuit) yang menjadi wujud operator-operator itu, dan transpilasinya menjadi circuit qubit di bawah encoding fermion-ke-qubit apa pun
Simulasi cepat dalam ruang jumlah partikel tetap yang ringkas	Kerangka mapper dan struktur data operator yang menjadi bahan pembangun circuit

Konsekuensi praktisnya berlaku dua arah. Matematika ansatz ada di ffsim, jadi UCJ dan UCC menerima operator ffsim langsung sebagai inputnya. Sebaliknya, gate Qiskit milik ffsim sendiri khusus untuk transformasi Jordan-Wigner, jadi manfaat membawa salah satu operator ansatz-nya ke sini adalah bisa menurunkannya lewat encoding yang berbeda.

Simulasi adalah titik temu keduanya, dan panduan ini menjelaskan caranya. ffsim adalah backend simulasi paket ini, dijangkau lewat protokolnya sendiri, bukan lewat wrapper: panduan SKQD memanggil ffsim.apply_unitary(), ffsim.linear_operator(), dan ffsim.sample_state_vector() langsung pada objek FermionicCircuit dan objek FermionOperator, tanpa langkah konversi.

Terhubung ke antarmuka simulasi ffsim

ffsim adalah simulator berkinerja tinggi untuk circuit kuantum fermionik yang memanfaatkan kekekalan jumlah partikel dan spin-Z untuk merepresentasikan state vector lebih ringkas daripada statevector qubit generik berdimensi $2^n$. ffsim mendefinisikan protokol yang bisa diimplementasikan objek apa pun agar ikut serta dalam mesin simulasinya (lihat qiskit_fermions.protocols untuk protokol milik paket ini sendiri, yang mengikuti desain yang sama):

• ffsim.SupportsApplyUnitary, lewat metode _apply_unitary_(vec, norb, nelec, copy), yang menerapkan objek sebagai uniter ke state vector dengan jumlah partikel tetap

• ffsim.SupportsLinearOperator, lewat metode _linear_operator_(norb, nelec), yang mengembalikan tampilan scipy.sparse.linalg.LinearOperator dari objek pada sektor yang sama

• ffsim.SupportsTrace, lewat metode _trace_(norb, nelec), yang mengembalikan trace objek pada sektor itu.

Paket ini mengimplementasikan antarmuka tersebut: setiap gate fermionik di qiskit_fermions.circuit.library menyediakan _apply_unitary_, dan FermionOperator menyediakan _linear_operator_ dan _trace_. Itulah yang membuat operator dan circuit paket ini kompatibel dengan ffsim, sehingga perangkatnya bekerja secara native pada keduanya, tanpa langkah konversi. ffsim.apply_unitary() bisa mensimulasikan FermionicCircuit dari ujung ke ujung, ffsim.linear_operator() bisa mendiagonalisasi FermionOperator, dan utilitas sampling seperti ffsim.sample_state_vector() (dipakai di panduan SKQD untuk mengubah statevector hasil simulasi menjadi counts pengukuran) bekerja tanpa modifikasi.

Yang dikembalikan _linear_operator_ adalah LinearOperator SciPy biasa, jadi scipy.sparse.linalg.eigsh() dan fungsi sejenis juga bisa dipakai padanya.

>>> import ffsim
>>> import numpy as np
>>>
>>> from qiskit_fermions.circuit import FermionicCircuit
>>> from qiskit_fermions.circuit.library import Evolution
>>> from qiskit_fermions.operators import FermionOperator, ann, cre
>>>
>>> norb, nelec = 2, (1, 1)
>>> hamiltonian = FermionOperator.from_terms([
...     ([cre(0), ann(1)], 0.5),
...     ([cre(1), ann(0)], 0.5),
... ])
>>>
>>> circuit = FermionicCircuit(2 * norb)
>>> circuit.append(Evolution(2 * norb, hamiltonian, time=1.0), circuit.modes)
>>>
>>> reference = ffsim.hartree_fock_state(norb, nelec)
>>> state = ffsim.apply_unitary(reference, circuit, norb=norb, nelec=nelec)  # native ffsim call

Keuntungan dari penggabungan lewat protokol ffsim adalah ini: ekosistem utilitas simulasi dan sampling-nya yang aktif dikembangkan berlaku untuk circuit dan operator paket ini tanpa perubahan, dan pengguna yang sudah memakai ffsim bisa mencampurkan gate dan operator paket ini tanpa perlu mempelajari API simulasi lain.

ffsim adalah dependensi opsional

ffsim dideklarasikan sebagai extra opsional (pip install "qiskit-fermions[ffsim]", atau secara transitif lewat [all]), dijaga saat runtime oleh HAS_FFSIM (seperti yang ditunjukkan di atas). Memasangnya membuka kemampuan simulasi: ffsim.SupportsLinearOperator dan ffsim.SupportsTrace diimplementasikan dengan mengonversi FermionOperator milik paket ini menjadi ffsim.FermionOperator, sehingga tanpa ffsim keduanya memunculkan MissingOptionalLibraryError. Semua yang tidak melakukan simulasi (membangun operator, memetakannya, dan mentranspilasi circuit hasilnya) tidak membutuhkannya sama sekali.

Simulasi fermionik berlangsung di sektor jumlah partikel tetap

Baik _apply_unitary_ maupun _linear_operator_ menerima argumen nelec dan merepresentasikan state vector di atas basis determinan jumlah-partikel-tetap untuk sektor (norb, nelec) itu, meniru setup ruang FCI milik ffsim (dan, secara transitif, PySCF), bukan ruang berdimensi $2^{\text{num\_modes}}$ penuh yang dipakai simulator qubit umum. Ruang ini jauh lebih kecil (ukurannya hasil kali koefisien binomial, bukan pangkat dua), tetapi datang dengan batasan keras. Hanya operator dan gate yang mempertahankan jumlah partikel (dan, pada kasus berspin, jumlah partikel tiap spesies spin secara terpisah) yang bisa direpresentasikan di dalamnya. Operator yang aksinya akan memindahkan amplitudo ke jumlah partikel berbeda tidak punya tempat untuk menaruhnya.

ffsim menyelesaikannya dengan menolak operator semacam itu sama sekali: mengonversinya menjadi linear operator memunculkan ValueError yang menyebutkan hukum kekekalan mana yang gagal. Itu default yang tepat, karena menerapkan $\exp(-i t H)$ untuk Hamiltonian $H$ dengan suku yang tidak mempertahankan jumlah partikel akan mengubah sesuatu yang seharusnya uniter menjadi peta non-uniter yang tidak bermakna secara fisik.

• Evolution meneruskan penolakan itu dari operator yang dievolusikannya.

• OrbitalRotation memeriksa bahwa matriks rotasinya (yang di-embed) berbentuk blok-diagonal di seluruh pembagian alpha/beta pada kasus spinful, dan memunculkan ValueError kalau matriks itu mencampur sektor spin.

>>> from qiskit_fermions.circuit.library import Evolution
>>>
>>> non_conserving = FermionOperator.from_terms([([cre(0), cre(1)], 1.0)])  # creates 2 particles
>>> gate = Evolution(2 * norb, non_conserving, time=1.0)
>>>
>>> try:
...     gate._apply_unitary_(reference, norb, nelec, copy=True)
... except ValueError as exc:
...     print("rejected:", exc)
rejected: The given FermionOperator could not be converted to a LinearOperator because it does not conserve particle number and the z component of spin. Conserves particle number: False Conserves spin z: False

Jadi, simulasi yang tidak menjaga jumlah partikel mustahil dilakukan di ruang fermionik, karena representasi sektor tetap memang dibuat begitu, dan itulah harga dari ruang FCI yang ringkas, yang sejak awal membuat simulasi fermionik jadi bisa dikerjakan. Kalau algoritmamu butuh operator yang melanggar jumlah partikel (misalnya error channel yang native ke qubit, atau operator yang dibuat untuk Hamiltonian hasil mapping yang tidak menjaga jumlah partikel suku demi suku), transpile dulu ke qubit lalu simulasikan QuantumCircuit yang dihasilkan dengan simulator tingkat qubit. Rute transpilasi apa pun bisa dipakai untuk ini; panduan fermionic circuit dan transpilasi membahasnya lebih detail, tapi generate_preset_jw_pass_manager() adalah pilihan default yang masuk akal.

Konvensi block-spin untuk sistem spinful

nelec bertipe int | tuple[int, int], dan tipenya, bukan flag terpisah, yang menentukan salah satu layout mode yang didukung:

• Sebuah int memilih interpretasi spinless. norb mode diperlakukan langsung sebagai orbital spinless, dan nelec adalah jumlah total partikel.

• Sebuah pasangan (n_alpha, n_beta) memilih interpretasi spinful untuk 2 * norb mode dengan konvensi block-spin yang tetap. Mode 0 .. norb adalah orbital alpha (spin-up) dan mode norb .. 2 * norb adalah orbital beta (spin-down). Tiap spesies spin terjaga secara independen; suku khusus alpha bisa memindahkan elektron antar mode alpha tapi tidak pernah ke mode beta, dan sebaliknya.

Dispatch ini terjadi di setiap entry point protokol ffsim di package ini (konstruktor gate, implementasi _apply_unitary_placed_, dan kompilasi sektor kernel Rust native), dan ini adalah konvensi yang dipakai di seluruh panduan LUCJ dan SKQD (misalnya, InitializeModes.from_hartree_fock() mengisi okupasi alpha ke mode 0 .. n_alpha dan okupasi beta ke mode norb .. norb + n_beta). Ini patut dibandingkan dengan modul qiskit_fermions.operators dan FermionicCircuit secara umum, yang memakai indeks mode generik tanpa makna spin bawaan (lihat panduan fermionic circuit). Makna block-spin baru diberlakukan saat nelec spinful diberikan ke pemanggilan simulasi, bukan tertanam di representasi operator atau circuit itu sendiri.

>>> from qiskit_fermions.circuit.library import InitializeModes
>>>
>>> norb, nelec = 3, (2, 1)
>>> init = InitializeModes.from_hartree_fock(norb, nelec)
>>> print([bool(occ) for occ in init.occupation])  # alpha modes 0,1; beta mode 3 (= norb + 0)
[True, True, False, True, False, False]

Langkah berikutnya

• Ikuti panduan SKQD untuk melihat ffsim.apply_unitary() dan ffsim.sample_state_vector() dipakai bersama untuk men-sampling circuit yang dibangun dari gate package ini, dan untuk mengevaluasi nilai ekspektasi Hamiltonian lewat ffsim.linear_operator() (yang sendirinya didukung oleh metode protokol _linear_operator_ yang sama seperti dijelaskan di sini).

• Ikuti panduan LUCJ untuk separuh cerita lainnya: membawa operator ansatz ffsim melewati pipeline transpilasi package ini sampai ke coupling map perangkat.

• Baca panduan fermionic circuit untuk indeks mode generik yang tidak peduli spin, yang dipakai di luar pemanggilan simulasi.

• Baca panduan transpilasi untuk tahu cara keluar dari ruang fermionik

  dan simulasi pada qubit, yang wajib untuk operator yang tidak menjaga jumlah partikel.

• Telusuri qiskit_fermions.protocols untuk katalog lengkap protokol yang didefinisikan package ini, termasuk protokol konversi (SupportsFermionOperator, SupportsMajoranaOperator) yang tidak ada hubungannya dengan ffsim.

• Baca panduan ffsim sendiri untuk workflow yang jadi tanggung jawabnya, terutama membangun ansatz UCJ dan mengoptimalkannya secara variasional. Vektor parameter yang dikendalikan panduan-panduan itu adalah yang diterima oleh UCJ dan UCC, lewat operator yang mereka bangun.