Mag-migrate mula sa server-side patungo sa client-side na Sampler at Estimator

Inilalarawan ng gabay na ito kung paano mag-migrate mula sa server-side na implementasyon ng IBM Quantum® Sampler at Estimator patungo sa kanilang bagong client-side na implementasyon sa qiskit-ibm-runtime. Ang mga interface at opsyon ay karamihan hindi nagbago, kaya karamihan sa code ay tatakbo nang as-is, ngunit may ilang pagkakaiba sa behavior na dapat unawain.

Kaligiran

Ang Sampler at Estimator ay primitive interface na tinukoy sa Qiskit. Ang IBM Quantum Compute Service (dating Qiskit Runtime) ay tradisyunal na nagbibigay ng implementasyon ng mga primitive na ito sa loob ng runtime environment nito. Kapag tinawag mo ang sampler.run() o estimator.run(), ipinapadala ang request sa service, at lahat ng computation — kabilang ang error suppression at mitigation — ay nagaganap sa server side.

Maginhawa ang black-box na karanasan na ito: hindi mo na kailangang alalahanin ang mga detalye ng implementasyon. Ngunit dahil dito, mahirap ding i-debug, i-customize, o pag-aralan ang mga primitive, dahil hindi mo makikita kung ano ang nangyayari sa panahon ng processing.

Ang bagong ipinakilalang directed execution model ay gumagamit ng kabaligtarang approach at nagbibigay ng white-box na karanasan. Ang lahat ng design intent ay nakukuha sa client side, at isang solong server-side na primitive Executor ang nagpoproseso ng mga input na iyon nang eksakto ayon sa direksyon — hindi ito gumagawa ng anumang implicit na desisyon para sa iyo.

Simula sa qiskit-ibm-runtime v0.50.0, ang Sampler at Estimator ay muling naipatupad sa client side sa ibabaw ng Executor. Nagbibigay pa rin sila ng parehong convenience at abstraction gaya ng dati, at ngayon ay maaari mo nang suriin ang mga detalye ng implementasyon kapag kailangan mo ito. Dahil ang mga interface at opsyon ay karamihan hindi nagbago, dapat na maayos at walang aberya ang migration.

Tandaan: Sinusuportahan lang ng IBM Quantum ang version 2 ng Sampler at Estimator interface (BaseSamplerV2 at BaseEstimatorV2). Kaya, tinutukoy lang sila bilang Sampler at Estimator sa gabay na ito.

I-update ang mga import

Sa ngayon, kailangan mong explicit na i-import ang mga bagong implementasyon mula sa kani-kanilang dedicated module:

from qiskit_ibm_runtime.executor_sampler import Sampler
from qiskit_ibm_runtime.executor_estimator import Estimator

Sa malapit na hinaharap, ang mga top-level na import ay mare-resolve na sa bagong client-side na implementasyon, at hindi na kakailanganin ang pagbabago sa code:

# Coming soon — the following code will import the new client-side implementations.
from qiskit_ibm_runtime import Sampler, Estimator

Gayundin, kung gagawa ka ng typed options object, kailangan mo itong i-import mula sa qiskit_ibm_runtime.options_models sa halip, o mag-pasa lang ng plain nested dict:

from qiskit_ibm_runtime.options_models import SamplerOptions, EstimatorOptions

Ano ang nananatiling pareho

Ang paggawa ng primitive gamit ang mode at options.
Ang run() signature at PUB format.
Ang options tree (options.twirling, options.resilience, options.default_shots, at iba pa).
Ang result data structure na ibinabalik ng job.result().

Mga hindi compatible na pagbabago sa bagong Sampler

Pagbabago	Aksyon sa migration
Ang underlying primitive ngayon ay Executor. Ipapakita ng parehong IBM Quantum Platform user interface at `job.primitive_id` ang `executor` sa halip na `sampler`.	I-update ang anumang code na tumutukoy sa `job.primitive_id`.
Ang bagong implementasyon ay nag-ma-map ng mga Sampler input patungo sa Executor input, kaya ang `job.inputs` ay nagbabalik ng Executor input.	I-update ang anumang code na tumutukoy sa `job.inputs`. Tingnan ang Mga input ng job.
Mas maraming pre- at post-processing ang nagaganap na ngayon sa client side, kaya ang `sampler.run()` at `job.result()` ay maaaring tumagal nang mas matagal kaysa dati.	I-enable ang INFO logging para sundan ang progress ng client-side processing. Tingnan ang I-enable ang INFO logging.
Kinokopya ang circuit metadata sa result metadata. Ang mga data type na pinapayagan sa result metadata ay limitado na ngayon sa `str`, `float`, `int`, `bool`, at mga lists o dictionaries ng mga type na iyon.	Kung kailangan mo ng ibang data type, i-encode muna ito bilang string (halimbawa, gamit ang base64).
Ang mga options class (`options_models.SamplerOptions` at iba pa) ay Pydantic models na ngayon sa halip na dataclasses, kaya hindi na ito maaaring i-convert sa Python dictionaries gamit ang `asdict()`.	Gamitin na lang ang `options.model_dump()`.
Ang mga options class na dati ay may `V2` suffix (`ExecutionOptionsV2` at iba pa) ay wala na nito, dahil hindi na sinusuportahan ang mga V1 primitive.	Alisin ang `V2` suffix ng mga options class na ito: palitan ang `ExecutionOptionsV2` ng `ExecutionOptions`, `ResilienceOptionsV2` ng `ResilienceOptions`, at `SamplerExecutionOptionsV2` ng `SamplerExecutionOptions`.
Kung naka-enable ang `twirling` at ang `shots` (sa mga PUB o sa `run()`), `shots_per_randomization`, at `num_randomizations` ay lahat na-specify, ang `num_randomizations * shots_per_randomization` ang mananaig kaysa sa `shots`.	Alisin ang `num_randomizations` at `shots_per_randomization` kung gusto mong gamitin ang value ng `shots`.
Ang ilang input validation ay inilipat na sa server side at nagbibigay na ngayon ng `RuntimeError` sa halip na `IBMInputValueError`.	I-update ang mga exception type na hinuhuli ng iyong code.
Hindi na sinusuportahan ang mixed shot values sa iisang job.	Mag-submit ng hiwalay na job para sa bawat shot value. Tingnan ang Paghahati ng job para sa mga dapat isaalang-alang.

Mga hindi compatible na pagbabago sa bagong Estimator

Pagbabago	Aksyon sa migration
Ang underlying primitive ngayon ay Executor. Ipapakita ng parehong IBM Quantum Platform user interface at `job.primitive_id` ang `executor` sa halip na `estimator`.	I-update ang anumang code na tumutukoy sa `job.primitive_id`.
Ang bagong implementasyon ay nag-ma-map ng mga Estimator input patungo sa Executor input, kaya ang `job.inputs` ay nagbabalik ng Executor input.	I-update ang anumang code na tumutukoy sa `job.inputs`. Tingnan ang Mga input ng job.
Mas maraming pre- at post-processing ang nagaganap na ngayon sa client side, kaya ang `estimator.run()` at `job.result()` ay maaaring tumagal nang mas matagal kaysa dati.	I-enable ang INFO logging para sundan ang progress ng client-side processing. Tingnan ang I-enable ang INFO logging.
Kinokopya ang circuit metadata sa result metadata. Ang mga data type na pinapayagan sa result metadata ay limitado na ngayon sa `str`, `float`, `int`, `bool`, at mga lists o dictionaries ng mga type na iyon.	Kung kailangan mo ng ibang data type, i-encode muna ito bilang string (halimbawa, gamit ang base64).
Ang mga options class (`options_models.EstimatorOptions` at iba pa) ay Pydantic models na ngayon sa halip na dataclasses, kaya hindi na ito maaaring i-convert sa Python dictionaries gamit ang `asdict()`.	Gamitin na lang ang `options.model_dump()`.
Ang mga options class na dati ay may `V2` suffix (`ExecutionOptionsV2` at iba pa) ay wala na nito, dahil hindi na sinusuportahan ang mga V1 primitive.	Alisin ang `V2` suffix ng mga options class na ito: palitan ang `ExecutionOptionsV2` ng `ExecutionOptions` at ang `ResilienceOptionsV2` ng `ResilienceOptions`.
Ang lahat ng input options ay ibinabalik sa result metadata, sa halip na isang piling subset.	Wala — ito ay impormasyon lamang.
Ang ilang input validation ay inilipat na sa server side at nagbibigay na ngayon ng `RuntimeError` sa halip na `IBMInputValueError`.	I-update ang mga exception type na hinuhuli ng iyong code.
Wala nang implicit na noise learning para sa PEA at PEC. Sinusuportahan pa rin ang measurement noise learning para sa TREX.	Matutunan ang mga noise model nang hiwalay at ipasa ang mga ito sa Estimator. Tingnan ang Magsagawa ng explicit na noise learning para sa PEA at PEC.
Ang input type ng `ResilienceOptions.layer_noise_model` ay iba na at maaaring gawin mula sa mga resulta ng `NoiseLearnerV3`.	Tingnan ang Magsagawa ng explicit na noise learning para sa PEA at PEC kung paano matutunan ang mga noise model gamit ang `NoiseLearnerV3` at ipasa ang mga ito sa Estimator.
Hindi na sinusuportahan ang `MeasureNoiseLearningOptions.shots_per_randomization`.	Isang solong shot value ang ginagamit para sa lahat ng circuit sa job, kabilang ang mga circuit para sa measurement noise-learning. Kung kailangan mong gumamit ng ibang shot value, i-apply ang TREX gamit ang `qiskit-mitigation` sa labas ng Estimator.
Hindi na sinusuportahan ang mixed precision values sa iisang job.	Mag-submit ng hiwalay na job para sa bawat gustong precision. Tingnan ang Paghahati ng job para sa mga dapat isaalang-alang.
Hindi na sinusuportahan ang opsyong `seed_estimator`.	Alisin ang anumang assignment ng `options.seed_estimator` (ang pag-set nito ay nagbibigay ng `ValidationError`). Walang katumbas dito sa client side, kaya hindi na maaaring gawing reproducible ang mga resulta gamit ang seed na ito.

I-enable ang INFO logging

Dahil mas maraming trabaho na ngayon ang nagaganap sa client side, kapaki-pakinabang na makita ang progress ng processing na iyon. I-enable ang INFO-level logging para sa qiskit_ibm_runtime logger:

import logging

logger = logging.getLogger("qiskit_ibm_runtime")
logger.setLevel(logging.INFO)

Magsagawa ng explicit na noise learning para sa PEA at PEC

Ang bagong Estimator ay hindi na nagsasagawa ng implicit na noise learning kapag pinili ang error mitigation method na PEA o PEC. Kailangan mong matutunan ang mga noise model nang explicit at ipasa ang mga ito. Gamitin ang bagong NoiseLearnerV3 para kontrolin kung paano na-stratify ang mga circuit sa mga layer. Kumukuha ito ng listahan ng mga boxed circuit instruction (halimbawa, ang mga unique layer) bilang input.

Mahalaga

Kinakailangan na ngayon ng PEA at PEC ang explicit na pattern na ito. Huwag laktawan ang hakbang ng noise-learning o mabibigo ang iyong code. Hindi apektado ang measurement noise learning para sa TREX at patuloy itong gumagana gaya ng dati.

Gayundin, kung ang iyong code ay gumagamit ng NoiseLearner at ipinapasa ang resultang noise model sa server-side na Estimator, kailangan mong mag-migrate patungo sa NoiseLearnerV3. HUWAG gamitin ang mas lumang NoiseLearner, na hindi compatible sa bagong Estimator.

Lahat ng noise learning options sa server-side na Estimator (LayerNoiseLearningOptions) ay direktang naka-map sa opsyon ng NoiseLearnerV3 (NoiseLearnerV3Options), maliban sa max_layers_to_learn. Sa halip, ang bilang ng mga layer na matututunan ay batay sa bilang ng mga layer na ipinasa sa NoiseLearnerV3.

Halimbawa:

Server-side Estimator (na naka-enable ang PEC):

from qiskit_ibm_runtime import Estimator

pubs = [...]  # Your PUBs
estimator = Estimator(mode, options)
estimator.options.resilience.pec_mitigation = True  # or zne_mitigation + pea amplifier
estimator.options.resilience.layer_noise_learning.num_randomizations = 64

job = estimator.run(pubs)

Client-side Estimator (na naka-enable ang PEC):

from qiskit_ibm_runtime.executor_estimator import Estimator
from qiskit_ibm_runtime import NoiseLearnerV3

pubs = [...]  # Your PUBs
estimator = Estimator(mode, options)
estimator.options.resilience.pec_mitigation = True  # or zne_mitigation + pea amplifier

# Identify the unique layers to learn.
layers = estimator.find_unique_layers(pubs)

# Learn the noise model for those layers (runs as a separate job).
learner = NoiseLearnerV3(mode)
learner.options.num_randomizations = 64  # Same as layer_noise_learning.num_randomizations
learner_job = learner.run(layers)
learner_result = learner_job.result()

# Convert results to Pauli-Lindblad noise maps.
pauli_lindblad_maps = learner_result.to_pauli_lindblad_maps()

# Assign the learned noise maps so PEA/PEC uses them.
estimator.options.resilience.layer_noise_model = zip(layers, pauli_lindblad_maps)

# Now execute the target PUBs.
job = estimator.run(pubs)

Mag-migrate mula sa `NoiseLearner` patungo sa `NoiseLearnerV3`

Gumagana lang ang NoiseLearner kasama ang server-side na implementasyon ng Estimator. Kaya, kung ang iyong code ay gumagamit ng NoiseLearner para matutunan ang noise model at ipasa ito sa Estimator, kailangan mong i-update ang iyong code para gamitin ang NoiseLearnerV3.

Tingnan ang gabay na Mag-migrate mula sa NoiseLearner patungo sa NoiseLearnerV3 para sa mga detalye.

Paghahati ng job

Kapag kinakailangan mong hatiin ang isang job sa ilan dahil hindi na sinusuportahan ang mixed shot o precision values sa iisang job, isaalang-alang ang mga sumusunod:

Pagsamahin ang mga PUB base sa kanilang target value — isang job bawat natatanging value, hindi isang job bawat PUB. Ang splitting ay isang regrouping, kaya hindi nagbabago ang kabuuang bilang ng mga PUB na isu-submit mo. Halimbawa, sa [A@0.01, B@0.05, C@0.01], mag-submit ng dalawang job: [A, C] sa precision=0.01 at [B] sa precision=0.05. Ang pag-submit ng A at C bilang magkahiwalay na job ay mas hindi episyente, dahil bawat job ay may fixed overhead.
Matuto nang isang beses at gamitin ang mga noise model sa lahat ng hinating job. Mas episyente na magpatakbo ng iisang NoiseLearnerV3 job sa union ng lahat ng layer. Ang resulta ng isang noise learner job ay naglalaman ng listahan ng mga NoiseLearnerV3Result object, isa para sa bawat input instruction, at nasa parehong pagkakasunod-sunod ng input list. Maaari mong gamitin ang output ng noise learner job na ito sa lahat ng hinating (Estimator) job, at ang mga noise model para sa mga layer na wala sa mga PUB ng isang hinating job ay babalewalain.
Isumite muna ang lahat ng hinating job sa isang Batch, saka kolektahin ang kanilang mga resulta. Ang Batch execution mode ay nagbibigay ng episyenteng parallel execution kapag maraming job. Gayunpaman, ang job.result() ay blocking, kaya ang pagtawag dito sa loob ng submission loop ay nagse-serialize sa mga job at binabawi ang mga benepisyo ng paggamit ng Batch. Siguraduhing gamitin mo ang submit-all-then-collect na pattern (ipinapakita sa baba).

Sa sumusunod na halimbawa, kinakailangan ng pub1 at pub2 ang precision=0.5, samantalang kinakailangan ng pub3 ang precision=0.1:

group1_pubs = [pub1, pub2]
group2_pubs = [pub3]

with Batch(backend=backend) as batch:
    estimator = Estimator(mode=batch)
    estimator.options.resilience.pec_mitigation = True

    # Learn once, over the union of every job's layers.
    all_layers = estimator.find_unique_layers(group1_pubs + group2_pubs)
    learner_job = NoiseLearnerV3(mode=batch).run(all_layers)
    learner_result = learner_job.result()
    pauli_lindblad_maps = learner_result.to_pauli_lindblad_maps()

    # Assign the learned noise maps. Any layers not found in the input PUBs are ignored.
    estimator.options.resilience.layer_noise_model = zip(all_layers, pauli_lindblad_maps)

    # Submit every split job with different precision values.
    jobs = []
    jobs.append(estimator.run(group1_pubs, precision=0.5))
    jobs.append(estimator.run(group2_pubs, precision=0.1))

    # Block once, at the end — the jobs run in parallel.
    results = [job.result() for job in jobs]

Istruktura ng mga input ng job

Ang bagong implementasyon ay nag-ma-map ng mga input ng Sampler o Estimator patungo sa mga input ng Executor, kaya ang job.inputs ay nagbabalik ng dictionary na naglalaman ng mga input ng Executor. May sumusunod na keys ang dictionary na ito:

options: Ang input na ExecutorOption.
quantum_program: Ang input na QuantumProgram
schema_version: Ang server-side schema version na ginamit.

Kung ang iyong code ay gumamit ng job.inputs['options'] para hanapin ang mga opsyon na tinukoy para sa job, maaari mo na ngayong gamitin ang job.result().metadata['options'] sa halip.

Mag-test nang lokal gamit ang fake backend

Bago mag-submit sa hardware, maaari mong i-validate ang na-migrate na code laban sa Fake* na backend para maagap na mahuli ang anumang syntax error. Tandaan ang sumusunod na detalye tungkol sa local testing mode:

Hindi nito ginagaya ang mga resulta ng hardware. Ang local noisy simulation ay hindi perpektong gumagaya sa noise ng totoong device, kaya maaaring magkaiba ang mga output. Sinusuri pa rin ng pagpapatakbo kung tama ang mga option path at value type.
Ang NoiseLearnerV3 ay walang local testing mode: tinatanggap lang ng mode nito ang totoong Backend, Session, o Batch, kaya hindi mo masusubok ang hakbang ng noise-learning laban sa fake na backend. Sa halip, i-verify ang bahaging iyon ng iyong code laban sa NoiseLearnerV3 API reference. Kumpirmahin na ang constructor, ang input shape ng run(instructions), at anumang helper (tulad ng unique-layer helper) ay ginagamit ayon sa dokumentasyon.

I-Cliffordize ang circuit para sa episyenteng lokal na simulation

Ang fake backend ay gumagamit ng statevector (noisy) simulator, na ang gastos ay lumalaki nang exponential kasabay ng bilang ng qubit at lalim. Kaya, maaaring mag-hang o maubusan ng memory ang isang makatotohanang workload circuit. Dahil ang local testing ay kailangan lang na masubok ang mga option path (hindi kailangang gayahin ang pisikal na resulta), bawasan muna ang circuit sa isang Clifford na circuit gamit ang ConvertISAToClifford, na nagro-round ng bawat anggulo ng RZ/RZZ/RX sa pinakamalapit na multiple ng π/2. Ang mga Clifford circuit ay nagsi-simulate nang episyente (stabilizer simulation) anuman ang laki.

from qiskit.transpiler import PassManager
from qiskit_ibm_runtime.transpiler.passes import ConvertISAToClifford

clifford = PassManager([ConvertISAToClifford()]).run(isa_circuit)
# run `clifford` (not the original) through the fake-backend primitive

Kinakailangan ng ConvertISAToClifford ang isang ISA circuit bilang input (ang output ng generate_preset_pass_manager(...).run(...) na naka-target sa backend). Kailangan mong isaalang-alang ang sumusunod na konsekwensya kapag gumagawa ng lokal na PUB:

Naaalis ang .layout attribute. Pinapanatili ng Cliffordized na circuit ang parehong bilang ng qubit, ngunit ang clifford.layout ay None, kaya nabibigo ang observable.apply_layout(clifford.layout). Sa halip, i-layout ang observable mula sa pre-Clifford ISA na circuit: isa_obs = observable.apply_layout(isa_circuit.layout), saka patakbuhin ang (clifford, isa_obs).
Naaalis ang mga parameter. Ang pag-round sa mga anggulo ng rotation ay ginagawang concrete Clifford na circuit ang isang parametric na ISA circuit, kaya nagiging 0 ang clifford.num_parameters. Ang isang PUB na may dalang parameter-values array ay mabibigo sa coercion. Para sa lokal na run, alisin ang parameter array mula sa PUB; pinapanatili ng hardware run ang orihinal na parametric na circuit at ang mga value nito.

Mga susunod na hakbang

Mga rekomendasyon

Kaligiran​

I-update ang mga import​

Ano ang nananatiling pareho​

Mga hindi compatible na pagbabago sa bagong Sampler​

Mga hindi compatible na pagbabago sa bagong Estimator​

I-enable ang INFO logging​

Magsagawa ng explicit na noise learning para sa PEA at PEC​

Mag-migrate mula sa NoiseLearner patungo sa NoiseLearnerV3​

Paghahati ng job​

Istruktura ng mga input ng job​

Mag-test nang lokal gamit ang fake backend​

I-Cliffordize ang circuit para sa episyenteng lokal na simulation​

Mga susunod na hakbang​